Using Content Transformation Service

Concept

The Content Transformation Service provides transformations for content, such as:

• Conversion from one file format to another
• Image manipulations (crop, resize, flip, rotate, sharpen, ..)
• Extraction of image metadata

The actual transformation is executed by a provider supporting the particular transformation.

Usage

The Content Transformation Service is available through the Content Server (Viewer module) and Transformation Server (Batch module). For both APIs you need to specify how the content should be transformed (transformation instruction) and optionally which provider to use. The instruction is passed directly to the provider, if specified. Otherwise, the instruction is passed to the enabled providers in a configured order, the first provider to support the given instruction is used. Rather than specifying the transformation instruction for each transformation, you can use a predefined transformation.

Transformation

Commonly used transformation instructions can be registered and maintained as transformations in iKnowBase Development Studio (ikb$console > development > advanced > transformations).

A transformation contains:

• an external key that may be used to look up the transformation
• one or more transformation instructions, which apply to given file formats and mime types
• excluded file formats and mime types
• Settings regarding content viewer, image picklist, and iKnowBase Content Studio (thumbnail)

See the “Providers” section for information about transformation instructions.

Note: A transformation instruction relate to output/target format, e.g. "<extension>" means output/target file extension.

You can use a transformation in a content viewer to generate content server transformation links. The links will only be generated for the file formats and mime types included in the transformation.

You can use a transformation in one of the supported APIs, by referencing it either by its external key or its guid.

See iKnowBase Development Reference for further information.

HTTP API for Content Server

To transform content using the HTTP API use a URL with the following format:

• /Content/<document_id>/[attr=<document_attribute_guid/][version=<version_no>/]transformation=<reference|[provider:]instruction>/<filename>

You may specify which transformation to perform in one of two ways, either by referencing a predefined transformation or by using a transformation instruction directly (see the previous section “Transformation”). Both document content and document file attributes may be transformed.

Examples

The following table illustrates various ways to use the Content Server to convert a MS Word document to PDF.

PL/SQL API for Transformation Server

To transform content from PL/SQL there are two APIs available. You can either transform a blob or a content from a document. For both methods you must specify which transformation to perform, either by using a predefined transformation or by using a transformation instruction directly (see previous section “Transformation”).

Transformation from PL/SQL uses AQ and you can set a default maxWait for enqueuing/dequeuing operations. It accepts the following configuration property.

See iKnowBase PL/SQL Content Services API for further information.

Examples

Convert a blob:

declare
        l_transformed_object blob;
begin
        l_transformed_object := ikb_transformation_service.process (
                        p_file             => :inputFile, -- (BLOB)
                        p_transformation   => :transformation, -- string e.g pdf
                        p_maxWaitResponse  => :maxWaitResponse);
end;
/

Convert the binary content from a document:

declare
        l_transformed_object blob;
begin
        l_transformed_object := ikb_transformation_service.process (
                        p_execution_user          => :userreference,
                        p_documentreference       => :documentreference,
                        p_document_attribute_guid => :document_attribute.object_guid,
                        p_transformation          => :transformation, -- string e.g pdf
                        p_maxWaitResponse         => :maxWaitResponse);
end;
/

Providers

The following table shows available providers with a flag indicating if the provider is automatically enabled.

These following providers have specific installation requirements, see Content Transformation Providers:

• FileConverter
• CloudConvert

The following sections documents each available provider, including supported transformation instructions.

CloudConvert

Prefix: “cloudconvert”.

The CloudConvert content transformation provider supports a large set of transformations via www.cloudconvert.com, including among other things format transformation and image manipulation.

The default transformation settings will:

• Upload the file to www.cloudconvert.com with transformation instructions.
• Wait until the conversion process has finished (or until timeout).
• Download and return the file. The file is immediately deleted from www.cloudconvert.com after the first successful download.

The CloudConvert provider accepts simple transformation instructions with or without transformation provider prefix:

• Simple using format: Any format defined in https://cloudconvert.com/formats. Conversion using default settings.
• Simple using mimetype: “application/pdf”, “text/html”, "image/tiff"

The CloudConvert provider accepts advanced transformation instructions with or without transformation provider prefix. The options below may occur in any order.

The option converteroptions is a Map corresponding to https://cloudconvert.com/api of converteroptions for the transformation. Use www.cloudconvert.com’s API Console to find the configuration options you want. Note: They will be delimited with & (ampersand) in the API, while iKnowBase uses : (colon) as delimiter.

Examples

ImageEditor

Prefix: “image”.

The ImageEditor provider performs image operations such as resize, rotate, flip, crop and metadata extraction and is used by the Image Archive for all image operations.

The ImageEditor provider accepts simple transformation instructions with or without transformation provider prefix:

• Simple using format: “gif”, “jpeg”, “jpg”, “png”, "metadata"
• Simple using mimetype: “image/gif”, “image/jpeg”, "image/png"

The ImageEditor provider accepts advanced transformation instructions with transformation provider prefix:

• "image:<operation>"

Multiple operation options can be specified delimited by : (colon). Each operation may also take additional parameters. The table below gives an overview over available operations.

Examples

FileConverter

Prefix: “fileconverter”.

The FileConverter is a content transformation provider that converts documents from a number of file formats, to PDF, HTML or a number of image formats.

The FileConverter provider accepts simple transformation instructions with or without transformation provider prefix:

• Simple using format: “pdf”, “html”, “tiff”, “xml”, “gif”, “jpeg”, "jpg"
• Simple using mimetype: “application/pdf”, “text/html”, “image/tiff”, “text/xml”, “image/gif”, "image/jpeg"
• Simple using configFile: "my-custom.cfg"

The FileConverter provider accepts advanced transformation instructions with transformation provider prefix

• "fileconverter:<extension>:<configurationFile>"
• "fileconverter:<mimetype>:<extension>"
• "fileconverter:<mimetype>:<extension>:<configurationFile>"

FileConverter is also supported via the legacy database package BATCH_FILECONVERT_CLIENT.

Note: Mimetype in transformation instruction is not supported through the Content Server, due to conflicting “/”.
Note: Configuration files for the specified type needs to be present in the installed Oracle Outside In directory.

Oracle Multimedia

Prefix: “ordimg”.

The Oracle Multimedia provider performs image operations such as resize, rotate, flip, and crop for images.

The Oracle Multimeldia provider accepts simple transformation instructions without transformation provider prefix:

• Simple using format: “gif”, “jpeg”, “jpg”, "png"
• Simple using mimetype: “image/gif”, “image/jpeg”, "image/png"

The Oracle Multimeldia provider accepts advanced transformation instructions with transformation provider prefix:

• "ordimg:<operation>"

See Oracle’s documentation for “Image process( ) and processCopy( ) Operators” regarding valid operations.

Note: The advanced command format for Oracle Multimedia is incompatible with iKnowBase Content Server and cannot be used directly in the URL using transformation=. You need to register the transformation command
in ikb$console and use the transformation’s external key in the URL.

Oracle Text

Prefix: “ctxdoc”.

The Oracle Text provider various file formats to text or HTML.

The Oracle Text provider accepts simple transformation instructions with or without transformation provider prefix:

• Simple using format: “text”, "html"
• Simple using mimetype: “text/plain”, "text/html"

Caching

All transformed content are cached in a database table (IKB_TRANSFORMATION_EDITIONS). A cached transformation result is only valid if the source content has not changed.

You may view the cache in ikb$console > services > transformations > cache.

Cache cleanup

A database job which cleans up the cache is by default configured to run periodically, see Schedule in iKnowBase Development Studio. It will remove non-current cache for iKnowBase documents (cache prefix “docref”) and old BLOB conversions (cache prefix “blob” - no iKnowBase document reference used).

You may also purge the cache table, but note that this will lead to initially longer response times as the cache needs to be regenerated.