Upgrading Add-ons

The Content Engine APIs provide the UpgradeAddOn interface that allows you to upgrade one set of add-ons with another set of add-ons on an object store. Like an Addon object, a UpgradeAddon> object must first be registered in a domain's Global Configuration Database (GCD) before it can be installed in an object store.

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 add-ons listed in the FromVersions property are replaced with the add-ons 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.

Note: If one add-on in a set fails to import, the installation stops and no attempt is made to install the remaining add-ons in the list.

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

Step-by-Step Example

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 import dataset 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 UpgradeAddOn.ToVersions property to "v2.0Addon". The XML import dataset for the UpgradeAddOn object should only contain the additions or changes between v1.0Addon and v2.0Addon, not the entire data set.

    When the UpgradeAddOn object is saved, it is registered in the domain's GCD.

  3. Install the UpgradeAddOn object to the object store. The XML import dataset 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.