Process assets Using media handlers and workflows processing-assets-using-media-handlers-and-workflows

CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

Adobe Experience Manager Assets provides a set of default workflows and media handlers to process assets. A workflow defines a typical asset management and processing task, then delegates the specific tasks to the media handlers, for example thumbnail generation or metadata extraction.

A workflow can be defined that automatically execute when an asset of a particular type or format is uploaded to the server. The processing steps are defined as a series of Experience ManagerAssets media handlers. Adobe Experience Manager provides some built in handlers, and more can be either custom developed or defined by delegating the process to a command-line tool.

Media handlers are services inside Experience Manager Assets that perform specific actions on assets. For example, when an MP3 audio file is uploaded into Experience Manager, a workflow triggers an MP3 handler that extracts the metadata and generates a thumbnail. Media handlers are used with workflows. Most common MIME types are supported within Experience Manager. You can perform specific tasks on assets by doing any of the following

  • Extending or creating workflows.
  • Extending or creating media handlers.
  • Disabling or enabling media handlers.
NOTE
See Assets supported formats page for a description of all the formats supported by Experience Manager Assets and features supported for each format.

Default media handlers default-media-handlers

The following media handlers are available within Experience Manager Assets and handle the most common MIME types:

Handler name
Service Name (in the System Console)
Supported MIME types
TextHandler
com.day.cq.dam.core.impl.handler.TextHandler
text/plain
PdfHandler
com.day.cq.dam.handler.standard.pdf.PdfHandler
  • application/pdf
  • application/illustrator
JpegHandler
com.day.cq.dam.core.impl.handler.JpegHandler
image/jpeg
Mp3Handler
com.day.cq.dam.handler.standard.mp3.Mp3Handler
audio/mpeg
Important - When you upload an MP3 file, it is processed using a third-party library. The library calculates a non-accurate approximate length if the MP3 has variable bitrate (VBR).
ZipHandler
com.day.cq.dam.handler.standard.zip.ZipHandler
  • application/java-archive
  • application/zip
PictHandler
com.day.cq.dam.handler.standard.pict.PictHandler
image/pict
StandardImageHandler
com.day.cq.dam.core.impl.handler.StandardImageHandler
  • image/gif
  • image/png
  • application/photoshop
  • image/jpeg
  • image/tiff
  • image/x-ms-bmp
  • image/bmp
MSOfficeHandler
com.day.cq.dam.handler.standard.msoffice.MSOfficeHandler
application/msword
MSPowerPointHandler
com.day.cq.dam.handler.standard.msoffice.MSPowerPointHandler
application/vnd.ms-powerpoint
OpenOfficeHandler
com.day.cq.dam.handler.standard.ooxml.OpenOfficeHandler
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.presentationml.presentation
EPubHandler
com.day.cq.dam.handler.standard.epub.EPubHandler
application/epub+zip
GenericAssetHandler
com.day.cq.dam.core.impl.handler.GenericAssetHandler
fallback in case no other handler was found to extract data from an asset

All the handlers perform the following tasks:

  • extracting all available metadata from the asset.
  • creating a thumbnail image out of the asset.

It is possible to view the active media handlers:

  1. In your browser, navigate to http://localhost:4502/system/console/components.
  2. Click the link com.day.cq.dam.core.impl.store.AssetStoreImpl.
  3. A list with all the active media handlers is displayed. For example:

chlimage_1-437

Use media handlers in workflows to perform tasks on Assets using-media-handlers-in-workflows-to-perform-tasks-on-assets

Media handlers are services that are used with workflows.

Experience Manager has some default workflows to process assets. To view them, open the Workflow console and click the Models tab: the workflow titles that start with Experience Manager Assets are the assets-specific ones.

Existing workflows can be extended and new ones can be created to process assets according to specific requirements.

The following example shows how to enhance the AEM Assets Synchronization workflow so that subassets are generated for all assets except PDF documents.

Disabling/Enabling a Media Handler disabling-enabling-a-media-handler

The media handlers can be disabled or enabled through the Apache Felix Web Management Console. When the media handler is disabled, its tasks are not performed on the assets.

To enable/disable a media handler:

  1. In your browser, navigate to https://<host>:<port>/system/console/components.
  2. Click Disable next to the name of the media handler. For example: com.day.cq.dam.handler.standard.mp3.Mp3Handler.
  3. Refresh the page: an icon is displayed beside the media handler indicating it is disabled.
  4. To enable the media handler, click Enable next to the name of the media handler.

Creating a Media Handler creating-a-new-media-handler

To support a new media type or to execute specific tasks on an asset, it is necessary to create a media handler. This section describes how to proceed.

Important Classes and Interfaces important-classes-and-interfaces

The best way to start an implementation is to inherit from a provided abstract implementation that takes care of most things and provides reasonable default behavior: the com.day.cq.dam.core.AbstractAssetHandler class.

This class already provides an abstract service descriptor. So if you inherit from this class and use the maven-sling-plugin, make sure that you set the inherit flag to true.

Implement the following methods:

  • extractMetadata(): extracts all available metadata.
  • getThumbnailImage(): creates a thumbnail image out of the passed asset.
  • getMimeTypes(): returns the asset MIME types.

Here is an example template:

package my.own.stuff; /** * @scr.component inherit="true" * @scr.service */ public class MyMediaHandler extends com.day.cq.dam.core.AbstractAssetHandler { // implement the relevant parts }

The interface and classes include:

  • com.day.cq.dam.api.handler.AssetHandler interface: This interface describes the service which adds support for specific MIME types. Adding a MIME type requires to implement this interface. The interface contains methods for importing and exporting the specific documents, for creating thumbnails and extracting metadata.

  • com.day.cq.dam.core.AbstractAssetHandler class: This class serves as basis for all other asset handler implementations and provides common used functionality.

  • com.day.cq.dam.core.AbstractSubAssetHandler class:

    • This class serves as basis for all other asset handler implementations and provides common used functionality plus common used functionality for subasset extraction.
    • The best way to start an implementation is to inherit from a provided abstract implementation that takes care of most things and provides reasonable default behavior: the com.day.cq.dam.core.AbstractAssetHandler Class.
    • This class already provides an abstract service descriptor. So if you inherit from this class and use the maven-sling-plugin, make sure that you set the inherit flag to true.

The following methods must be implemented:

  • extractMetadata(): this method extracts all available metadata.
  • getThumbnailImage(): this method creates a thumbnail image out of the passed asset.
  • getMimeTypes(): this method returns the asset MIME types.

Here is an example template:

package my.own.stuff; /** * @scr.component inherit=“true” * @scr.service */ public class MyMediaHandler extends com.day.cq.dam.core.AbstractAssetHandler

The interface and classes include:

  • com.day.cq.dam.api.handler.AssetHandler interface: This interface describes the service which adds support for specific mime types. Adding a MIME type requires to implement this interface. The interface contains methods for importing and exporting the specific documents, for creating thumbnails and extracting metadata.
  • com.day.cq.dam.core.AbstractAssetHandler class: This class serves as basis for all other asset handler implementations and provides common used functionality.
  • com.day.cq.dam.core.AbstractSubAssetHandler class: This class serves as basis for all other asset handler implementations and provides common used functionality plus common used functionality for subasset extraction.

Example: create a specific Text Handler example-create-a-specific-text-handler

In this section, you are going to create a specific Text Handler that generates thumbnails with a watermark.

Proceed as follows:

Refer to Development Tools to install and set up Eclipse with a Maven plugin and for setting up the dependencies that are needed for the Maven project.

After you perform the following procedure, when you upload a txt file into Experience Manager, the file’s metadata are extracted and two thumbnails with a watermark are generated.

  1. In Eclipse, create myBundle Maven project:

    1. In the Menu bar, click File > New > Other.

    2. In the dialog box, expand the Maven folder, select Maven Project, then click Next.

    3. Check the Create a simple project box and the Use default Workspace locations box, then click Next.

    4. Define the Maven project with the following values:

      • Group Id: com.day.cq5.myhandler
      • Artifact Id: myBundle
      • Name: My Experience Manager bundle
      • Description: This is my Experience Manager bundle
    5. Click Finish.

  2. Set the Java™ Compiler to version 1.5:

    1. Right-click the myBundle project, select Properties.

    2. Select Java™ Compiler and set following properties to 1.5:

      • Compiler compliance level
      • Generated .class files compatibility
      • Source compatibility
    3. Click OK. In the dialog window, click Yes.

  3. Replace the code in the pom.xml file with the following code:

    code language-xml
    <project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <!-- ====================================================================== -->
     <!-- P A R E N T P R O J E C T D E S C R I P T I O N -->
     <!-- ====================================================================== -->
     <parent>
      <groupId>com.day.cq.dam</groupId>
      <artifactId>dam</artifactId>
      <version>5.2.14</version>
      <relativePath>../parent</relativePath>
     </parent>
     <!-- ====================================================================== -->
     <!-- P R O J E C T D E S C R I P T I O N -->
     <!-- ====================================================================== -->
     <groupId>com.day.cq5.myhandler</groupId>
     <artifactId>myBundle</artifactId>
     <name>My CQ5 bundle</name>
     <version>0.0.1-SNAPSHOT</version>
     <description>This is my CQ5 bundle</description>
     <packaging>bundle</packaging>
     <!-- ====================================================================== -->
     <!-- B U I L D D E F I N I T I O N -->
     <!-- ====================================================================== -->
     <build>
      <plugins>
       <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-scr-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.apache.sling</groupId>
        <artifactId>maven-sling-plugin</artifactId>
        <configuration>
         <slingUrlSuffix>/libs/dam/install/</slingUrlSuffix>
        </configuration>
       </plugin>
       <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
         <instructions>
          <Bundle-Category>cq5</Bundle-Category>
          <Export-Package> com.day.cq5.myhandler </Export-Package>
         </instructions>
        </configuration>
       </plugin>
      </plugins>
     </build>
     <!-- ====================================================================== -->
     <!-- D E P E N D E N C I E S -->
     <!-- ====================================================================== -->
     <dependencies>
      <dependency>
       <groupId>com.day.cq.dam</groupId>
       <artifactId>cq-dam-api</artifactId>
       <version>5.2.10</version>
       <scope>provided</scope>
      </dependency>
      <dependency>
       <groupId>com.day.cq.dam</groupId>
       <artifactId>cq-dam-core</artifactId>
       <version>5.2.10</version>
       <scope>provided</scope>
      </dependency>
      <dependency>
       <groupId>com.day.cq</groupId>
       <artifactId>cq-commons</artifactId>
      </dependency>
      <dependency>
       <groupId>javax.jcr</groupId>
       <artifactId>jcr</artifactId>
      </dependency>
      <dependency>
       <groupId>org.apache.felix</groupId>
       <artifactId>org.osgi.compendium</artifactId>
      </dependency>
      <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
      </dependency>
      <dependency>
       <groupId>commons-lang</groupId>
       <artifactId>commons-lang</artifactId>
      </dependency>
      <dependency>
       <groupId>commons-collections</groupId>
       <artifactId>commons-collections</artifactId>
      </dependency>
      <dependency>
       <groupId>commons-io</groupId>
       <artifactId>commons-io</artifactId>
      </dependency>
      <dependency>
       <groupId>com.day.commons</groupId>
       <artifactId>day-commons-gfx</artifactId>
      </dependency>
      <dependency>
       <groupId>com.day.commons</groupId>
       <artifactId>day-commons-text</artifactId>
      </dependency>
      <dependency>
       <groupId>com.day.cq.workflow</groupId>
       <artifactId>cq-workflow-api</artifactId>
      </dependency>
      <dependency>
       <groupId>com.day.cq.wcm</groupId>
       <artifactId>cq-wcm-foundation</artifactId>
       <version>5.2.22</version>
      </dependency>
     </dependencies>
    
  4. Create the package com.day.cq5.myhandler that contains the Java™ classes under myBundle/src/main/java:

    1. Under myBundle, right-click src/main/java, select New, then Package.
    2. Name it com.day.cq5.myhandler and click Finish.
  5. Create the Java™ class MyHandler:

    1. In Eclipse, under myBundle/src/main/java, right-click the com.day.cq5.myhandler package, select New, then Class.
    2. In the dialog window, name the Java™ Class MyHandler and click Finish. Eclipse creates and opens the file MyHandler.java.
    3. In MyHandler.java replace the existing code with the following and then save the changes:
    code language-java
    package com.day.cq5.myhandler;
    import java.awt.Color;
    import java.awt.Rectangle;
    import java.awt.image.BufferedImage;
    import java.io.IOException;
    import java.io.InputStream;
    import java.io.InputStreamReader;
    import javax.jcr.Node;
    import javax.jcr.RepositoryException;
    import javax.jcr.Session;
    import org.apache.commons.io.IOUtils;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import com.day.cq.dam.api.metadata.ExtractedMetadata;
    import com.day.cq.dam.core.AbstractAssetHandler;
    import com.day.image.Font;
    import com.day.image.Layer;
    import com.day.cq.wcm.foundation.ImageHelper;
    
    /**
     * The <code>MyHandler</code> can extract text files
     * @scr.component inherit="true" immediate="true" metatype="false"
     * @scr.service
     *
     **/
    
    public class MyHandler extends AbstractAssetHandler {
     /** * Logger instance for this class. */
     private static final Logger log = LoggerFactory.getLogger(MyHandler.class);
     /** * Music icon margin */
     private static final int MARGIN = 10;
     /** * @see com.day.cq.dam.api.handler.AssetHandler#getMimeTypes() */
     public String[] getMimeTypes() {
      return new String[] {"text/plain"};
     }
    
     public ExtractedMetadata extractMetadata(Node asset) {
      ExtractedMetadata extractedMetadata = new ExtractedMetadata();
      InputStream data = getInputStream(asset);
      try {
       // read text data
       InputStreamReader reader = new InputStreamReader(data);
       char[] buffer = new char[4096];
       String text = "";
       while (reader.read(buffer) != -1) {
        text += new String(buffer);
       }
       reader.close();
       long wordCount = this.wordCount(text);
       extractedMetadata.setProperty("text", text);
       extractedMetadata.setMetaDataProperty("Word Count",wordCount);
       setMimetype(extractedMetadata, asset);
      } catch (Throwable t) {
       log.error("handling error: " + t.toString(), t);
      } finally {
       IOUtils.closeQuietly(data);
      }
      return extractedMetadata; }
     // ----------------------< helpers >----------------------------------------
     protected BufferedImage getThumbnailImage(Node node) {
      ExtractedMetadata metadata = extractMetadata(node);
      final String text = (String) metadata.getProperty("text");
      // create text layer
      final Layer layer = new Layer(500, 600, Color.WHITE);
      layer.setPaint(Color.black);
      Font font = new Font("Arial", 12);
      String displayText = this.getDisplayText(text, 600, 12);
      if(displayText!=null && displayText.length() > 0) {
       // commons-gfx Font class would throw IllegalArgumentException on empty or null text
       layer.drawText(10, 10, 500, 600, displayText, font, Font.ALIGN_LEFT, 0, 0);
      }
      // create watermark and merge with text layer
      Layer watermarkLayer;
      try {
       final Session session = node.getSession();
       watermarkLayer = ImageHelper.createLayer(session, "/content/dam/geometrixx/icons/certificate.png");
       watermarkLayer.setX(MARGIN);
       watermarkLayer.setY(MARGIN);
       layer.merge(watermarkLayer);
      } catch (RepositoryException e) {
       // TODO Auto-generated catch block
       e.printStackTrace();
      } catch (IOException e) {
       // TODO Auto-generated catch block
       e.printStackTrace(); }
      layer.crop(new Rectangle(510, 600));
      return layer.getImage(); }
     // ---------------< private >-----------------------------------------------
     /**
      * This method cuts lines if the text file is too long..
      * * @param text
      * * text to check
      * * @param height
      * * text box height (px)
      * * @param fontheight
      * * font height (px)
      * * @return the text which will fit into the box
      */
     private String getDisplayText(String text, int height, int fontheight) {
      String trimmedText = text.trim();
      int numOfLines = height / fontheight;
      String lines[] = trimmedText.split("\n");
      if (lines.length <= numOfLines) {
       return trimmedText;
      } else {
       String cuttetText = "";
       for (int i = 0; i < numOfLines; i++) {
        cuttetText += lines[i] + "\n";
       }
       return cuttetText;
      }
     }
     /**
      * * This method counts the number of words in a string
      * * @param text the String whose words would like to be counted
      * * @return the number of words in the string
      * */
     private long wordCount(String text) {
      // We need to keep track of the last character, if we have two whitespace in a row we don't want to double count.
      // The starting of the document is always a whitespace.
      boolean prevWhiteSpace = true;
      boolean currentWhiteSpace = true;
      char c; long numwords = 0;
      int j = text.length();
      int i = 0;
      while (i < j) {
       c = text.charAt(i++);
       if (c == 0) { break; }
       currentWhiteSpace = Character.isWhitespace(c);
       if (currentWhiteSpace && !prevWhiteSpace) { numwords++; }
       prevWhiteSpace = currentWhiteSpace;
      }
      // If we do not end with a whitespace then we need to add one extra word.
      if (!currentWhiteSpace) { numwords++; }
      return numwords;
     }
    }
    
  6. Compile the Java™ class and create the bundle:

    1. Right-click the myBundle project, select Run As, then Maven Install.
    2. The bundle myBundle-0.0.1-SNAPSHOT.jar (containing the compiled class) is created under myBundle/target.
  7. In CRX Explorer, create a node under /apps/myApp. Name = install, Type = nt:folder.

  8. Copy the bundle myBundle-0.0.1-SNAPSHOT.jar and store it under /apps/myApp/install (for example with WebDAV). The new text handler is now active in Experience Manager.

  9. In your browser, open the Apache Felix Web Management Console. Select the Components tab and disable the default text handler com.day.cq.dam.core.impl.handler.TextHandler.

Command Line Based Media Handler command-line-based-media-handler

Experience Manager enables you to run any command-line tool within a workflow to convert assets (such as ImageMagick) and to add the new rendition to the asset. Install the command-line tool on the disk hosting the Experience Manager server and add and configure a process step to the workflow. The invoked process, called CommandLineProcess, filters according to specific MIME types and creates multiple thumbnails based on the new rendition.

The following conversions can be automatically run and stored within Experience Manager Assets:

NOTE
On non-Windows systems, the FFMpeg tool returns an error while generating renditions for a video asset that has a single quote (') in its filename. If the name of your video file includes a single quote, remove it before uploading to Experience Manager.

The CommandLineProcess process performs the following operations in the order they are listed:

  • Filters the file according to specific mime-types, if specified.
  • Creates a temporary directory on the disk hosting the Experience Manager server.
  • Streams the original file to the temporary directory.
  • Executes the command defined by the arguments of the step. The command is being executed within the temporary directory with the permissions of the user running Experience Manager.
  • Streams the result back into the rendition folder of the Experience Manager server.
  • Deletes the temporary directory.
  • Creates thumbnails based on those renditions, if specified. The number and the dimensions of the thumbnails are defined by the arguments of the step.

An example using ImageMagick an-example-using-imagemagick

The following example shows you how to set up the command line process step. Every time an asset with the MIME-type gif or tiff is added to /content/dam on the Experience Manager server, a flipped image of the original is created together with three more thumbnails (140x100, 48x48, and 10x250).

To do this process step, use ImageMagick. Install ImageMagick on the disk hosting the Experience Manager server:

  1. Install ImageMagick. See ImageMagick documentation for more information.

  2. Set up the tool so you can run convert on the command line.

  3. To see if the tool is installed properly, run the following command convert -h on the command line.

    It displays a Help screen with all the possible options of the convert tool.

    note note
    NOTE
    In some versions of Windows® (for example Windows® SE), the convert command fails to run because it conflicts with the native convert utility that is part of Windows® installation. In this case, mention the complete path for the ImageMagick utility used to convert image files to thumbnails. For example, "C:\Program Files\ImageMagick-6.8.9-Q16\convert.exe" -define jpeg:size=319x319 ${filename} -thumbnail 319x319 cq5dam.thumbnail.319.319.png.
  4. To see if the tool runs properly, add a JPG image to the working directory and run the command convert <image-name>.jpg -flip <image-name>-flipped.jpg on the command line.

    A flipped image is added to the directory.

Then, add the command line process step to the DAM Update Asset workflow:

  1. Go to the Workflow console.

  2. In the Models tab, edit the DAM Update Asset model.

  3. Change the settings of the Web enabled rendition step as follows:

    mime:image/gif,mime:image/tiff,tn:140:100,tn:48:48,tn:10:250,cmd:convert ${directory}/${filename} -flip ${directory}/${basename}.flipped.jpg

  4. Save the workflow.

To test the modified workflow, add an asset to /content/dam.

  1. In the file system, get a TIFF image of your choice. Rename it to myImage.tiff and copy it to /content/dam, for example by using WebDAV.
  2. Go to the CQ5 DAM console, for example http://localhost:4502/libs/wcm/core/content/damadmin.html.
  3. Open the asset myImage.tiff and verify that the flipped image and the three thumbnails have been created.

Configure the CommandLineProcess process step configuring-the-commandlineprocess-process-step

This section describes how to set the Process Arguments of the CommandLineProcess. Separate the values of Process Arguments using a comma and do not start a value with a whitespace.

Argument-Format
Description
mime:<mime-type>
Optional argument. The process is applied if the asset has the same MIME-type as the one of the arguments.
Several MIME-types can be defined.
tn:<width>:<height>
Optional argument. The process creates a thumbnail with the dimensions defined in the argument.
Several thumbnails can be defined.
cmd: <command>
Defines the command that is run. The syntax depends on the command line tool. Only one command can be defined.
The following variables can be used to create the command:
${filename}: name of the input file, for example original.jpg
${file}: full path name of the input file, for example /tmp/cqdam0816.tmp/original.jpg
${directory}: directory of the input file, for example /tmp/cqdam0816.tmp
${basename}: name of the input file without its extension, for example original
${extension}: extension of the input file, for example jpg

For example, if ImageMagick is installed on the disk hosting the Experience Manager server and if you create a process step using CommandLineProcess as Implementation and the following values as Process Arguments:

mime:image/gif,mime:image/tiff,tn:140:100,tn:48:48,tn:10:250,cmd:convert ${directory}/${filename} -flip ${directory}/${basename}.flipped.jpg

Then, when the workflow runs, the step only applies to assets that have image/gif or mime:image/tiff as mime-types. It creates a flipped image of the original, converts it into .jpg and creates three thumbnails that have the dimensions: 140x100, 48x48, and 10x250.

Use the following Process Arguments to create the three standard thumbnails using ImageMagick:

mime:image/tiff,mime:image/png,mime:image/bmp,mime:image/gif,mime:image/jpeg,cmd:convert ${filename} -define jpeg:size=319x319 -thumbnail "319x319>" -background transparent -gravity center -extent 319x319 -write png:cq5dam.thumbnail.319.319.png -thumbnail "140x100>" -background transparent -gravity center -extent 140x100 -write cq5dam.thumbnail.140.100.png -thumbnail "48x48>" -background transparent -gravity center -extent 48x48 cq5dam.thumbnail.48.48.png

Use the following Process Arguments to create the web-enabled rendition using ImageMagick:

mime:image/tiff,mime:image/png,mime:image/bmp,mime:image/gif,mime:image/jpeg,cmd:convert ${filename} -define jpeg:size=1280x1280 -thumbnail "1280x1280>" cq5dam.web.1280.1280.jpeg

NOTE
The CommandLineProcess step only applies to Assets (nodes of type dam:Asset) or descendants of an asset.
recommendation-more-help
4452738f-2bdf-4cd4-9b45-905a69d607ad