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 addon included with the Content Engine (also called system addons). For a detailed description of IBM FileNet P8 feature addons, refer to Add-on features in the Content Engine Administration Guide.
The 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.
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. When you create an instance of an AddOn object, you specify the Domain 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, import dataset, 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 for a code example.
Upon saving the AddOn object, the related import dataset 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 with the IBM Administration Console for Content Platform Engine. An addon can also be installed programmatically with the Content Engine APIs.
Import Dataset
An import dataset contains a representation of the objects to be installed. To create an import dataset, define your AddOn objects in the Content Engine and export them to an XML dataset file, as follows:
The export manifest is used to create the export dataset.
The export dataset consists of the metadata that you created with IBM Administration Console for Content Platform Engine. The dataset that's exported from ImpExpCmdTool is the dataset that's imported into the addon when it is created.
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-import 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. For more information, see About import scripts.
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-import 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.
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".
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.
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.