ShowTable of Contents
The XPages2Eclipse API and Add-on products are implemented as a set of Eclipse plugins and features and make use of the
XPages Extensibility API
provided by IBM.
This Extensibility API is available as of IBM Lotus Notes 8.5.2, which therefore is the minimum requirement for XPages2Eclipse as client and server platform.
XPages2Eclipse is implemented as pure Java code (no native libraries) running against Eclipse and Lotus Notes APIs. The product was tested on Windows and Linux based Domino servers and Windows, Linux and Mac as Notes Client platforms. It is expected that the server part will also run on other operating systems, but these platforms (e.g. AIX) are currently not officially supported.
Manual Deployment in Notes Client / Domino Designer
A step-by-step installation wizard guides you through the installation and setup process for the product when you open the installation database:
Three installation steps are required to install XPages2Eclipse on a developer or user machine:
1. Create Keystore databaseThe keystore database is a Lotus Notes database that is used to store XPages2Eclipse license keys. The keystore needs to be created once and should then be replicated to a Domino server and shared between multiple clients.
Two type of keys are required to use the XPages2Eclipse product:
Developer and User licenses.
A
Developer license is required for each Notes ID that signs code which calls XPages2Eclipse API methods (e.g. an XPage or a SSJS library design element). And for each user that is using such an application, a
User license is required.
XPages2Eclipse is
secure by default. It
will not run any code on a user machine, unless at least one Developer license key is installed for the code signer (a Developer key also includes a User license, that means a developer can of course test his own code).
To set up the keystore database, extract the database template from the installation wizard page and create a new database instance. Normal users should only have reader access to this database, so you should only give editor rights or higher to privileged users that need to manage license keys.
2. Open keystore and request license key
Now open the keystore database in your Lotus Notes Client and press the button to request an evaluation license key.
This opens a web form with already preselected usernames and license types. When you have successfully requested the key, a download for a .x2ekey file should start. This key file needs to be imported into the keystore database.
3. Install plugins/features through widget deploymentOn the last page of the installation wizard, you need to install the XPages2Eclipse plugins and features into your Lotus Notes Client, followed by an automatic Client restart.
To achieve this, the XPages2Eclipse installation database is based on
the
Eclipse
Update Site design template from IBM, which contains the plugins/features as a set of Notes documents.
The installation is done using
widget deployment, which means that you need to drag and drop the widget, a small xml file called "extension.xml" with XML code pointing to the installataion database, into the My Widgets panel in the sidebar of the Lotus Notes Client.
The update site template has been enhanced so that the widget file is automatically created when the database is opened. This ensures that the widget always points to the right database, even when that database is copied to a corporate Domino server.
If Lotus Notes reports any errors during installation, you should find a detailed error report via the menu action "Help/Support/View Trace" and can hopefully track down the issue (e.g. disk full, installation database cannot be resolved).
It's also possible that custom plugin installation is prohibited via policy by your administrator. In that case, you should ask for installation rights or schedule an automatic deployment on your workstation.
Automatic Deployment in Notes Client / Domino Designer to many machines
This section contains instructions to automatically deploy the XPages2Eclipse product to a number of machines.
Keystore database
The keystore database needs to be accessible from any machine that is either developing or using code with XPages2Eclipse calls. It can either be located on a Domino server or replicated locally, but a local replica is recommended for performance reasons to accelerate the license reading during the first usage of XPages2Eclipse in a user session.
When you open the keystore database for the first time on a machine or by manually selecting the action "Register keystore location on workstation" from the "Administration tools" drop down in the keystore database, the location of the keystore is written to the client's Notes.ini file:
$mndX2EKeyStoreServer=CN=Server1/O=Mindoo
$mndX2EKeyStoreFilepath=dev\xpages2eclipse\keystore.nsf
$mndX2EKeyStoreReplicaId=C12578AF003D5D62When searching for the keystore database, the plugins will at first try to find a local replica with the specified replica id. If it cannot be found, we will then try to open the database via server/filepath on the server, followed by a server/replicaid search.
For an automatic deployment, you should make sure that these Notes.ini variables contain valid data and that the keystore database can be found.
As an alternative to deploying a keystore database, the product also supports adding the license keys to the product as Eclipse extensions (that means as part of the plugin installation without any database involved). Please contact the XPages2Eclipse support in case this deployment scenario is relevant for your environment.
Plugins and features
The recommended way to automatically deploy Eclipse plugins/features to a number of workstations is to
- copy the XPages2Eclipse database to a Domino server
- open the installation database on the server and save the "extension.xml" widget XML file to a local folder
- set up a widget catalog database
- create a new catalog entry, import XPages2Eclipse widget XML file and assign a category value (e.g. "XPages2Eclipse")
- configure the Domino policy
In the policy document, you can specify one or more categories of the widget catalog that should be deployed automatically. By removing categories from the policy, the plugins/features will be deleted from the Notes Client installation on the next startup.
To deploy an update, replace the widget in the widget catalog with a newer version. The Notes Client automatically checks for newer versions every 24 hours and will initiate a software update including Client restart.
Additional setup steps are required for a completely silent deployment (that means no installation prompts to confirm the plugin code signature and installation).
Please refer to the Domino Administrator documentation and the provided wiki articles for details. For our German audience, I have attached very good and detailed session slides of René Winkelmeyers Plug-in session at Entwicklercamp 2011 to this wiki article (see the attachments section).
The following Lotus Notes and Domino Wiki articles will give you a step by step guide in plugin deployment:
Deploying the IBM Lotus Learning Widget using a Widgets Catalog and policy documentsDeployment GuideDeployment on Domino Server
Xpages2Eclipse needs to be deployed to a Domino server, if users should be able to access an XPages database with their web browser and that database is using XPages2Eclipse technology.
The XPages2Eclipse installation database contains code from the OpenNTF project
Plugins Deployment for Domino for this purpose that makes the deployment process on Domino Servers very easy.
The following steps are required to deploy XPages2Eclipse on a Domino server:
- copy the installation database to the server
- sign the database with a Notes ID that has admin privileges on the server (the deployment agents will access the filesystem to add/remove plugin archives from the server's OSGi framework)
- open the installation database and click on the link "Manage Update Site"
- in the "Server Deployments" view, create a new Server Deployment document, enter the server, select the features/plugins to be installed and check/uncheck the options as required
- activate the agents "DeployOnSchedule" and "DeployOnServerStart" in the database design
The installation database can also be used to deploy plugin updates and remove plugins from the Domino server.