Thumbnails

Processing Thumbnail Requests

The Content Engine thumbnail generation service renders a thumbnail image from a document content element. You cannot generate thumbnails for annotations. The process for automatically generating a thumbnail starts with a thumbnail request. How a request is created depends on the automatic generation options that you implement.

A request is represented by a CmThumbnailRequest object, and is placed on the ThumbnailRequest queue table. This object references a single content element in the document version to be submitted for thumbnail generation.

A queue sweep job processes the ThumbnailRequest queue table, passing document content elements to the thumbnail generation service. The queue sweep job is represented by a CmThumbnailRequestSweep object, which controls thumbnail attributes such as format and size. A CmThumbnailRequestSweep instance is created by the Thumbnail Extensions Add-On. You cannot create more instances of this class.

When the thumbnail generation service successfully renders a thumbnail image, a CmThumbnail object is created that contains the thumbnail image and that references the source document and content element for the generated image. A document can have multiple thumbnails, referenced by the document's CmThumbnails property.

The system removes successfully completed thumbnail requests from the ThumbnailRequest queue table, and exceptions where the system cannot process the request, and, which cannot be fixed by an administrator. Failed requests that are fixable by an administrator are automatically tried again up to a configurable number of times. If the retries fail, the requests remain in the queue table. A CmThumbnailRequest object provides failure information, and allows an administrator to manually restart retries for failed requests.

Automatic Generation Options

Thumbnails can be automatically generated by the Content Engine thumbnail generation service in the following ways.

• Event-based generation. A class subscription mechanism that automatically generates thumbnails for new documents. The class subscription is CmThumbnailGenerationSubscription, with a target class of Document or a subclass. An administrator creates a CmThumbnailGenerationSubscription object and sets the SubscribedEvents property to CheckinEvent, the EventAction property to an event handler that is created by the Thumbnail Extensions AddOn, and, if necessary, the FilterExpression property to additional filter criteria. When an applicable document is checked in, the event handler creates and inserts a CmThumbnailRequest object in the ThumbnailRequest queue table.

  Event-based generation applies only to the first content element if there are multiple content elements set on the document.

• Sweep-based generation. A document-query mechanism that automatically generates thumbnails for existing documents. The CmThumbnailGenerationJob class is provided for performing one-time sweeps of persisted Document instances, based on filter criteria set on the FilterExpression property. For documents that meet the criteria, a CmThumbnailGenerationJob object creates and inserts CmThumbnailRequest objects in the ThumbnailRequest queue table.

  A CmThumbnailGenerationJob object runs as a background thread. You can configure one or more CmThumbnailGenerationJob objects with timeslots, specifying when each job starts and how long it runs. After a job processes all Document instances that meet the FilterExpression criteria, the job terminates. Additional sweep jobs are typically run to change existing thumbnail formats or sizes, or process a new set of documents that are not covered by a previous sweep.

  A CmThumbnailGenerationJob object includes properties to enable generation of failure result records and to retrieve them. Each failure result record identifies a swept object for which the failure occurred, and describes the reason for the failure. For more information, see CmSweepResult.

  Sweep-based generation applies only to the first content element if there are multiple content elements set on a document.

• Ad hoc generation. Supports direct user requests to generate thumbnails for any content element in a document version. After a request from a user to generate a thumbnail for a specified content element, the client application creates and saves a CmThumbnailRequest object, without any filtering. The server inserts the object in the ThumbnailRequest queue table.

  Unlike event- or sweep-based generation, the ad hoc method is not limited to thumbnail generation for only the first content element. For example, a user can request two thumbnails for a document version that contains two content elements, resulting in the creation of two CmThumbnailRequest objects for the same input document.

User-Generated Option

Unlike the automatic generation options where a Content Engine service renders thumbnail images, the user-generated option supports persistence of thumbnails with images generated by third-party applications. In this scenario, a client application directly creates a CmThumbnail object and sets the externally generated thumbnail image on it.