Creating a customized addon installer 

Addon installers allow for installation of additional features and plugins into an Expeditor-based target product.  Multiple addon installers can be targeted to a product, and each addon installer can be installed and uninstalled separately from the product.  The following instructions describe how to use customization kits to create customized addon installers for Expeditor-based products.

Customizing for Linux

The following steps detail how to create a customized addon installer for Linux. Unlike on Windows, customizing a Linux addon does not involve modifying an existing, built installer, but rather creating a whole new RPM install package after modifying the provided spec file. The created RPM package can be converted to a Debian package later by using the Alien conversion utility.

Linux preparation

These preparatory steps only need to be done once on your development machine, which must be a Linux machine that supports RPM building.

1. Unzip the addon customization kit for Linux to a working directory.
2. Update the packaged license files, if you wish to display/require license acceptance:
1. Overwrite the provided dummy license files (RTF format) must be provided in the /license/ directory. You must keep any license filenames the same.
2. If you do not wish to provide license information within your addon package, you may remove the license/ directory entirely.
3. Replace the feature and plug-in in the content directory with your own addon feature(s) and plug-in(s) in the provided shared/eclipse/ site structure. By default, this structure is populated with a dummy test feature, provided as an example.

NOTE: During the building of the package, if a license directory is present, its contents will be moved to license// within the finalized package. This is done to avoid potential file ownership conflicts amongst other addon pacakges.

Customizing the spec file

To customize the provided spec file for use with your Linux system, edit the xpd-addon.spec file and modify the following tags. Knowledge of RPM spec files is assumed, so a full explanation of these tags is not provided.

• Summary -- change the summary to one appropriate to your addon
• Name -- set the name of the addon; built RPMs will have the format of --..rpm
• Version -- set the version of the addon
• Release -- set the release of the addon
• Vendor -- change the vendor information
• Provides -- set to the list of components provided, if any
• Requires -- set to require the base product the addons should install into (for example, "expeditor" or "ibm_lotus_notes")
• Prefix -- should be set to the default location of the base product (for example, /opt/ibm/lotus/Expeditor or /opt/ibm/lotus/notes)
• %description -- provide a description for the addon
• KIT_DIR within %build -- change to the location where the addon customization kit was unpacked

Customizing the deploy contents

The Linux customization kit contains a deploy/ directory which holds the default install and uninstall manifests for the addon. These manifests are named install.xpd-addon.xml and uninstall.xpd-addon.xml. The following customization should be done for the manifests.

1. Modify the contents of install.addon.xml to include your feature(s). Rename the id to something unique for your addon and ensure that mergeaction="add" is set. Replace the existing entry with your set of features to install. Ensure that each entry has action="install".
2. Make the same edits to uninstall.addon.xml as done for the install manifest shown above, however, ensure that each entry listed has action="uninstall".
3. If you wish to add/change preferences using the plug-in_customization.ini, make the desired edits in the file according to the sample structure provided in the comments in that file. If you don't need to add/change any preferences during addon install, the plugin_customization.ini file can be removed.

NOTE: Features included in the addon should not be placed into the rcp/ site under any circumstances. Doing so will jeopardize their existence whenever the base product is upgraded (as the rcp/ site is totally wiped and recreated). So ensure that any included features in the addon are not upgrades to any existing platform features in the rcp/ site or have an internal colocation-affinity set to any existing platform feature in the rcp/ site. By default, the structure provided assumes all addons will go into the shared/ site in the platform.

NOTE: During the building of the package, the install.addon.xml, uninstall.addon.xml and plugin_customization.ini will be renamed as install..xml, uninstall..xml and plugin_customization..ini, respectively, within the finalized package. This is done to avoid potential file ownership conflicts amongst other addon pacakges.

Building the RPM package

To build the RPM package, run rpmbuild -bb xpd-addon.spec to build the binary package of the RPM. The RPM build begins and, assuming it is successful, the RPM package will be placed into /usr/src/redhat/RPMS//--..rpm by default.

Converting from RPM to Debian packaging

On Ubuntu systems, Debian packaging is used. A quick way to convert an RPM package to a Debian package is to use the Alien utility.

1. First obtain the alien program, if not already present, with sudo apt-get install alien.
2. After alien is installed, directly convert the RPM with sudo alien -ck .
3. A Debian package, named __.deb, will be generated.

The Alien utility will make some automatic assumptions about certain control fields that are not directly convertible from RPM packages (such as Priority, Section, and Depends). If you wish to make changes to this control data, then you will have to use Alien to generate the build tree (using sudo alien -gck ) for the package and then make edits to the debian/control file before building the Debian package. Instructions for building Debian packages directly can be found at http://www.debian.org.

Customizing for Windows

The following steps detail how to customize the addon installer for Windows. The addon customizer tool will be used for the majority of the customization. All steps are listed here, but not all steps are required -- optional steps are marked with (optional).

The CustomizeAddon.exe tool is present in the addon installer kits located in the utils\addon_customization directory of the Expeditor install package.

Windows preparation

The following preparatory steps only need to be performed once on your development machine:

