Extensions

The ImageMaster Integration Service can be equipped with extensions. Extensions are Java classes loaded by the Integration Service at run-time when the system encounters an extension point.

Extension points are fixed points in the implementation of the Integration Service that consist of a name and an interface. When control reaches an extension point, the Integration Service looks for extensions based on an extension configuration file (see example further below) and runs the code from the extensions.

For example, during initialization of the query language system, the Integration Service passes the extension point queryLangInit. It then consults the extension configuration to find the extensions to be run at this point, instantiates the extension classes (which all implement the interface IQueryExtension), and runs the extensions. The following XML code presents an example configuration file which activates two extensions to be executed at the extension point queryLangInit:

<

<?xml version='1.0' encoding='UTF-8'?>

<ext:config xmlns:ext='http://www.imaes.ecm.tsystems.com/ima/9.0/extensions'>

  <point>

    <name>queryLangInit</name>

    <extensions>

      <extension>

        com.tsystems.ecm.imaes.exttest.QueryExt1

      </extension>

      <extension>

        com.tsystems.ecm.imaes.exttest.QueryExt2

      </extension>       

    </extensions>

  </point>

</ext:config>

Figure 579: Example – extension configuration file “extensions.XML”

Note the following issues in the context of the extension configuration:

  • An invalid extension configuration file “extensions.xml” prevents the start of the Integration Service.
  • In any delivery package there must not be more than one configuration file “extensions.xml”.
  • Adding, removing, or changing the order of extensions or an extension itself requires changing the extension configuration and at least it also requires re-deploying the software.

Furthermore, Integration Service extensions are characterized as follows:

  • There may be more than one extension installed at an extension point.

  • If the extension configuration does not define an extension at an extension point, no extension is installed for this point.

  • The Integration Service also works if there is no extension configuration.

Note that the order of the extensions in the XML file is also the order in which the classes are instantiated. Typically, this is also the order in which the extensions are called when processing the extension point. It is, however, up to the definition of the extension point to decide exactly how the results from multiple extensions are combined. Some extension points may decide that it makes no sense to run more than the first extension and therefore ignore the second extension. It is therefore essential to consult the extension point’s specification before writing an extension configuration.

In practice, extensions (provided within JAR files) with their configuration (provided as XML file “extensions.xml”) are packaged into the delivery EAR file of an ImageMaster release. Project specific deliveries will have incorporated all their required extensions in this delivery file.

A delivery EAR file typically contains several files and a directory structure that can be viewed by any ZIP based file extraction tool. The content of the EAR file may look as follows:

lib/ima-client-extensions-9.9.1.1-b88888.jar

inventoryBeans.jar

imawebservice.war

Figure 580: Example – content of a delivery file including extensions

In this example the extension configuration file’s location can be derived from the JAR name in the lib directory “ima-client-extensions…jar”. This jar file includes the configuration file “extensions.xml”, whereas the extension implementations themselves are located in another JAR file, e.g. in “inventoryBeans.jar” in the example above.

The following table presents an overview of the extension points which are available in the ImageMaster 9.9.1 release. Certain extensions are used by specific ImageMaster features and all listed extension points bear potential for further specific customization.

Since release 9.5.1, some mandatory extensions are automatically enabled if the corresponding module is included in the assembled EAR file. These extensions are included in the table below with a corresponding note that there is no need to enable them manually anymore.

Extension Point

Description

addConstraints

Called on system startup. Allows creating custom constraint checkers for attribute constraints.

auditEvent

Called when a new audit trail event is written. Allows modifying the event properties, or overriding the filter decisions by the system's audit trail configuration.

batchCancel

Called when a batch is cancelled (used by FIS).

batchClose

Called when a batch is closed (used by FIS).

checkinRevision

Called when document revisions are checked in. Prevents update of a revision if the revision is going to be registered or is already registered in SAP.

Permits the update of a revision which is already registered in SAP and checks if the mime type structure of the revision is retained.

Required for or used by:

  • Full-text search (automatically enabled if full-text module is included)

  • SAP Messenger

computeArchiveRealm

Called when a new document is created to compute the archive realm of the document's binary objects. Archive realm can be computed by the tenant name.

Required for or used by:

  • Archive Configuration

  • Archive

computePartitionKey

Called to compute the partition key for new objects that support database partitioning (documents, folders, blobs, audit events).

createDocument

Called when documents are created. Notifies the full-text engine about newly created documents. Calls SecPKI application server to verify the PKCS7 digital signature. Checks if the incoming document has an PKCS7 digital signature. Creates SAP transfer jobs for archived documents if the document data matches a configured transfer configuration.

Required for or used by:

  • Full-text search (automatically enabled if full-text module is included)

  • SAP Messenger

  • Digital signature handling

deleteDocument

Called when documents are moved to the recycle bin. In case the recycle bin is disabled and "deleteDocument" is called, “eraseDocument” is invoked.

deleteRevision

Called when document revisions are deleted. Notifies the full-text engine about deleted revisions. Prevents deletion of a revision if the revision is going to be registered or is already registered in SAP.

Permits the deletion of a revision which is going to be registered or already registered in SAP and makes the appropriate cleanup of the internal tables. This extension is vital if deletion of revision is permitted.

Required for or used by:

  • Full-text search (automatically enabled if full-text module is included)

  • SAP Messenger

eraseDocument

Called when documents are finally deleted from the system.

initSystem

Called when the system install is executed.

migrateRevision

Called when a revision is migrated via the ImaMigrationService Web Service.

queryFilter

Called after parsing and before execution of a query. Allows custom optimizations or restrictions to be applied to every query.

queryLangInit

Called during query language initialization. Allows registration of custom types, galaxies, and operators.

Used by:

  • Client (automatically enabled if Client is included)

resolveLink

Called whenever a masterdata link with a resolver extension needs to be resolved.

restoreDocument

Called when a document is restored (moved out from the recycle bin).

retentionAssignment

Called when a new document is created. Allows customizing assignments of retention plans to new documents.

(Automatic assignment via a query is possible without any extensions.)

retentionInit

Called at retention management initialization. Allows registration of custom retention management operators.

Required for:

  • Digital Signature

(This extension is available if the signature component is installed. If the signature component is required, there is no standard product extension but rather a project specific extension must be designed.)

revisionFilter

Called whenever an IRevision object is returned from the IntegrationService. Also called before creating or updating documents. Allows modification of revisions returned by the service.

This filter can be circumvented in a SOAP request by the filter header (Header “filter”).

Applies SAP component information to ImageMaster content objects when creating a revision so that documents intended to be registered to an SAP system contain correct component IDs regardless from which client they have been archived. Handles modification of component IDs when updating and deleting content objects of / from a revision to maintain valid SAP component information in SAP registered documents.

Required for:

  • SAP Messenger

selectArchive

Called whenever a binary object needs to be read from an archive. Allows prioritization of the available archives.

textSearchQuery

Called to execute full-text parts from RAQL queries. A project specific implementation is not advised.

Used by:

  • Full-text search (automatically enabled if full-text module is included)

validateConfig

Called to validate SAP configuration that enters the system via Web service.

Required for:

  • SAP Configuration

webServiceContext

Called for each Web service request to analyze the Web service context.

sendMail

Called when an e-mail is sent by the ImageMaster (e.g. password reset e-mail etc.). Allows modification of the e-mail being sent.

Table 369: Extensions overview

Also see the following manuals for information on specific extensions: