Processing Assets Using Media Handlers and Workflows

Adobe Experience Manager (AEM) Assets 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.

A workflow can be defined that will automatically execute when an asset of a particular type is uploaded to the server. The processing steps are defined in terms of a series of AEM Assets Media Handlers. AEM provides some built in handlers, and additional ones can be either custom developed or defined by delegating the process to a command line tool.

Media handlers are services inside AEM Assets that perform specific actions on assets. For example, when an MP3 audio file is uploaded into AEM, 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 AEM. Specific tasks can be performed on assets by either extending/creating workflows, extending/creating media handlers or disabling/enabling media handlers.

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

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:

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

AEM 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 AEM 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 sub-assets are generated for all assets except PDF documents.

The workflow will look as follows:

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.

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.

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 behaviour: 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 need to 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 type(s).

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 new 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 behaviour: 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 need to 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 type(s).

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 new 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

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

Proceed as follows:

Refer to How to Set Up the Development Environment with Eclipse for installing and setting 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 AEM, the file's metadata are extracted and two thumbnails with a watermark are generated.

AEM 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 AEM 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 AEM Assets:

• EPS and AI transformation using ImageMagick and Ghostscript
• FLV video transcoding using FFmpeg
• MP3 encoding using LAME
• Audio processing using SOX

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 AEM 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 AEM.
  
• Streams the result back into the rendition folder of the AEM 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.

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 /content/dam on the AEM 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 AEM server:

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

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

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.

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