DAM Media Handlers

CQ5 DAM comes with a set of default workflows and media handlers to process assets. The workflow defines the general tasks to be executed on the assets, then delegates the specific tasks to the media handlers, for example thumbnail generation or metadata extraction.

Media handlers are services inside CQ5 DAM that perform specific actions on assets. For example, when an MP3 audio file is uploaded into CQ5, a workflow triggers an MP3 handler that extracts the metadata and generates a thumbnail. Media handlers are usually used in combination with workflows. Most common MIME types are supported within CQ5. Specific tasks can be performed on assets by either extending/creating workflows, extending/creating media handlers or disabling/enabling media handlers.


Please refer to the CQ DAM Supported Formats page for a description of all the formats supported by CQ DAM as well as features supported for each format.

Default Media Handlers

The following media handlers are available within CQ5 DAM and handle the most common MIME types:

Handler name Service Name (in the System Console) Supported MIME types




























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://<host>:<port>/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:

Using Media Handlers in Workflows to perform tasks on Assets

Media handlers are services that are usually used in combination with workflows.

CQ5 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 DAM are the assets specific ones.

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

By default, when a PDF document is uploaded into the /var/dam/geometrixx/documents folder, the default DAM Asset Synchronization copies the document into the /content/dam/geometrixx/documents folder.

The following example shows how to enhance the DAM Asset Synchronization workflow
so that sub-assets are generated for all assets except PDF documents.

The workflow will look as follows:


Proceed as follows:

  1. Go to the Workflow console.
  2. Edit the the DAM Asset Synchronization workflow model.
  3. Add an OR Split after the Sync asset step.
  4. Add a Create Sub Asset step to the left branch.
  5. Add a No Operation step to the right branch.
  6. Edit the OR Split:
    • Add the script 1 below - that returns false for PDF files - to the Branch 1.
    • Set Branch 1 as the default route.
    • Add the script 2 below- that returns true for PDF files - to the Branch 2.
  7. Save the workflow.

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 http://<host>:<port>/system/console/components.

  2. Click the Disable button right beside the name of the media handler. For example: com.day.cq.dam.handler.standard.mp3.Mp3Handler.

  3. Refresh the page: a Disabled icon is displayed beside the media handler.

  4. To enable the media handler, click the Enable button beside the name of the 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 new media handler. This section describes how to proceed.

Important Classes and Interfaces

Example: create a specific Text Handler

Command Line Based Media Handler

CQ enables you to run any command-line tool within a workflow to convert assets (like for example ImageMagick) and to add the new rendition to the asset. You only need to install the command-line tool on the disk hosting the CQ server and to add and configure a process step to the workflow. The invoked process, called CommandLineProcess, also enables to filter according to specific mime-types and to create multiple thumbnails based on the new rendition.

The following conversions can be automatically run and stored within DAM:

The CommandLineProcess process sequently performs the following operations:

  • Filters the file according to specific mime-types, if specified.
  • Creates a temporary directory on the disk hosting the CQ 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 CQ.
  • Streams the result back into the rendition folder of the CQ 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

The following example shows you how to set up the command line process step so that every time an asset with the mime-type gif or tiff is added to /var/dam on the CQ server, a flipped image of the original is created together with three additional thumbnails (140x100, 48x48 and 10x250).

To do this, you will use ImageMagick. ImageMagick is a free software suite to create, edit, and compose bitmap images and is typically used from the command line.

First install ImageMagick on the disk hosting the CQ server:

  1. Install ImageMagick: please refer to the ImageMagick documentation.
  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 on the command line:
    convert -h
    It displays a help screen with all the possible options of the convert tool.
  4. To see if the tool runs properly, add an .jpg image to the working directory and run the following command on the command line:
    convert <image-name>.jpg -flip <image-name>-flipped.jpg
    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:
    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
  4. Save the workflow.

Finally, test the modified workflow by adding a new asset to /var/dam:

  1. In the file system, get a .tiff image of your choice. Rename it myImage.tiff and copy it to /var/dam; for example by using WebDAV.
  2. Go to the CQ5 DAM console; for example at 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.


Configuring the CommandLineProcess Process Step

This section describes how to set the Process Arguments of the CommandLineProcess.

The values of the Process Arguments must be separated by a comma and must not start with a whitespace.

 Argument-Format Description

Optional argument. The process is applied if the asset has the same mime-type as the one of the argument.

Several mime-types can be defined.


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 will be executed. 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, e.g. original.jpg
${file}: full path name of the input file, e.g. /tmp/cqdam0816.tmp/original.jpg
${directory}: directory of the input file, e.g. /tmp/cqdam0816.tmp.
${basename}: name of the input file without its extension, e.g. original
${extension}: extension of the input file, e.g. jpg

For example, if ImageMagick is installed on the disk hosting the CQ 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


The CommandLineProcess step only applies to Assets (nodes of type dam:Asset) or descendants of an Asset.

Any questions?
Find tips, tricks, and solutions to common issues in our support community: