Feature Addon Concepts

Feature addons are modules containing custom metadata (classes and properties) and data (objects such as folders, custom objects, and so on) that support extensions to core Content Engine features, as well as support applications that integrate with the Content Engine. A feature addon can be a non-FileNet® product that is compatible with the IBM FileNet P8 platform, or an out-of-the-box addon included with the Content Engine. For a detailed description of IBM FileNet P8 feature addons, refer to Feature Addons in the Content Engine Administration Guide.

The out-of-the-box (or "system") addons are identified by both a display name and a GUID, which maps to SystemAddOnId constants. The display name gives a hint to the underlying functionality of the addon, for example, 4.5.0 Publishing Extensions provides the base functionality necessary for IBM FileNet P8 publishing applications and maps to the SystemAddOnId.PUBLISHING constant. In addition, the DescriptiveText property for each addon describes in more detail the addon's functionality. For example, the value of the DescriptiveText property for the Publishing Extensions addon is: "Extends existing classes with property definitions and creates necessary instance information required by P8 Publishing applications." If you create custom addons, you can populate this property with a description of your choice to help consumers of your addon decide whether they need to install that functionality.

The Content Engine APIs support the registration, installation, and upgrading of feature addons. Before you can install an addon to an object store, you must first create it, which automatically registers it in the IBM FileNet P8 Global Configuration Data (GCD) database of a domain. Once an addon is registered, you can install it to a new or existing object store.

This topic introduces the API interfaces used to create, install, upgrade, and delete addons. For code examples of these interfaces, see Working with Addon-Related Objects.

Creating Addons

An addon is a domain resource. When created, the addon is automatically registered in the FileNet P8 Global Configuration Data (GCD) database. A registered feature addon is also referred to as an "installable" addon. To create an addon, you must have domain-level write permission.

An addon is represented by an AddOn object. As a resource of a domain, you specify the Domain object when you create an instance of an AddOn object, along with a globally unique ID (GUID) that will identify the AddOn in the domain's GCD. You then must specify the object's display name, XML manifest, and addon type. Depending on the addon, you might also need to specify the addon's prerequisites and scripts. Although not required, it is highly recommended that the addon's descriptive text be populated with details of the functionality provided by the addon. See Creating an AddOn Object for a code example.

Upon saving the AddOn object, the related XML manifest and/or scripts are registered in the GCD. To retrieve a list of registered feature addons, get the AddOns property on the Domain object. See Retrieving Registered Addons for a code example.

Note that parameters set on an AddOn object are not validated at object creation time. Instead, errors will be reported during the installation of the object.

A registered addon can be installed on a new or existing object store via the FileNet Enterprise Manager. An addon can also be installed programmatically with the Content Engine APIs.

XML Manifest

An XML manifest contains a representation of the objects to be installed. To create an XML manifest, define your AddOn objects in the Content Engine and export them to an XML file, as follows:

  1. Using Enterprise Manager, create an object store with no addons installed.

    NOTE It is important that you create an object store without addons, not even addons on which the addon you will author logically depends. Otherwise, when you export to an XML file, it will be extremely hard to disentangle the newly authored addon from previously installed addons.

  2. Define the classes, objects, and properties that form the feature addon.
  3. Export the data to an XML file.

For a more detailed procedure, see Add objects to an export manifest in the Content Engine Administration Guide.

Addon Types

You must set the AddOnType property of an addon, which identifies the addon as either optional or recommended. In general, you should specify as optional those feature addons that are not required for your system or that deal with specialized, niche functionality. A recommended feature addon is one that is typically installed as part of most systems.

Addon Prerequisites

An addon might be dependent on other addons, called prerequisites, which must be installed before the dependent addon. The prerequisites for an addon are specified by adding their IDs to the Prerequisites property (an IdList) of the AddOn object. To successfully install a dependent addon to an object store, its prerequisite addons must be installed first. If you specify a prerequisite that is not already installed on the object store, the installation of the addon generates an error and fails.

The order in which you install prerequisite addons does not matter when you have a single dependent addon with multiple prerequisites, as long as you install the dependent addon last. On the other hand, the order you install the prerequisites is important if you have multiple dependent addons, each with one or more prerequisite addons. You must install the prerequisite addons in a sequence that guarantees that they will already be installed so that the dependent addons that identify them as prerequisites will find them available and installed.

Superseding Addons

An older application might need to determine if the functionality it requires is simply present (registered), or present and installed, in the IBM FileNet P8 domain. The application can check the value of the SupersededAddOnIds property of the desired AddOn object. Therefore, it is important when adding new versions of existing addons to populate the SupersededAddOnIds property of the new addon. The value for this property is necessary if the new addon is compatible with the previous addon.

Addon Import Scripts

When you install a feature addon to an object store, the objects defined in the XML manifest are imported into the object store. You can optionally run pre- and post-import scripts when you install an AddOn object. For example, you might run a script to modify security or to add users and groups prior to importing objects.

A script must be written in JavaScript™. The signatures of the pre- and post-import entry points that an addon script must implement are PreImportScriptMethod(objectstore) and PostImportScriptMethod(objectstore). Java™ code can be directly called from within JavaScript. You can configure an addon to use a pre-import script, a post-import script, or both. To perform some action on the object store before the addon is installed, call AddOn.setPreImportScriptStream. If you want your script to perform its tasks after the feature addon is installed, call AddOn.setPostImportScriptStream.

