Introduction

It's been observed that LEI users often employ different practices to upgrade their existing LEI setups to newer versions and can face issues when important details are not taken care of.

This article describes the activities and things one should consider to achieve a smooth upgrade to new LEI version. It focuses on the upgrade procedure for the most commonly used LEI setup, in which LEI is configured as an add-in task of the IBM Lotus Domino® server.

Most of the information contained herein can be used when upgrading other types of LEI setups, for example, when the LEI server is installed as a stand-alone application or the LEI Admin database and LEI Log database are hosted on another Domino server.

Note that this article does not cover the upgrade procedure from LEI version 3.x.

Scope and goal

Before we go any further, let's first define the scope and goal of the LEI upgrade procedure.

Scope
We have a running setup of a Domino server and LEI server (Domino 7.0.x and LEI 7.0.x) hosted on a machine. During the upgrade procedure we will install a later version of Domino and LEI servers (8.5.x) on top of these existing installations.

Installers of both these products are capable of detecting existing installations and will follow appropriate logic during installation.

During the upgrade procedure we will not make any changes to existing configuration settings (for example, change the Domino server name or the LEI server name), unless the newer version requires a change in the settings.

Goal
After a successful upgrade procedure, we should be able to execute the existing LEI activities and be able to use the existing LEI Connection documents without any errors. Also, we should be able to use any new features added in the upgraded release.

Phases in the upgrade procedure

The upgrade procedure consists of three phases:

• Planning
• Execution
• Verification

Let's look at each of these phases in more detail.

Planning

1. In the planning phase of the upgrade procedure, make sure to do the following:
2. Always read the “Readme.txt” file of the newer LEI version very carefully, especially for information about platforms and RDBMS versions supported by this newer version. Inspect the existing setup to determine if the existing platform and relational database management systems (RDBMS) clients are supported by this newer version of LEI. If not, plan to upgrade these first. This point is also applicable for applications that use Lotus Connectors Lotus Script Extension (LSXLC) in Domino applications of the existing setup.
3. Analyze the LEI activities in the existing setup as follows:

• Categorize the LEI activities being used into high, medium, and less critical, based on their usage and the data handled by the activities.
• Identify how many activities run as schedule activities.
• Determine how many real-time activities there are.
• Identify how many real-time activities run in “Auto Start” mode (activities that start as soon as the LEI server starts).
• Determine whether there are any test activities that would allow us to smoke-test the setup and critical operations during the verification phase. If not, plan to design such activities.

4. Identify a setup downtime window, and inform all the stakeholders in advance.
5. Also, plan a procedure to revert back to the existing setup, in case something goes really wrong during the upgrade procedure and the upgrade cannot be completed during the planned setup downtime window.

Execution

What the LEI installer does during upgrade
Before we look at the steps involved in the Execution phase, let's discuss the sequence of events that occur during the LEI upgrade installation, which will help us to troubleshoot and relate our observations with upgrade install logic. Specifically, the installer:

1. Inspects the notes.ini file for the entries “EIName” and “EIAdminServer,” and detects the existence of the LEI Admin database at the values specified by these entries.
2. If the LEI Admin database exists, then the installer creates a backup copy of this database with the name provided by the user during installation; the default is "decsadm_bkup.nsf".
3. Copies binaries and template files, overwriting the corresponding older binaries and template files.
4. Creates a new blank LEI admin database using the LEI Admin template (leiadm.ntf).
5. Creates new Configuration documents (Administrator and Server) in the new LEI Admin database (decsadm.nsf).
6. Copies all the Connection and Activity documents from the backup copy of the LEI Admin database (created in Step 2) to the newly created LEI Admin database.

Pre-execution steps:
Before beginning the upgrade execution, perform these steps:

1. Take backups of the existing LEI Admin, LEI Log, and Script Vault databases (if being used in our setup) and store them in a safe place (usually outside the Domino program and data directories). These will be useful in revert-back plan mentioned in Planning section above.
2. Disable the Scheduling option of activities that are scheduled to run during the setup downtime window. To do this, open the given Activity document, select the option SCHEDULE DISABLED from the Scheduling tab, and save the Activity document (see figure 1).

Figure 1. Disable Scheduling option



3. Turn off the Auto Start option of all real-time activities, changing it to the Manual option (see figure 2).

Figure 2. Change to Manual option



Executing the upgrade
To perform the upgrade, use these steps:

1. Shut down the Domino server.
2. Upgrade the Domino server to the newer version.
3. Once the Domino server upgrade is complete and the server is re-started, shut down the LEI server by issuing command “tell lei quit” on the Domino console; wait for the “LEI: Shutdown complete” message on the Domino console. At this point, the Domino server is upgraded, but LEI is not, and it auto starts as a Domino process. This is a mixed environment that is not supported; thus LEI still needs to be upgraded.
4. Make sure that no user / application or process is accessing either the LEI Admin or the LEI Log database. Issue the command “dbcache flush” on the Domino console to remove any reference to the LEI databases from the cache.
5. Now execute the LEI installer, to upgrade to the new version of LEI (compatible with the upgraded Domino version).
6. Once the LEI installation is successful, restart the Domino server by issuing command “restart server” on the Domino console.
7. Once the Domino server is restarted, wait for message “LEI: Initialization successful”, indicating that the new version of the LEI server has been loaded successfully on the new version of the Domino server.
8. Open the LEI Admin database from a Notes client and execute the “RefreshAllDocuments” agent by selecting Action > RefreshAllDocuments from the menu. This agent makes sure that all the Connections and Activities that were copied into this new LEI Admin database during the install are properly formed.
9. Examine the log generated and make sure no errors were reported. Note that this log is created on the Notes client machine, not on the machine hosting the Domino and LEI servers.

By successfully completing the above steps, we've completed the major portion of the LEI upgrade procedure. Now only the Verification phase remains; however, before proceeding to that phase, note the following:

1. Do not ignore any errors that occurred during LEI installation. Try to correct those before moving ahead.
2. If the LEI installation needs to be re-run:

• Remove the LEI Admin database (decsadm.nsf) and/or backup copy of this database (created by the LEI installer) from the Domino data directory, if these were created during the unsuccessful installation.
• Replace the LEI Admin database with a good backup copy (which would have been done in Step 1 in the Pre-execution steps section).
• After the replacement, perform Steps 2 and 3 of the Pre-execution steps section before moving ahead to re-run the LEI installation.

Verification

In this phase we carry out verification checks to ensure that the LEI upgrade installation is successful before re-opening our setup for production use.

1. Shut down the Domino server, open the notes.ini file, and remove the LEI task from the “ServerTasks” entry (see figure 3 below). With this change the LEI server will not start when Domino starts.
2. Start the Domino server and open the LEI Admin database, the Administrator configuration document, and the Server configuration document. (To access these, click “Configuration” in left-hand pane of the LEI Admin database.)
3. Make sure all the fields in these documents have values that look correct.
4. Open the Activity documents of highly critical activities, as well as the Connection documents used by these activities. Make sure that all the fields in these documents have values that look correct.
5. Open the Activity and Connection documents of a couple of real-time activities and verify the fields and their values appear correct.
6. Open a few Activity and Connection documents at random and verify that the fields and their values are correct.
7. Shut down the Domino server again, open the notes.ini, and re-add the LEI task to the ServerTasks entry.
8. Start the Domino server and look for the “LEI: Initialization successful” message.
9. Now try executing the test activities (mentioned in the Planning section above), to verify they run as expected.
10. Enable the Schedule option in activities for which we had disabled it at the start of execution phase.
11. Re-enable the Auto Start option in the real-time activities that we had disabled at the start of the Execution phase; restart the Domino server.

Figure 3. ServerTasks entry


If all the above verification checks are good, then our upgrade procedure is considered successful, and we are ready to re-open the LEI setup for production use. It's recommended to closely monitor the setup for a fewl days, to ensure there's no unexpected behavior.

This article does not cover the LEI upgrade procedure for the LEI cluster setup, but the steps would be the same as discussed above. The primary server should be upgraded first, and then the additional server/servers in the LEI cluster should follow.

NOTE: Only open all the setups for production use after all the LEI servers in the LEI cluster have been upgraded successfully.

SAP Connector and LEI setup

Here are some points to remember if the LEI setup also contains the IBM Lotus Connector for SAP Solutions (SAP Connector):

When the SAP connector is used in the LEI setup, it has two parts:

• SAP Connector binaries. These are available in the Domino program directory

• SAP Connection FORM. This is copied into the LEI Admin database during the SAP connector install and becomes available in the “Add Connection” menu of the LEI Admin database.

During the LEI upgrade procedure this FORM is not copied back to the upgraded LEI Admin database. Thus after the upgrade, if we try to open any SAP Connection document, we will get an error or may observe the error in the log after the RefreshAllDocument agent is run.

To resolve this issue, use one of these two options:

• Once the LEI upgrade is complete, install the SAP connector again.

• After the LEI upgrade is complete, copy the SAP Connection FORM (Connection\SAP | Connection to SAP) from the LEI Admin database backup copy to the new LEI Admin database. Then create a SAP Connection, using menu options Create > Connection > SAP. After you perform this step, the SAP connection will be available in the Add Connection option in the LEI Admin database.

Conclusion

You should now be familiar with the proper scope and realistic goals of the LEI upgrade procedure, as well as the different phases involved in the procedure. We have discussed each phase in detail and have seen the various activities and steps to perform in each phase. We also briefly mentioned some points to should consider if we have the SAP Connector in our setup.

By designing the upgrade procedure per the instructions in this article, we can expect a smooth upgrade of the LEI setup to the newest version.

Resources

For information about the LEI product, including demos, customer stories and white papers, visit the Lotus Enterprise Integrator for Domino home page

For more detailed information about how the Lotus Enterprise Integrator works, consult the developerWorks® Lotus Enterprise Integration product page.

The Enterprise Integration Forum has many answers for issues reported by the LEI user community, serving as a great source of information.

About the author

Prasanna Joshi joined IBM in 2000 and since 2007 has served as the Technical Lead for LEI, the SAP Connector, and other components, including Domino Enterprise Connection Services (DECS) and LCLSX from the Domino Enterprise Connection framework. Before his current assignment, he led the Domino Crash and Hang Analysis L2 team at IBM's India Support Center, led the QE team for Lotus Workflow, and was part of Lotus SmartSuite development team.