1. Unzip the addon customization kit for Windows to a working directory.
2. Update the externally packaged license files, if you wish to display/require license acceptance. Overwrite the provided dummy license files (RTF format) must be provided in the /license/ADDON_NAME/ directory.
NOTE: License filenames and the ADDON_NAME directory must remain the same.

Customizing the MSI using the addon customizer tool

The customizer tool currently handles the following items:

• Package, product, and upgrade code generation.
• License importing into the MSI and the MST files.
• Update of select properties in the Control, Properties, Binary, Icon, Directory and Upgrade tables.
• Renames the MSI file.
• Updates properties in the Setup.ini file.
• Updates the input config file with the UpgradeCode in use.

To create your customized Addon Installer:

1. Configure the AddonConfig.ini file located in the installer kit with the required and optional values described in the "Example AddonConfig.ini contents" section below.
2. Configure the deploy manifest files located in the install/deploy directory, using the instructions found in the "Customizing the deploy contents" section below.
3. Copy your update site to the 'updateSite' directory in the installer toolkit.
4. From a command prompt, run CustomizeAddon.exe <source dir> <destination dir> [location of AddonConfig.ini]" where:

<source dir> is the location of the installer toolkit that contains the directories with the deploy manifests and your valid updateSite
<destination dir> is where you want your customized installer to be written. Note: This must be a fully qualified path, not a relative path
[location of AddonConfig.ini] is an optional parameter which allow you to specify a different location for the AddonConfig.ini file other than the default directory which is the current location of the CustomizeAddon executable.

The CustomizeAddon tool makes a copy of the install kit directory and modifies the MSI based on the properties you set in the AddonConfig.ini. In order to avoid bundling the entire tool with your plugin installer, a best practice when creating your installer is to move the CustomizeAddon.exe and AddonConfig.ini out of the installer kit to a separate directory before executing the tool.

Once the CustomizeAddon tool runs successfully, your installer will be in the <destination dir> specified and can be tested/packaged for use by your users.

Example AddonConfig.ini contents

You can add the following properties to the input AddonConfig.ini file to customize the addon installer. The properties are used to modify values in tables within the MSI file (Property, Icon, Binary and Directory tables are modified) and within the Setup.ini file:

• MSIFileName -- (required) the new msi file name
• ProductName - (required) set to your addon's display name and version (this is used for display purposes only in some panels)
• ProductNameNoVersion -- (required) set to your addon's display name
• ProductVersion -- (required) set to your addon's version (in format major.minor.build, with maximum value of 255.255.65535)
• TargetProductName -- (required) set to the name of the product your addon intends to install into (this is used for display purposes only in some panels)
• TARGETUPGRADECODE1 -- (required) set to the UpgradeCode value of the product your addon can install into  (Expeditor Client uses UpgradeCode {D0ACD8C4-9DC8-41AB-BBCA-B90259CD96B0})
• TARGETUPGRADECODE2 -- set to the UpgradeCode value of a second product your addon can install into (optional -- used mainly for installing into Notes since Notes has AllClient and NotesClient versions)
• TARGETUPGRADECODE3 -- set to the UpgradeCode value of a third product your addon can install into (optional -- used mainly for installing into Notes since Notes has AllClient and NotesClient versions)
• TARGETVERSIONS1 -- set to the supported version(s) of the target product defined by TARGETUPGRADECODE1, in the format of ;;...; (wildcards using * are acceptable, and a blank value means all versions are supported). For example: TARGETVERSIONS1=8.0.2;8.5.*
• TARGETVERSIONS2 -- set to the supported version(s) of the target product defined by TARGETUPGRADECODE2, in the format of ;;...; (wildcards using * are acceptable, and a blank value means all versions are supported). For example: TARGETVERSIONS2=8.0.2;8.5.*
• TARGETVERSIONS3 -- set to the supported version(s) of the target product defined by TARGETUPGRADECODE3, in the format of ;;...; (wildcards using * are acceptable, and a blank value means all versions are supported). For example: TARGETVERSIONS3=8.0.2;8.5.*
• EMBEDDED -- set to "true" if you wish this to be an embedded addon, or leave as "false" (default) if you wish this to be an external addon
• NOLICENSE -- set to "true" if you do not wish to have the LAP panel used or licenses laid down, or leave as "false" (default) if you wish to display/require license acceptance and have license files laid down.
• LicenseDir - (only required if NOLICENSE =false) replaces the default  ADDON_~1|ADDON_NAME  DefaultDir value in the Directory table within the MSI. It also updates the external directory name used for your licenses ( /license/). This is the directory name used for the destination of the license files laid down on disk during installation ( /rcp/license/).
• The LicenseDir value should be in the format of <short name>|<long name> -- where is first_six_characters_of_longname~1
• Example: Sameti~1|Sametime Advanced
• UpgradeCode -- modify this to be a unique code. By default, a unique code is automatically generated and saved to the AddonConfig.ini file after tool execution. This new value must be used for this property in any future customizations of your addon MSI (for example, the UpgradeCode should never change for your addon once it has been set.) The tool also modifies the UpgradeCode entry in the Upgrade table.
• XPD_WizardImage --specify a location of the new bitmap image. Modified in the Binary table, it utilizes the new bitmap as the dialog background image. The image is displayed on the left hand side of dialogs. Alternatively, you can place an image with the file name "wizard.bmp" in the <addon source dir>. The bitmap image size should be 160 x 314.
• ARPProduction.exe --specify a location of the new icon image. Modified in the Icon table, it utilizes the new icon to display in the Add/Remove Programs. Alternatively, you can place an image with the file name "arpicon.ico" in the <addon source dir>.
• LauncherName -- sets the LauncherName value in the Setup.ini file and renames the setup.exe file.
• EnableLangDlg -- sets the EnableLangDlg value in the Setup.ini file. Set the value to "Y" if you wish to show an initial language selection dialog before install begins.