For an example of a script, use FileNet Enterprise Manager to view the PostImportScript property of the Publishing Extensions Addon.

NOTE Import scripts are invoked within the same transaction as the addon's manifest so keeping operations to a minimum is advised.

Installing Addons

An installable addon, that is, one registered in the GCD, can be installed on an object store with the Content Engine APIs. To install an addon, you must have domain-level write permission. In addition, to import data defined in the addon XML manifest and to perform the operations in the pre- and post-import scripts, you must have whatever additional access rights are required for those operations.

To install an addon to an object store, call the ObjectStore.installAddOn method. Input to the method is the AddOn or UpgradeAddOn object to install. Objects installed through the installAddOn method take on the default instance permissions, even if permissions are defined within the XML manifest. If permissions for the objects exist in the manifest, they are ignored. After installation of the objects completes successfully, and before attempting to access the objects, use an approach of your choice to modify the security on the objects. See Installing an Addon for a code example.

When you call the installAddOn method, an InstallAddOn object is created. When you save the ObjectStore object, an AddOnInstallationRecord object is created. You can retrieve the AddOnInstallationRecord object to get installation-related information about the addon, such as the installation status of the addon (Installed or InstallationFailure), an installation report if the install failed, and the ID of the user who installed the addon. You can also retrieve the AddOn object, if it was successfully installed. See Retrieving Addon Installation Records for a code example.

NOTE

Upgrading Addons

The Content Engine APIs provide the UpgradeAddOn interface that allows you to migrate from one set of addons to another set of addons, with each set consisting of one or more addons (see Addon Sets). UpgradeAddOn includes two properties that identify the AddOn objects to upgrade from and the AddOn objects to upgrade to. The FromVersions property specifies one or more installed AddOn objects to be upgraded. The ToVersions property specifies one or more new AddOn objects with the data to upgrade to. When the UpgradeAddOn object is installed on an object store, the addons listed in the FromVersions property are replaced with the addons listed in the ToVersions property. In effect, UpgradeAddOn serves as a migration path: it upgrades an existing object store to the equivalent state of a new object store created with the AddOn objects that are listed in the UpgradeAddOn.ToVersions property.

An UpgradeAddOn object has import data (XML manifest), a pre-import script, and a post-import script, and is installed using the same API method (ObjectStore.installAddOn) as an AddOn object.

The following steps summarize the actions you would take to upgrade an object store from "v1.0Addon" to "v2.0Addon" using the "v1.0to2.0UpgradeAddon".

  1. Create an AddOn object for "v2.0Addon", that is, register it in a domain's GCD. (For this example, assume that the"v1.0Addon" was previously registered in the GCD and is installed on the object store.) The XML manifest for "v2.0Addon" should contain the entire data set, including the updated data that will replace the data in "v1.0Addon".
  2. Create an UpgradeAddOn object for "v1.0to2.0UpgradeAddon". Set the UpgradeAddOn.FromVersions property to "v1.0Addon", and set the UpgradeAddOnToVersions property to "v2.0Addon". The XML manifest for the UpgradeAddOn object should only contain the additions or changes between "v1.0Addon" and "v2.0Addon", not the entire data set.
  3. Install the UpgradeAddOn object to the object store. The XML manifest for the UpgradeAddOn object is used to manipulate the current data in "v1.0Addon" to the updated data in "v2.0Addon".

If the installation is successful, the AddOnInstallationRecord for "v1.0Addon" is replaced by an AddOnInstallationRecord for "v2.0Addon", and the AddOnInstallationRecord for "v1.0to2.0UpgradeAddon" is removed.

If the installation fails, the AddOnInstallationRecord for "v1.0to2.0UpgradeAddon" remains, with a report of the failure set on the object's InstallationReport property.

Note that once the "v1.0to2.0UpgradeAddon" has been applied to all the object stores having the "v1.0Addon" installed, both the "v1.0Addon" and the "v1.0to2.0UpgradeAddon" can be deleted from the GCD, since neither will be referenced by any object store's AddOnInstallationRecordList.

See Creating an Upgrade Add-On for a code example.

Addon Sets

You can upgrade a set of older version addons to a set of newer version addons via a single UpgradeAddOn object. For example, when an UpgradeAddOn object with a FromVersions value of [A1, A2, A3] and a ToVersions value of [A4, A5] is installed on an object store, the AddOn objects for A1, A2, and A3 are replaced with AddOn objects for A4 and A5. Also, the AddOnInstallationRecord objects for A1, A2, and A3 are removed and replaced with AddOnInstallationRecord objects for A4 and A5.

NOTE If one addon in a set fails to import, the installation stops and no attempt is made to install the remaining addons in the list.

Deleting Addons

Using the delete method, you can remove from a domain's GCD UpgradeAddOn objects that have been installed, as well as AddOn objects that have not yet been installed. An AddOn object cannot be deleted if it is currently installed in an object store. Deletion of an UpgradeAddOn is prevented if the UpgradeAddOn references installed AddOn objects in its FromVersions property. (This particular state indicates that the UpgradeAddOn has not completed its use of the referenced AddOn. Once the UpgradeAddOn has been successfully installed and its FromVersions property no longer references installed addons, it can be deleted.).

See Deleting an Addon for a code example.