Alfresco has developed a mechanism to easily generate thumbnails of each document. Alfresco uses thumbnails at different places, the most common case is the thumbnails displayed in the document library.

This mechanism may seem a little complex but it is pretty well developed. I’m going to describe it in four parts :

  1. Thumbnail definition
  2. Content transformation definition
  3. Content transformation execution
  4. Service layer

1 - Thumbnail rendition definition

Each thumbnail is generated by applying a specific configuration that contains : width, height, ratio, target format, etc.

These definitions are listed in the bean with id “thumbnailRegistry” defined in the file  “thumbnail-service-context.xml”.

That bean holds all thumbnail definitions that are available. If you want to create a new thumbnail definition you should override that bean.

2 - Content transformation definition

Basically, the generation of a thumbnail is done by generating a new file from an existing one. You may need to generate a thumbnail from a Powerpoint, a PDF, a video, a picture, etc.

For instance, beans described in the file “video-thumbnail-context.xml” defines conversions from a video file (FLV, MP4, etc.) to a picture (JPEG format).

You can find other transformation definitions in the file “content-services-context.xml”.

3 - Content transformation execution

Alfresco does not use pure java to do conversions, it uses third-party softwares like ffmpeg, image magick, open office, etc.

These softwares are called dynamically at runtime. For each of them there is a “base command” defined in XML configuration (again and again :) ), each command takes input parameters that depends on the content transformation definition chosen.

The execution phase of the transformation is done by calling the method “transform” from java classes implementing the interface “ContentTransformerWorker”.

The functioning of this method is easily understandable :

  • Takes in parameter a source file (the "reader") and a target file (the "writer")
  • Infers the mimetypes of the reader and writer
  • Picks the proper transformation definition to apply
  • Execute the transformation by using java.lang.Runtime#exec (see org.alfresco.util.exec.RuntimeExec)
  • Write the result of the transformation (if no errors occured) in the writer

4 - Service layer

Alfresco is well-designed, no complex API calls are needed to create a thumbnail, you should use the service called “ThumbnailService”.

It is a pretty little service but it uses everything I talked about in the previous parts of this blog article.

To create a thumbnail you should use the method “createThumbnail” (obviously!), it takes some input parameters :

  • Source node ref
  • Property that contains the binary content of the node (typically "cm:content")
  • Target mime type
  • Transformation options (used at transformation execution)
  • Name of the generated thumbnail (matches with the name of a thumbnail rendition definition)

Once the thumbnail is generated, a node will be created and will have the source node as parent.


Et voila! At the first glance the thumbnail generation may seem a bit complicated, but in fact it is well designed and easily understandable.