ShowTable of Contents
Introduction
IBM® Lotus® Notes® version 8 is based on Eclipse to provide a highly productive and integrated development experience for a wide range of business applications. All the functions in Lotus Notes are packaged as plugins/features.
Installing/uninstalling features is a common Notes operation, so in this article, we discuss seven approaches to manage Notes features; specifically, via:
-
update manager
-
composite applications
-
widgets
-
provisioning
-
the feature panel
-
the Addon installer
-
the Enterprise Management Agent
Prerequisites
For the purposes of this article we used one machine with the Notes Client 8.5.3 installed and an Eclipse update site.
Update manager
Update Manager is directly from Eclipse and is frequently used to install/uninstall features. The Update Manager function needs to be enabled in Notes.
Install features via update manager
To do this, use these steps:
-
The update manager function in Lotus Notes is disabled by default, so we need to enable it by changing “enable.update.ui=false” to “enable.update.ui=true” in the file com.ibm.notes.branding.prefs in the directory “<Notes_workspace>\.metadata\.plugins\org.eclipse.core.runtime\.settings\”.
Example: On Windows you can find the file named "plugin_customization.ini" at "C:\Program Files (x86)\IBM\Notes\framework\rcp". Open that file and change or add "com.ibm.notes.branding/enable.update.ui=true" (without the quotes)
Check more information about this at the Notes 8 online help.
-
After Lotus Notes is restarted, the update manager is enabled.
-
From the Notes menu, select File --- Application --- Install (see figure 1).
Figure 1. Open the Feature Updates window
4. In the Features Update window, select Search for new features to install, and click Next.
5. In the Application Locations window, you can add the URL, folder, or ZIP/JAR location, to install features. To edit or remove features, highlight the location. Click Finish (see figure 2).
Figure 2. Applications Location window
6. In the Search Results window, select the features to install, and click Next to continue (see figure 3).
Figure 3. Search Results window
7. Select Accept item in the Feature License window and click Next. Wait until the status message pops up to prompt you to restart Lotus Notes, and restart it for the update manager installation to take effect.
8. Select Open --- Application --- Application Management, to verify the feature installed successfully and displays in the features list (see figure 4).
Figure 4. Application Management window
To uninstall features via update manager
-
Click the feature in the feature list; the Available Tasks of the feature display in the right-hand column.
-
Click the Uninstall link and verify, then restart Lotus Notes for the uninstall to take effect.
Composite applications
Composite applications (CA) is a solution of the SOA framework with which you can integrate different types of applications (SWT, Portlet, Browser, HostCommand) into one application. You can also use CA to manage a feature.
There are several types of composite applications: Portal CA, Local CA, Notes CA, and Static CA. In this article, we use Portal CA as an example. To use CA, make sure you have Composite Application Editor (CAE) features installed in Lotus Notes. IBM HTTP Server (IHS) and IBM WebSphere® Portal Server are used in the following steps.
Configure a CA to ship a feature on Portal
-
Copy the update site to an IHS doc root, after which you should be able to get the site.xml via http://[IP]/test/site.xml. Note that [IP] is the IP of HTTP server.
-
Log in to Portal server as an admin and select Launch --- templates.
-
In the templates page, click “Application library”, then “New”, and enter the name and description.
-
Select "Portal blank template" as the template; click OK.
-
In the application list, find TestSimpleSWTView, click the name link, click the Page Menu button (see figure 5), and then select "edit page layout".
Figure 5. Page Menu button
6. Click the Add portlets button, find “Rich Client View Placeholder", check the check box next to the portlet, click OK and then click the Rich Client tab (see figure 6).
Figure 6. Rich Client tab
7. In the Portlets section, click the pencil icon next to the Rich Client View Placeholder portlet (see figure 7).
Figure 7. Pencil icon
8. Click the Add button in the Feature requirements section (see figure 8).
Figure 8. Feature requirements section
9. Enter the feature information in the Rich Client Layout Administration window as shown in the example in figure 9, where the Provisioning URL is http://IP/test (the folder to the site.xml of the test application). Click Done.
Figure 9. Rich Client Layout Administration window
10. Input the Eclipse view id in the Rich client properties section (see figure 10); click OK.
Figure 10. Rich client properties section
Open the CA to install the feature
1. Configure Portal server connection information, using File --- Preferences --- Home Portal Account (see figure 11).
Figure 11. Home Portal Account window
2. Open the CA catalog, using Open --- Composite Applications (see figure 12).
Figure 12. Open Composite Applications
3. In the CA catalog, find the CA you created, and double-click to open it. The feature is now installed. Open the feature (see figure 13).
Figure 13. Feature installed
Remove the CA to uninstall the feature
1. In the CA catalog, find the CA you created, right-click it, and select Uninstall; the feature is now uninstalled (see figure 14).
Figure 14. Uninstall feature
Widgets
Notes Widgets is a small application that can be installed and executed in Lotus Notes and, using Widgets, you can also install/uninstall features.
Install features via Widgets
1. Enable Widgets to display in the Notes sidebar, using File --- Preferences --- Widgets (see figure 15).
Figure 15. Show Widget toolbar and the My Widgets panel
2. Open a Web browser in a Notes window; the My Widgets panel shows on the right-hand side. Right-click in the My Widgets title bar, and select Configure a Widget from --- Features and Plugins on an Update Site, to open the Configure Widget window (see figure 16).
Figure 16. Open the Configure Widget window
3. In the Configure a Widget from an Update Site window, input the available URL for the update site and click Load, to see what you can include. You can load features from either a remote server or a local directory, as shown in figures 17 and 18, respectively.
Figure 17. URL format for loading from a remote server
Figure 18. URL format for loading from local directory
4. The features included in the update site display in the list after loading. Check the features you need to install and click Next.
5. Restart Lotus Notes for the installation to take effect. The features installed by widgets display in My Widgets panel.
Uninstall features via Widgets
In My Widgets panel, right-click the feature's icon and select “Remove” (see figure 19).
Figure 19. Remove a feature
Provisioning
Provisioning is the core backend Notes service, and all feature installation/uninstallation operations will eventually invoke provisioning functions. You can also manage features by using the provisioning DCommand function or by invoking the provisioning API command directly; however, that needs some coding work.
Install features via API command
1. You need some coding work to invoke an API command. Here you can install the existing sample application:
2. Put the feature you're going to install on local disk, for example, C:/features/HelloWorld_1.0.0.
3. Open a command window, change the current directory to <Notes_install_dir>, run the following command to install the feature:
notes.exe -RPARAMS -com.ibm.test.wed.client.provisioning.api.dcommand#provisioningApiCommand -feature_id helloFeature -feature_url "
file://C:/features/HelloWorld_1.0.0" -feature_version 1.0.0 -feature_action install
4. Restart the Notes Client, select Open --- Application --- Application Management, and in the Application Management window, verify the features are in the Features list.
Uninstall features via API command
The steps are the same as when installing features via an API command, except for the command in Step 3; the feature_action will be “uninstall”:
notes.exe -RPARAMS -com.ibm.test.wed.client.provisioning.api.dcommand#provisioningApiCommand -feature_id helloFeature -feature_url "
file://C:/features/HelloWorld_1.0.0" -feature_version 1.0.0 -feature_action uninstall
Install features via DCommand
-
Get the feature install build and put it under a working directory, such as C:/features/HelloWorld_1.0.0.
-
Create an install manifest file named mymanifest.xml on the local directory, for example, C:/features/mymanifest.xml.
-
Add manifest contents in mymanifest.xml. such as url=”file://C:/features/HelloWorld_1.0.0”. Listing 1 shows the content of mymanifest.xml.
Listing 1. mymanifest.xml content
<?xml version="1.0" encoding="UTF-8"?>
<ibm-portal-composite>
<domain-object name="com.ibm.rcp.installmanifest">
<object-data>
<install>
<installfeature>
<requirements>
<feature id="helloFeature" url="file://C:/features/HelloWorld_1.0.0" version="1.0.0" match="compatible" size="1086" download-size="602" config="user" action="install" shared="false"/>
</requirements>
</installfeature>
</install>
</object-data>
</domain-object>
</ibm-portal-composite>
4. Open a command prompt, change the current directory to <Notes_install_dir>, and run the following command to install the feature:
notes.exe -RPARAMS -application com.ibm.rcp.provisioning.application.ProvisioningApplication -provisioningOperation provision C:/features/mymanifest.xml -console
5. Restart Lotus Notes, select Open --- Application --- Application Management, and verify that the feature is in the the Features list.
Uninstall features via Dcommand
All the steps are the same as that for installing a feature via the Dcommand, except that the feature action is “uninstall” in the manifest file (see listing 2)
Listing 2. Uninstall action in manifest file
<?xml version="1.0" encoding="UTF-8"?>
<ibm-portal-composite>
<domain-object name="com.ibm.rcp.installmanifest">
<object-data>
<install>
<installfeature>
<requirements>
<feature id="helloFeature" url="file://C:/features/HelloWorld_1.0.0" version="1.0.0" match="compatible" size="1086" download-size="602" config="user" action="uninstall" shared="false"/>
</requirements>
</installfeature>
</install>
</object-data>
</domain-object>
</ibm-portal-composite>
Feature selection panel
Notes provides the ability of installing an addon feature via the Feature selection panel during the product installation process. Currently there are some default addon features installed in this way, such as Sametime and CAE. You can also install a feature via the Feature selection panel, but make sure the feature you're going to install is safe.
Install features via Feature Selection panel
1. Add the features you're going to install to <Notes_install_build>\framework\rcp\deploy\install.xml, for example:
<installfeature description="test" id="helloFeature" name="helloFeature" required="false" show="true" version="1.0.0">
<requirements>
<feature action="install" id="helloFeature" match="compatible" shared="true" size="5" version="1.0.0" />
</requirements>
</installfeature>
You must sign the feature you're going to install. An alternative is to replace all the "PROMPT" instances with "ALLOW" in the <Notes_install_build>\framework\rcp\plugin_customization.ini file.
2. Run <Notes_install_build>\setup.exe to install Lotus Notes. In the Custom Setup window, select the feature want to install and click Next, to continue the installation until it completes (see figure 20).
Figure 20. Custom Setup window
Figure 21. Feature installed
Uninstall features via Feature Selected panel
You can uninstall a feature by re-executing <Notes_install_build>\setup.exe, selecting “Modify” in the Wizard window, and deselecting the feature you just installed in the Custom Setup window.
Addon installer
An addon is usually based on Notes to provide relatively independent functions. For such features (like embedded IBM Sametime), we can install them via the addon installer.
Install features via addon
Prepare the customized addon installer
-
Obtain the Expeditor Addon Windows installer kit from xpd build, and unzip it to a working directory, for example, C:\Test\addon installer source.
-
Obtain the CustomizeAddon.exe from C:\Test\addon installer source to C:\Test.
-
Create a new folder for the customized addon installer, for example, C:\Test\dest.
-
Create a file named AddonConfig.ini under a working directory, like: C:\Test\AddonConfig.ini, and add the properties shown in listing 3.
Listing 3. Properties for addon installer
MSIFileName=EmbeddedAddon.msi
ProductName=XPD_EMBEDDED 6.2.4
ProductNameNoVersion=XPD_EMBEDDED
TargetProductName=XPD Client
ProductVersion=1.0.0
UpgradeCode={135058D1-8E26-444D-AE71-BD4F05FEF4B2}
TARGETUPGRADECODE1={D0ACD8C4-9DC8-41AB-BBCA-B90259CD96B0}
TARGETVERSIONS1=6.2.4
EMBEDDED=true
NOLICENSE=false
LicenseDir=Embede~1|Embedded
LauncherName=setupEmbedded.exe
EnableLangDlg=N
NOTE: To ensure that the above properties are compatible with Lotus Notes, you need to update the contents with the correct Targetupgradecode1 and Targetversions1.
Customize the deploy contents
-
Replace the feature and plugin in the addon installer source\updateSite directory with HelloWorld_1.0.0.
-
Edit the addon installer source\deploy\install.addon.xml file so the contents look like that shown in listing 4.
Listing 4. source\deploy\install.addon.xml contents
<install version="1.0.0">
<installfeature id="xpd.embeddedAddon" mergeaction="add" description="embedded 1.0.0" name="addon" required="false" show="true" version="1.0.0">
<requirements>
<feature action="install" download-size="378" id="helloFeature" match="perfect" shared="true" size="344" url="" version="1.0.0"/>
</requirements>
</installfeature>
</install>
3. Edit the addon installer source\deploy\uninstall.addon.xml file so the contents look like listing 5.
Listing 5. source\deploy\uninstall.addon.xml contents
<install version="1.0.0">
<installfeature id="xpd.embeddedAddon" mergeaction="add" description="embedded 1.0.0" name="addon" required="false" show="true" version="1.0.0">
<requirements>
<feature action="uninstall" download-size="378" id="helloFeature" match="perfect" shared="true" size="344" url="" version="1.0.0"/>
</requirements>
</installfeature>
</install>
4. Run CustomizeAddon.exe under a working directory to create the new addon installer, using the command:
CustomizeAddon.exe <addon source dir> <addon destination dir> [optional]<AddonConfig.ini file location>
5. Verify the customized addon is generated under <addon destination dir> and that the below property in <addon destination dir>\Setup.ini is updated:
Product -- set to the ProductName value from Step1.
ProductVersion -- set to the ProductVersion value from Step 1.
PackageName -- set to the new name of your .msi file, from Step1.
ProductCode -- set to the ProductCode value automatically generated.
PackageCode -- set to the PackageCode value automatically generated.
LauncherName -- set to the LauncherName value and rename the setup.exe file, from Step1.
EnableLangDlg -- set to the EnableLangDlg value from Step1.
6. Update the <XPD_install_dir>\rcp\plugin_customization.ini file, replacing all "PROMPT" instances with "ALLOW".
7. Run <addon destination dir>\Setup.exe to install the addon while Expeditor is closed (see figure 22).
Figure 22. Addon installer Welcome window
8. Launch Expeditor after the addon is installed successfully and select Open --- Application --- Application Management, to verify the feature exists in the Features list.
Uninstall the feature via addon
You can uninstall the feature by running the addon installer again.
Enterprise Management Agent
The Notes Enterprise Management Agent enables you to manage the platform remotely, using a Device Manager Server, with which you can install/uninstall Notes, manage Notes configurations and, of course, install/uninstall features.
After Enterprise Management Agent is enabled, using File --- Preferences (see figure 23), all the operations will be done in Device Manager Server. After packaging features into a bundle and deploying it to the Device Manager Server, you can distribute/remove it to/from a Notes Client.
Figure 23. Enterprise Management Agent window
Conclusion
You should now be familiar with how to manage features in Lotus Notes, using these seven different approaches: Update manager, Composite Applications, provisioning, widgets, Feature selection panel, addon installer, and the Enterprise Management Agent.
Tell us what you think
Please visit this link to take a one-question survey about this article:
Resources
developerWorks Notes Domino product page:
http://www.ibm.com/developerworks/lotus/products/notesdomino/
Notes/Domino Forum:
http://www-10.lotus.com/ldd/nd85forum.nsf?OpenDatabase
developerWorks article, “Extending the IBM Lotus Notes V8 mail with Eclipse:”
http://www.ibm.com/developerworks/lotus/library/notes8-mail/About the authors
Ming Quan Rao is a Staff Software Engineer based at IBM's China Development Lab (CDL), where he has worked since 2006 as QA Lead on the Notes platform and infrastructure team. He is a Certified Project Management Professional and holds a Bachelor's degree in Applied Mathematics from Nankai University, Tianjin, China. You can reach him at
raomingq@cn.ibm.com.
Yuan Zhi Min is a Software Engineer working for IBM since 2010. She is currently a member of the Notes Platform and infrastructure team, before which she worked on the Lotus Expeditor team. She can be contacted at
yzhimin@cn.ibm.com.