The following is an example AddonConfig.ini:

MSIFileName=TestAddon.msi
ProductName=Addon for Company XYZ 1.0.0
ProductNameNoVersion=Addon for Company XYZ
ProductVersion=1.0.0
TargetProductName=Lotus Notes
TARGETUPGRADECODE1={D8641E4B-77AF-4EAC-9137-8D4DCB1478E2}
TARGETUPGRADECODE2={A68F0A65-F902-4EDA-AF80-0953B586DAA8}
TARGETUPGRADECODE3={5BA7CD07-4D6C-4D16-B1A6-2B50DD5F17AD}
TARGETVERSIONS1=8.0.2;8.5.*
TARGETVERSIONS2=8.0.2;8.5.*
TARGETVERSIONS3=8.0.2;8.5.*
NOLICENSE=false
LicenseDir=TestAd~1|TestAddon for Company XYZ 1.0.0
LauncherName=setup.exe
EnableLangDlg=N

Customizing the deploy contents

The Windows customization kit build contents contain an install/deploy/ directory which holds default install and uninstall manifests for the addon, as well as a sample plug-in customization file. The following customization should be done for the manifests:

1. Modify the contents of install.addon.xml to include your feature(s). Rename the <installfeature> id to something unique for your addon and ensure that mergeaction="add" is set. Replace the existing <feature> entry with your set of features to install. Ensure that each <feature> entry includes action="install".
2. Make the same edits to uninstall.addon.xml as done for the install manifest shown above, however, ensure that each <feature> entry listed includes action="uninstall".
3. If you wish to add/change preferences using plugin_customization.ini, make the desired edits in the file according to the sample structure provided in the comments in that file. If you don't need to add/change any preferences during addon install, the plugin_customization.ini file can be removed.

NOTE: Features installed by addon should not be installed into the rcp/ site under any circumstances. Doing so will jeopardize their existence whenever the base product is upgraded (as the rcp/ site is totally wiped and recreated). Ensure that any included features in the addon are not upgrades to any existing platform features in the rcp/ site or have an internal colocation-affinity set to any existing platform feature in the rcp/ site.

Example deploy contents

The following show some example content of what your deploy files may look like:

install.addon.xml

uninstall.addon.xml

plugin_customization.ini (optional)

Customizing the Setup ini

The provided setup.exe can launch the install and automatically do locale detection, applying the correct .mst language transform to the .msi file. However, this does require more customization. If you do not wish to make use of the setup.exe, then the setup.exe, Setup.ini and 0x.ini files are not utilized.

NOTE: If you are not making use of the setup.exe in your addon, this section can be ignored.

The customization tool automatically updates the following properties:

• Product -- set to the ProductName value from step 3 under Customizing the MSI using the Addon Customizer Tool
• ProductCode -- set to the ProductCode value automatically generated.
• ProductVersion -- set to the ProductVersion value from step 3 under Customizing the MSI using the Addon Customizer Tool
• PackageCode -- set to the PackageCode value automatically generated.
• PackageName -- set to the new name of your .msi file, from step 3 under Customizing the MSI using the Addon Customizer Tool
• LauncherName -- set to the LauncherName value and renames the setup.exe file, from step 3 under Customizing the MSI using the Addon Customizer Tool
• EnableLangDlg -- set to the EnableLangDlg value from step 3 under Customizing the MSI using the Addon Customizer Tool

List of valid UpgradeCodes

For Windows, each Addon installer must list at least one product upgrade code to which it can install. It can specify up to three. These are specified in TARGETUPGRADECODE1, TARGETUPGRADECODE2 and TARGETUPGRADECODE3. The following UpgradeCodes from these supported products can be used: 

Product	Version(s)	UpgradeCode
Expeditor	*	{D0ACD8C4-9DC8-41AB-BBCA-B90259CD96B0}
Domino Designer client	*	{D8641E4B-77AF-4EAC-9137-8D4DCB1478E2}
Notes client	8.0 - 8.0.*	{A68F0A65-F902-4EDA-AF80-0953B586DAA8}
Notes client	8.5 and higher	{5BA7CD07-4D6C-4D16-B1A6-2B50DD5F17AD}
Sametime	*	{98DAC193-E124-4ADB-8D3C-319B7CA13418}
Symphony	*	{6C72554F-78B1-4406-A037-364BAF7B4860}