ShowTable of Contents
Introduction
Users of IBM® Lotus® Expeditor, IBM Lotus Notes®, IBM Sametime®, and Lotus Symphony
TM frequently need to update their platforms to install new features or uninstall old features. The most common way to do these tasks is by using the Update Manager user interface (UI) provided by these applications.
Silent provisioning allows users to deploy features across multiple systems with much less user interaction. This article shows how you can deploy features by using DCommands.
We provide an example of the provisioning manifest to be used for DCommands along with details of the structure of the provisioning manifest. We also discuss how to control the target feature installation location and the usage of DCommands, with an explanation of the “provision” and “update” operations.
Using the Update Manager UI
In Lotus Expeditor, for example, you generally follow these steps to install new features:
1. Select File --- Application --- Install, and search for new features to install.
2. In the Feature Updates window, select the “Search for new features to install” radio button as shown in figure 1; click Next.
Figure 1. Feature Updates window
3. In the Application Locations window that displays, select the location for the available application and click OK, as shown in figure 2.
Figure 2. Application Locations window
4. In the Feature License window (see figure 3), select the features to install, accept the terms and conditions, and click Next.
Figure 3. Feature License window
5. The Installation window displays with a list of features that will be installed; click Finish (see figure 4).
Figure 4. Installation window
6. Select Add folder location --- Browse for folder, select the update site; click OK, and click Finish.
7. After the update process completes, restart the application so that your updates take effect by clicking the Restart Now button in the Restart window, as shown in figure 5.
Figure 5. Restart window
Now let's discuss how you can use DCommands to provision features into the platform silently, instead of using the Update Manager UI procedure.
Example provisioning manifest
The provisioning manifest, for example, install.update.xml, is an XML file that lists the features to be installed during the provisioning portion of the install process. An example install.update.xml for a provisioning manifest file is shown in listing 1.
Listing 1. install.update.xml code
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed Materials - Property of IBM
5724-R09
(C) Copyright IBM Corp. 2006, 2007
-->
<ibm-portal-composite>
<domain-object name="com.ibm.rcp.installmanifest">
<object-data>
<install>
<installfeature id="Platform.XPD" required="true">
<requirements>
<feature action="install"
id="Sample_Feature" match="compatible"
url="file:/C:/Install/Expeditor_new/Update_Site"
shared="true" version="1.0.0" mergeaction="add" />
</requirements>
</installfeature>
</install>
</object-data>
</domain-object>
</ibm-portal-composite>
Note these details about certain fields in this code:
- The action field indicates the action for the feature: enable, disable, install, or uninstall, as needed.
- The url field contains the location of the local or remote update site.
- If the value in the shared field is true, it indicates that the feature is to be installed in the shared folder.
Let's now examine the details of the structure of the install.update.xml file, line by line:
<?xml version="1.0" encoding="UTF-8"?> This is the root tag of the CA XML formatted file is.ibm-portal-composite.
<ibm-portal-composite >< domain-object name = "com.ibm.rcp.installmanifest"> This is the domain-object tag with value of the name attribute set to com.ibm.rcp.installmanifest, denoting that this is a provisioning manifest object.
<(object-data)>
<install>
<installfeature>
The list of features is equivalent to InstallShield features, which later can be presented as a list from which users can choose to install certain features. This installfeature tag has the following attributes:
id. The ID of the install feature.
name. The name of the install feature. The value of this attribute can be contributed to an offering installer’s UI when the ReadDeploymentManifest bean is used in the offering installer.
restartPersonality (optional). Used to indicate the personality with which the platform should be restarted, once all the features have been provisioned successfully.
required (optional). Denotes whether this is a required installfeature or can be optionally installed. Default value is false.
mergeaction (optional). Selected values are "add" and "remove. During upgrade scenarios, a pre-existing provisioning manifest is merged with a new manifest, according to the following rules:
- The mergeaction attribute is processed only from the new provisioning manifest and is ignored in the old manifest.
- add. Forces an installfeature specified in the new provisioning manifest file to be retained in the merged result.
- remove. Forces an installfeature specified in the new provisioning manifest file to be removed from the merged result.
- If the mergeaction attribute is not present, then the features within the installfeature are processed against the install feature of the identical ID.
< requirements> The requirements tag denotes a requirements block that contributes a list of required features to be used by the provisioning system.
< (feature)> The feature tag denotes a feature that is required by the platform for a given deployment. This tag has the following attributes:
id. The ID of the feature to be provisioned.
version. The version of the feature to be provisioned.
match (optional). Used to indicate the desired match rule. According to the manifest definition in the Eclipse help, the match rules are as follows:
perfect. Dependent plug-in version must match exactly the specified version. If "patch" is "true", then "perfect" is assumed and other values cannot be set.
equivalent. Dependent plug-in version must be at least at the version specified, or at a higher service level (major and minor version levels must equal the specified version).
compatible. Dependent plug-in version must be at least at the version specified, or at a higher service level or minor level (major version level must equal the specified version).
greaterOrEqual. Dependent plug-in version must be at least at the version specified, or at a higher service, minor or major level.
Match attributes are specified in both the provisioning manifest (user.xml or multiuser.xml) and in the feature itself.
Match attributes are specified in both the provisioning manifest (install.xml) and in the feature itself.
The match attributes specified inside the feature apply to the feature requirements and plug-in requirements for the feature. These are processed by the update manager to determine whether all requirements for the feature have been satisfied.
The match attributes specified in the provisioning manifest are used as a predetermination for installing the feature.
If not specified, then the Eclipse preference setting, org.eclipse.update.core/org.eclipse.update.core.updateVersions, is used.
url (optional). The URL to the update site where the feature can be found. An update site is any valid file URL that contains a site manifest file, a features folder, and a plug-ins folder. For example:
If a URL is not specified, then it is expected that the com.ibm.rcp.provisioning/updateSiteList preference has been updated with a list of update sites from which features will be installed. During the installation process, the installer automatically provides an update site that is used, if the feature does not otherwise have a URL specified.
size (optional). The installed size (in kilobytes) of the feature. It is used by the install application to calculate the total size of the installed product. The size attribute is currently used only by the install application.
download-size (optional). The download size (in kilobytes) of the feature. It is used by the install application to calculate the amount of temporary space required during the install processing. The download-size attribute is currently used only by the install application.
shared (optional). If set to true, the feature will be installed into the shared site (if no other feature version or affinity is satisfied). If false, the feature will be installed into the user site (if no other feature version or affinity is satisfied).
The default setting depends on the install configuration. If a multi-user install configuration is used, the default is true; if a single-user install configuration is being used, the default is false.
action (optional). Selected values are as follows:
install. Install and configure the feature (default).
installonly. Install, but do not configure the feature.
enable. Enable a feature that is currently installed.
disable. Disable a feature that is currently installed.
uninstall. Disable, then uninstall a feature.
ignore. Perform no actions on this feature
mergeaction (optional). Selected values are "add" and "remove. During upgrade scenarios, a pre-existing provisioning manifest is merged with a new manifest, according to the following rules:
- The mergeaction attribute is processed only from the new provisioning manifest and is ignored in the old manifest.
- add. Forces a feature specified in the new provisioning manifest file to be retained in the merged result.
- remove. Forces a feature specified in the new install manifest file to be removed from the merged result.
- If the feature is present in both the old and new manifest, and
- the mergeaction attribute not specified, then the feature is retained with the attributes define in the new manifest.
- mergeaction = "add", then the new feature is retained completely.
- mergeaction = "remove", then the feature is removed.
- If the installfeature is present in the old manifest and does not exist in the new manifest, it will be retained completely.
- If the installfeature is not present in the old manifest, it will exist only in the result if mergeaction="add" is specified.
The rest of the code is as follows:
</requirements>
</installfeature>
</install>
</object-data>
</domain-object>
</ibm-portal-composite>
Controlling the feature installation location
This section explains the available methods for controlling and specifying the target installation site for a feature. The platform provisioning system defines by default the following target sites into which features are installed:
rcp. This target site contains the features and plug-ins that are part of the Eclipse and client platform.
shared. This target site contains additional features and plug-ins intended for use by all users of the client platform.
user. Located in the workspace, this target site contains additional features and plug-ins intended for use only by a single user of the client platform.
The target installation site for a particular feature is determined by evaluating several conditions, including whether the feature is currently installed, collocation affinity, ability to write a specific directory, and requested target site.
Collocation affinity is an attribute that can be specified by each feature in the feature.xml descriptor and specifies the ID of another feature. It directs the provisioning system to attempt to install the new feature into the same target site that the other feature, that is, the feature whose ID is specified in the feature.xml, uses.
Using the Feature Manifest Editor from the Plug-in Development Environment, we can specify the collocation affinity on the Installation page of the Editor.
For example, suppose that a feature with an ID of com.ibm.sample has been installed in the shared site. A new feature with an ID of com.ibm.extendedsample can then specify a collocation affinity of com.ibm.sample to request that the feature is installed in the same location as com.ibm.sample, as shown in listing 2.
Listing 2. com.ibm.extended sample code
<feature
id="com.ibm.extendedsample"
label="Extendedsample Feature"
version="1.0.0"
provider-name="IBM"
collocation-affinity="com.ibm.sample">
The platform provisioning system uses these decisions to determine the target site for a feature, following this process:
- If a provisioning system detects a version of the feature that is already installed, the same installation site is used for any additional versions. This decision applies only when the feature has been installed into the Eclipse, RCP, or shared target sites.
If a deployer installs a feature X, version 1.0.0, in the shared site and later attempts to install feature X, version 1.0.1, then version 1.0.1 is installed in the shared site.
If user A installs a feature Y in the user site in workspace A, and later another user B attempts to install feature Y, then feature Y is installed a second time in workspace B because workspace A is not visible to user B.
2. If feature.xml specifies the collocation affinity attribute, then the following decisions are made:
a) If the feature that was specified in the collocation affinity attribute is installed, then attempt to install into that site. If that site is not accessible to the user installing the feature, then the feature installation fails.
b) If the feature that was specified in the collocation affinity attribute is not installed, then continue with step 3 in the decision process.
3. If a specific target site is requested for the feature, then attempt to install the feature into this site. If that site is not accessible, then continue with step 5. A target site can be specified only for features distributed through the Eclipse feature distribution job using the Device Management server.
4. If the provisioning manifest or a ProvisioningRequest (provided through an API request) specifies shared = true, then the shared site is the desired target site for installing the feature. If that site is not accessible, then continue with step 5.
5. If the provisioning manifest or a ProvisioningRequest object specifies shared = false or, if because of accessibility issues, the desired target sites for steps 3 and 4 are not available, then attempt to install the feature in the user site.
Because the collocation affinity takes precedence over the target site or shared attribute specification, specifying a collocation affinity is the preferred model for controlling feature installation locations. The client platform has defined the following features that can be used as targets for the collocation affinity attribute:
com.ibm.rcp.site.anchor.shared.feature. This feature is always installed into the shared site.
com.ibm.rcp.site.anchor.user.feature. This feature is always installed into the user site.
If the platform is used only by a single user with a single workspace, then the target site for a feature is less important because all features are always available. In the multi-user configuration, however, the target installation site becomes much more important because some applications are shared among all users of the platform, while other applications are private to specific users.
For example, assume a multi-user configuration in which deployers have administrator rights to the shared directory, and ordinary users are limited to read-only rights. Feature W does not contain a collocation affinity attribute.
If a deployer attempts to install this feature, it is installed into the shared directory because this location is the default option with no collocation affinity and no target site specified.
However, if a user attempts to install this feature, it is installed in the user target site and cannot be shared by all users on the platform. The user site is selected because the shared site is not accessible.
To limit the ability of a specific user to install feature W into the user site, the deployer can specify a collocation affinity attribute with the ID, com.ibm.rcp.site.anchor.shared.feature. The resultant site for a deployer is still the shared site, chosen now not because it is the default, but because the collocation affinity selects that site.
If a user attempts to install the feature, the installation will fail because the site specified by the collocation affinity is not accessible.