Adding an External Viewer

General Purpose

How to add an external viewer to be used by the Rosetta delivery manager.

The following components are involved:

  • Viewer
  • Viewer Pre-processor
  • Delivery Rules


The External Viewer is a tool or application that can deliver one or more files to the end user via the web browser. Different viewers can work with specific file formats and utilize different parts of the metadata stored in Rosetta. For example, the IA Book Reader can deliver image files such as JPEG, JPEG2000 or PNG.

The viewer should use the Delivery API for getting the IE (or only the files) from the repository (Operational or Permanent) in order to deliver them (see Delivery web services for more information)

If your viewer supports an alternative mobile UI, setting your delivery rule to ‘mobile’ will generate an “is_mobile=true” parameter in the URL that your viewer can use.

Viewers can also accept custom parameters, configured in the delivery rules and passed by the delivery manager. See also “Request Parameters” in the Rosetta Configuration Guide, ch. 4.

Note: Rosetta enforces the usage of the Delivery Session ID (DVS) as part of the web service call, in order to prevent un-authorized access to the repository.

Viewer Pre-Processor (VPP)

Since each viewer has different requirements, the delivered IE with its Representations and Files needs to go through a stage of preparation before it can be delivered. This stage is using a plug-in called viewer pre-processor (VPP). The VPP can be used for manipulating the files or the metadata to meet the viewer requirements, or prevent possible errors.

For example, the VPP can copy the files from the Permanent Repository to the cache so the external viewer will not have to access the original files.

Below is a table that specifies the parts of the IE that might be needed by the viewer:

LevelDataMets section
IEDescriptive metadataDC and Source Metadata
IECMS Descriptive metadataCMS Metadata
IETechnical informationDNX
REPStruct mapsStruct maps
REPTechnical informationDNX
FileFile pathshttp links in fileSec mets section – referenced by the ID in the struct map
FileThumbnail pathshttp links in fileSec mets section – referenced by the ID in the struct map
FileTechnical information- size, mime-type, checksum, checksum typeAttributes on the mets:file element
FileOther technical informationDNX – May make the METS to be too large for transfer – can be requested separately

Note: Using a VPP is not mandatory. In case no manipulation/conversion/copy of the files is needed, the viewer can call the delivery web services to get additional information as needed.

Delivery Rules

In order to use your viewer, a delivery rule should be configured to associate the matching Representation of the relevant IEs to the viewer. Please refer to the Rosetta Configuration Guide ch. 4, on how to set up delivery rules.

The VPP interface is available in the javadoc.


Blog posts that demonstrate examples of external viewer integration: