Understanding and troubleshooting plug-in installation for IBM Lotus Eclipse-based products

Introduction

Installing third-party features onto Expeditor platforms requires knowledge of various Lotus products such as Lotus Notes, Lotus Symphony, and Lotus Sametime, as well as the install mechanism. This section briefly introduces these products and the install components; they are discussed in more detail in subsequent sections.

Lotus Expeditor and its derivations

Lotus Expeditor is a universal desktop client integration framework designed for the construction, integration, and deployment of "managed client and server applications" in business mashups. It helps you deploy, configure, and manage various client applications onto a desktop, usually by a remote server.

The goal is to let developers create applications that take advantage of running on a local client while having the same ease of maintenance as Web-based applications. Lotus Expeditor also provides the core client technology for Lotus Notes (as of version 8), Lotus Sametime (as of version 7.5), and Lotus Symphony.

Expeditor install components

• UPDATESITE.ZIP. This file is the key mechanism to enabling installation of the applications. It includes many plug-ins, features, and manifest files. By using UPDATESITE.ZIP, we can update a target platform through plug-in management tools with specific platforms.

• Installer. An installer allows a customized installation of your application with pre-defined customized actions rather than using a single UPDATESITE.ZIP, which can also be installed through the management tools in Expeditor-based platforms.

• Manifest. Feature manifest is used to control the provisioning portion of the install. It is a file that is external to the installer and can be modified by developers to define the set of features to be provisioned and installed.

During the install, the Expeditor CoreAction module reads the provisioning manifest to get the total size of the features to be provisioned and stores the file to {install_dir}/rcp/deploy/install.xml (or install.upgrade.xml, in the case of an upgrade). It is then used by the provisioning plug-in to provision the desired features to the platform.

• Feature. A feature is the only level of installable unit that exists. It encapsulates plug-ins of different kinds and groups them by functionality. You cannot choose to install only certain plug-ins from a feature.

• Plug-in. A plug-in provides the core logic capability for the application, but it must be grouped by feature in order to be installed by use of the plug-in management tool. Multiple plug-ins can be shared among different features. The plug-in development platform provides wizards for creating features. Figure 1 is an architectural overview for the four key install components.

Figure 1. Add-on install components

• RCPLauncher. This is an embedded tool within the Expeditor framework that operates changes to Expeditor-based platforms. It can be called from a command line and serves as a common interface for any platform-level operations.

Installing plug-ins

There are three ways to install features on top of UPDATESITE.ZIP:

A. Plug-in management tool
Installing plug-ins using the management tool is a simple way to put plug-ins to work, requiring only UPDATESITE.ZIP as an input. Its advantage is that its quite very simple and does not need programming or any additional development.

Lotus Notes. Lotus Notes does not publicly provide a plug-in management tool for plug-in install; however, you can enable it, using these steps:

1. Open {notes_install_folder}/framework/rcp/plugin_customization.ini and add this line at the end: com.ibm.notes.branding/enable.update.ui=true
2. Restart Lotus Notes, and select Files – Application – Install. The Install/Update wizard displays.
3. Choose “Search for new features to install” and click Next.
4. In the Application Locations window, click Add Zip/Jar Location, select UPDATESITE.ZIP, and click Finish.
5. In the Search Results window, select the feature, and click Next.
6. In the Feature License Window, select Accept and click Next.
7. Click Finish to start the installation and then restart Lotus Notes.

Lotus Symphony. Offers this functionality by default. Refer to the Plug-In Installation Guide for more details.

Lotus Sametime. Likewise, this functionality is also enabled by default. The wizard can be found via Tools – Plug-ins – Install Plug-ins. Everything else is similar to the instructions for Notes.

B. Expeditor Add-on toolkit
Expeditor Add-on toolkit is an install framework based on InstallShield, intended to provide a customized installation of additional features and plug-ins into Expeditor-based platforms. It provides simple customizations for users who want to add version check, change strings, change and define target platform, etc.

Multiple add-on installers can be targeted to the same product, each of which can be installed and uninstalled separately from the product. Add-on installation and uninstallation does not affect the product's original functionality. Using the Expeditor Add-on toolkit, you can perform common install customizations within its pre-defined configuration framework.

C. InstallShield project
If there exists an install customization that Expeditor Add-on installer cannot handle, such as uninstalling shared features across multiple applications, accessing other add-on applications during the install, or adding specific warnings, then creating an installer from the InstallShield project would be an ideal solution. To start an InstallShield project, refer to the InstallShield library Help and select → Contents → Tutorial → Basic MSI Project Tutorial.

Processing Updatesite.zip

Now that we've discussed how to install plug-ins in the three Expeditor-based platforms, let's have a closer look at how UPDATESITE.ZIP is processed by these platforms (see figure 2).

Figure 2. Processing UPDATESITE.ZIP


Pre-processing manifest file. This step includes configuring the features we want to include, listing them in a manifest file, and adding security certificates to keystore so that signed features are trusted during install and updated from the media kit.

Initial provisioning. The Expeditor installer installs and initially provisions new or updated features from the install kit's update site, UPDATESITE.ZIP. During initial provisioning, trust is based on the Java^TM keystore file in the Lotus Expeditor install media kit's "deploy" directory. This keystore contains the IBM code signing certificate.

By default, only features and plug-ins that are signed with certificates will be installed. The items in the Expeditor install media kit, UPDATESITE.ZIP, must be signed, including custom or third-party features and plug-in JAR files. This process seeks to verify the signature.

Provisioning and installation. In this stage, the provisioning manifest is processed (replacing any supported variables) and copied to

{product destination}/rcp/deploy/install.xml

RCP Launcher then reads rcplauncher.properties from 

{notes_install_folder}/framework/rcp/rcplauncher.properties

to determine the provisioning.manifest.version property, and compares it to the version currently specified in the rcpinstall.properties.

If the version in rcplauncher.properties is later than the version in the rcpinstall.properties file, then launcher will start the platform provisioning application to update the platform based on the provisioning manifest (specified in rcplauncher.properties).

By updating the provisioning manifest contents and the provisioning.manifest.version, the launcher starts the provisioning application to process the provisioning manifest.

Merge processing. While provisioning manifest can be directly updated on the system, the preferred model for distributing a new manifest is to use the mergemanifest command provided by the Global Install Handler. Obviously, this is a much safer option.

The install handler provides a mechanism to install a new provisioning manifest and to merge it with the existing manifest on the system. This enables the deployment of a subset of new changes that are merged into the existing manifest without requiring the specification of an entire file.

When a new provisioning manifest is merged with an existing provisioning manifest, the new provisioning manifest can contain mergeaction attributes on the features and installfeatures present in the provisioning manifest. The mergeaction attributes provide the rules on how to merge the content of the two provisioning manifest files.

Log tracing

We install UPDATESITE.ZIP on Expeditor-based platforms, using Microsoft® Windows® Installer; therefore, there are two places we can obtain log tracing: the Windows installer log and the Expeditor platform log. If errors are ever returned, we first collect the logs, using the instructions below:

Windows Installer logging
Windows Installer tracks the install progress by posting it to the Temp folder. This log tracing is enabled by default. To locate the folder, type cd %temp% at a command prompt. The new log's file name is random, but begins with the letters "Msi" and ends with a .log extension.

You can also order files by create time, so you can easily locate the newly generated file. Note that, if log tracing is disabled, then open the Windows Registry with Regedit.exe and create the following path and keys:

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer
Reg_SZ: Logging
Value: voicewarmupx

Expeditor logging
Different platforms put logs in different locales, as follows:

Lotus Notes:
Single user: {Notes_install_folder}/Data/workspace/logs,
Multiple user: %userprofile%\Local Settings\Application Data\Lotus\Notes\Data

Lotus Symphony:
{Symphony_install_folder}/framework/installer_logs

Lotus Sametime (Notes embedded):
C:/Documents and Settings/{User_Profile}/Application Data/Lotus/Sametime/logs

Case study

In this section, a real-world project called Lotus Quickr Connectors is used to illustrate how UPDATESITE.ZIP is installed on Expeditor-based platforms. Using this example, we further explain the different installation stages from the code level.

This project's goal is to install six connectors: Lotus Notes, Symphony, and Sametime, and Microsoft Internet Explorer, Office and Outlook. In this section only the first three connectors are discussed. Although the install process for the three connectors is similar, there are some differences.

For Lotus Notes, because there may exist feature dependencies, installation needs to be conducted in two different provisioning settings to avoid dependency conflicts. That means the Notes provisioning component must provision required features ordered in two groups, and thus two manifests are used for each provisioning.

For Lotus Symphony, since there are two different install settings, standalone and embedded, two manifests are required for different user options.

For Lotus Sametime, UPDATESITE.ZIP file must be uncompressed before the install proceeds.

Since the whole procedure uses UPDATESITE.ZIP to install features, you need to understand that the UPDATESITE.ZIP file is basically composed of a set of features, affiliated plug-ins, and a manifest showing how many features will be installed.

Now let's see how to the install process is performed from several C++ code snippets:

1. Initialize required variables and collect path information:

uiMsiRc=ExtractPropFromCustomActionData(hInstall,L"QC_PROP_EXEC_FOLDER",szUpdateSitePath,&cchPathRes);detect UPDATESITE.ZIP path using InstallShield App Search

2. Copy feature list from a temporary file to official manifest, install.update.xml, and then replace tokens (used mainly for re-using manifest):

open Authentication feature list and copy to a temp XML file
uiMsiRc = ExtractPropFromCustomActionData(hInstall, L"SUPPORTDIR", szUpdateSitePath, &cchPathRes);
while(!(file.ReadString(tmp) == FALSE)) {
xml = xml + tmp; }
file.Open(lstrcat(szInstallManifest,L"install.update.xml"),CFile::modeCreate | CFile::modeReadWrite | CFile::typeText)

3. Copy new keystore information and sign the code with an IBM-specific signature. This means that UPDATESITE.ZIP must also be built on the official build server, or else it will return the warning: “Cannot extract properties from ”.

copy new keystore
uiMsiRc = ExtractPropFromCustomActionData(hInstall, L"SUPPORTDIR", szTempPath, &cchPathRes);
PathAppend(szTempPath, TEXT("keystore.JCEKS.IBM_J9_VM.IBM"));
PathAppend(szKeystorePath, TEXT("framework\\rcp\\deploy\\.keystore.JCEKS.IBM_J9_VM.install"));

4. Raise to Administrator rights and run the RCP Launcher command to warm up the Expeditor workspace for application provisioning:

set USERNAME variable if not already set
DWORD dwRet = GetEnvironmentVariable(L"USERNAME", strUserName, MAX_PATH);
if(dwRet == 0) SetEnvironmentVariable(L"USERNAME", L"Administrator");

5. Start real provisioning, using the manifest file along with other specific arguments:

warm up workspace first and then install feature through RCP Launcher
argsPrep[0] = rcpcommand; argsPrep[1] = TEXT("-rcpLauncherWait");
argsPrep[2] = TEXT("-noSplash");argsPrep[3] = TEXT("-application com.ibm.rcp.provisioning.application.ProvisioningApplication");
sys = rcpcommand;
SpawnRcplauncher(sys,argsPrep)
args[0] = rcpcommand; args[1] = TEXT("-rcpLauncherWait");
args[2] = TEXT("-noSplash");args[3] = TEXT("-application com.ibm.rcp.provisioning.application.ProvisioningApplication");
args[4] = argProv;args[5] = TEXT("-vmargs");
args[6] = TEXT("-Drcp.system.admin=true");
SpawnRcplauncher(sys,args)

Note that all the preparation and provisioning steps are invoked via the function SpawnRcplauncher, which executes commands while recording corresponding action details into install logs of Expeditor-based platforms. For details on how to find the logs, refer to Section 4, "Log tracing."

Troubleshooting tips

In this section, common error patterns and corresponding diagnostics are presented. We use Lotus Notes but, since the install processes of Expeditor-based platforms are all similar, the same diagnostics can be applied to any other Expeditor-based platform.

Install-related issues

(1) Installer: When using the Add-on Install toolkit, you must execute the installation using the .exe program rather than .msi program.

Although they act similar in Windows XP, using the .msi program for the Windows Vista and Windows 7 series will cause the install to fail because the .exe program can use Administrator rights to pass User Account Control (UAC) and conduct the install. Besides, running execution with .exe program lets you choose different languages for install.

(2) Data Roaming: Whenever the installer is interrupted or aborted, the corresponding log information can be found in the Expeditor log folder; however, sometime there can be some false warnings that are irrelevant, for example, the roaming error shown in figure 3.

Figure 3. Example false error


The message means that Lotus Notes is in a roaming user status. As a roaming user, when you start Lotus Notes on any computer, your roaming-enabled data is obtained from the roaming server, and a local replica of those applications is created or updated on the computer on which you are working.

Lotus Notes also copies some information such as user preferences and Notes.ini file settings from your roaming server to your local computer. If you make changes to these local replicas, for example, installing plug-ins using the Add-on installer, data is synchronized back to your roaming server on a scheduled basis. So you can disregard the warning.

(3) Security provisioning: A build generated on a local machine cannot be safely and fully installed because it is not signed by official build servers. Without authenticate signatures, the installation cannot pass security provisioning within Expeditor-based platforms (see figure 4).

Figure 4. Fail to pass Notes security check errors


An official production build is signed by certificates that build room owns. Note that none of the
FE level in build.properties file disables .jar signing, so you may want to check your FE to be sure. The build.properties are as follows:

enable.jarsigning
enable.fesigning
do.sign.inner.jars

Also, you can use the jarsigner tool (part of Java Development Kit) to verify that your official build is signed:

jarsigner -verify

To avoid such security checks, you can simply disable the security check by modifying configurations to pass the install provisioning. To do this:

1. Open the file: {Notes_install_dir}/framework/rcp/plugin_customization.ini
2. Set this property:
   

com.ibm.rcp.security.update/VERIFICATION_LISTENER=com.ibm.rcp.security.update.NullVerificationListener

4. Reordering manifest: In provisioning, manifest features are not provisioned orderly, meaning that reordering features does not have any impact on the installation. Features are provisioned all at once, so if there is any erroneous feature, the initial provisioning will fail immediately.

5. Upgrading and downgrading: When features of multiple versions are installed, repaired, or updated, the platform will automatically override the one with an older version number. This means that feature downgrading is not encouraged. To downgrade plug-in applications, you must uninstall the newer version of the application first and then install the older one.

6. Shared features: If any feature dependencies exist, we need to handle it by installing the independent ones first, using one manifest, and then install the dependent ones, using another manifest file. Since features manifest are provisioned all at once, reordering features in manifest does not work in this case.

Uninstall-related issues

1. Uninstalling: When features are uninstalled, you must disable the plug-ins/features being used first and then run the application provisioning. If you don't disable features that are being used, RCP Launcher will return an error and the uninstall will be aborted.

Basically, uninstalling does not trigger too many log tracings. Since uninstall errors are not that common compared with install errors, you can totally avoid this type of error by developing a well designed uninstaller.

2. Shared features: When shared features are to be removed, even if disabling is done, the processes will still fail since Lotus Expeditor does not support this kind of uninstall check.

To tackle this feature dependency issue, we need to remove the shared features first and then remove the standalone ones. By doing this in two steps, we can properly remove such feature dependencies.

Conclusion

This article has explained the detailed processes of how Expeditor-based platforms (Notes, Sametime, Symphony) provision and deploy UpdateSite.zip into existing settings. It also explained how to run and debug the plug-in install on these platforms, along with sets of best practices, and summarized solutions for common errors occurring on the three platforms.