The LEI Migration Utility is a stand-alone Java program provided with Lotus Enterprise Integrator (LEI) version 6.0 and above. It supports migration from LEI 3.x to LEI 6.x or 7.x. This utility allows you to transfer existing LEI and Domino Enterprise Connection Services (DECS) activity and connection documents from LEI 3.x to a new LEI 6.x/7.x Administrator. This tool can also update and transfer scripts (also called agents) stored in an LEI Script Vault to an LEI 6.x/7.x Script Vault. You can migrate documents during LEI 6.x or 7.x installation by choosing the migration option presented by the LEI installer. Alternatively, you can migrate at any other time after the LEI 6.x/7.x installation using the supplied run_migration executable typically located in the Lotus\Domino directory.
The Migration Utility handles design changes made between the earlier LEI 3.x versions and the newer LEI 6.x/7.x in items such as templates and scripting syntax. It is designed to upgrade items used in LEI 3.x to LEI 6.x/7.x standards, allowing their immediate use in an upgraded system. Multiple LEI 3.x Administrators can be consolidated into a single LEI 6.x/7.x Administrator to move activities and connections into one Administrator.
This article describes how to use the LEI Migration Utility to migrate from LEI 3.x to LEI 6.x and 7.x. We explain how to prepare for migration and conclude by examining how to troubleshoot the most common issues you may encounter when using the Migration Utility. This article assumes that you're an experienced LEI administrator.
The Migration Utility is contained in the migration.jar file installed in the Domino program directory. At runtime, the utility creates a file named migration.log to collect detailed information on the items examined and migrated. This file is also stored in the Domino program directory. This file logs the activities and connections transferred, those rejected as referencing retired Lotus Connectors, duplicates and/or copies made, and other information pertinent to the migration. The following is an example of migration log content:
Migration Log: 04/10/2004 10:43:57 AM: Connection MyNotesConnection has been transferred
Migration Log: 04/10/2004 10:43:58 AM: Activity MyDirectTransferActivity has been transferred
Migration Log: 04/15/2004 12:23:04 PM: The Script Vault has been backed up to leivlt_2.nsf
Migration Log: 04/18/2004 10:44:02 AM: Script MyScript is a duplicate and was not migrated
While the Script Vaults can be migrated, script libraries that exist in an LEI 3.x Script Vault cannot. You can manually copy script libraries to the LEI 6.x/7.x Script Vault, but you must make a minor code change before these scripts can run on the 6.x/7.x version. The Uselsx *lsxlei statement contained in every function must be changed to Uselsx *lsxlc. For a more detailed description, see the IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide provided with the LEI documentation.
Before running the LEI Migration Utility, you should:
- Clean up the LEI 3.x Administrator and Script Vault.
- Check the system path and Domino Directory.
- Check database naming requirements.
- Confirm LEI installation requirements.
- Back up the LEI 3.x Administrator and Script Vault.
- Configure the Domino server.
- Confirm connectivity settings.
The following sections explain how to perform these tasks.
1. Cleaning up the LEI 3.x Administrator and Script Vault
Prior to migrating from LEI 3.x to LEI 6.x/7.x, you should perform several housekeeping tasks to avoid transferring unusable documents. Clean up the databases to be migrated by deleting or archiving any connection/activity documents using retired Lotus Connectors. Also, delete or archive any documents you do not want transferred to the upgraded system. The ID used during migration must have access to the LEI Administrators (3.x and 6.x/7.x) and their contents and any Domino server(s) must have execution access to any other servers involved in the migration.
2. Checking the system path and Domino Directory
Check the system path for the Domino executable directory. For example, if the configuration being migrated is an LEI server and Domino server on the same machine, the system path must include C:\lotus\domino. If the configuration is an LEI server installed via the Notes client using a remote Domino server, the path must include C:\lotus\notes. (If the path isn't listed, ask you administrator to add it.)
Also confirm that the Domino server(s) are running. LEI does not need to be running and all activities should be stopped prior to running the Migration Utility.
3. Checking database naming requirements
Next, examine the LEI Administrators and Script Vaults involved in the migration. Confirm that any LEI 3.x Script Vault is named leivlt.nsf. The LEI Administrator file name and database title can have any valid values, but the Script Vault file name must be leivlt.nsf. You can make a backup copy of this vault and simply rename the file to leivlt.nsf. The vault database title can be anything (typically LEI Administrator).
The LEI 6.x/7.x Script Vault and Administrator must retain their installed names of leivlt6.nsf and decsadm.nsf respectively for migration to proceed.
4. Confirming LEI installation requirements
If you install LEI on a Notes client, set the Notes ID to share its password with other Notes-based systems as documented in the LEI Installation Guide. Confirm that the LEI environment is configured as required in the Installation Guide. Migration errors are often the result of an improperly configured system.
5. Backing up the LEI 3.x Administrator and Script Vault
Create backup copies of your LEI 3.x Administrator and Script Vault. The Migration Utility will ask whether or not you want it to create a backup copy of the LEI 3.x Administrator. The Migration Utility automatically creates a backup copy of the 6.x/7.x Script Vault whenever a Script Vault is migrated. Thus, you can choose to create a backup of your LEI 6.x/7.x Administrator before it is migrated, but the LEI 6.x/7.x Script Vault is created by default when you choose script migration.
The backup copy of the LEI 6.x/7.x Administrator is named decsadm_1.nsf with the _1 incrementing as needed for multiple backups created. The 3.x Script Vault is named leivlt_1.nsf, and the number similarly increments for each database copy created. The backup copy of the 3.x Script Vault name does not contain the 6 required for a 6.x/7.x Script Vault (for example, leivlt6.nsf). Both the 6.x/7.x Administrator and Script Vault can be renamed to decsadm.nsf and leivlt6.nsf respectively to be suitable for use as the primary administrative Notes databases used by LEI/DECS 6.x/7.x.
6. Configuring the Domino server
Perform all needed pre-installation setup as described in the LEI Installation Guide. For example, on Unix platforms correct access controls must be set for the Domino server. The Domino Server document in the active Domino Directory must be correctly configured. All required environment variables must be set and exported, and an X Windows system must be loaded and configured if you are installing on Unix.
Verify that a Domino 6.x/7.x server exists on the local machine that you are migrating to and that its version is compatible with the LEI version to which you are upgrading. This is the destination server for your LEI 3.x Administrator (any_name.nsf) and/or LEI 3.x Script Vault (leivlt.nsf).
Ensure that you have a connection to the Domino 6.x/7.x server by running the LEI connectivity testing tool ndctest (Windows 32) or dctest (Unix). This tool is located in the Domino program directory, which is typically stored as follows:
- Win32: domino\ndctest.exe
- Unix: /opt/lotus/notes/latest//dctest
If this test fails, then migration will also fail. You must troubleshoot your connectivity and correct the configuration before attempting to migrate your databases.
7. Confirming connectivity settings
Before migrating, you need to ensure that accurate connectivity designations exist for the Domino server (including network port settings), that all database access control lists (ACLs) have been set, and that the execution control list (ECL) for the Domino server is configured correctly.
Server name resolution
The Migration Utility expects a server name to be entered for the 6.x/7.x server. For this to resolve correctly, several settings can be edited. First ping the server using the server name alone, then use the server’s IP address, and finally the Internet host name (server_name.company_domain.com). Depending on which piece of the resolution puzzle is missing, you may need to update your machine and/or the server configuration. Look in the Domino server(s) console for an error indicating a name resolution error. An example console error is:
04/13/2004 02:13:56 PM Opened session for (Release 6.5.1 [Build 194])
04/13/2004 02:13:56 PM ATTEMPT TO ACCESS DATABASE leiadm.nsf by was denied
04/13/2004 12:15:59 PM Router: Unable to obtain Internet host and domain names
These Domino Server document settings are found on the Basics tab. Edit these as needed:
- Server name
- Domain name
- Fully qualified Internet host name
Figure 1. Server document Basics tab
Database Access Control List (ACL)
The Migration Utility needs to view its contents and have Editor access. Review the ACL for both the LEI 3.x Administrator and the Script Vault by right-clicking the database of interest and choosing the Access Control option. Display the entire list by selecting the Show All view and ensure that the Domino 6.x/7.x server has Manager access to the LEI 3.x databases and that your local configuration access rights are addressed. For example, LEI Products must have access as noted in the Enterprise Connector Products/Lotus Notes Companion Products entry shown in Figure 2. A setting of Default also works:
Figure 2. Access Control List
In addition, check under the Attributes section to ensure that the Replicate or copy documents option is enabled.
Server Execution Control List (ECL)
Check that both the source and destination Domino servers have appropriate access to operate on the source and target databases by reviewing the entries under each Server document’s Server tab. The server itself and the user Enterprise Connector Products/Lotus Notes Companion Products option must be listed in the "Run unrestricted methods and operations" and the “Run restricted LotusScript/Java agents" fields:
Figure 3. Server ECL settings
Network port
The network port must be defined properly to enable the Migration Utility to access the remote server. In the Server document, click the Ports tab and enter the machine name in the Notes Network Ports form. Depending on other machine settings, this may be accomplished by adding the machine name only, the IP address of the machine, or the fully qualified Internet host name such as machine_name.Domain.com.
Detailed instructions on running the Migration Utility on various platforms are provided in the LEI Installation Guide. Your specific migration procedure depends on what you are migrating (LEI or DECS) and where your current-release LEI server, Domino server, and LEI Administrator reside on your network. The current-release LEI Administrator is assumed to be on the machine that is running the Migration Utility.
If you have just installed LEI and are being prompted by the installation program to proceed with migration, or you are running the run_migration executable, the following screen appears:
Figure 4. Migration Utility welcome screen
Enter the following information specific to your system configuration:
- Source Server
Specify the Domino server where the LEI 3.x Administrator or DECS Administrator resides. - Source Administrator
Enter the LEI 3.x Administrator or DECS Administrator you want to migrate from. (The path and file name is specified relative to the Domino data directory.) - Domino Server to run RealTime Activities
Define the Domino server where the installed LEI Administrator used for Advanced RealTime activities resides. - Backup LEI 6.x/7.x Administrator
This option creates a copy of the current release LEI Administrator prior to migrating the contents of the LEI 3.x or DECS Administrators into it. - Migrate ACL
This option migrates ACLs from the source Administrator to the LEI 6.x/7.x Administrator. - Disable all scheduled activities
If checked, this disables all activities with enabled scheduling settings. If unchecked, all activities are migrated with their existing Scheduling section setting (either enabled or disabled) intact as defined in the source activity.
Resolving connection and activity documents conflicts
If the Migration Utility encounters connection name or activity name duplicates, a Conflicts Detected screen appears:
Figure 5. Conflicts Detected screen (showing connection conflicts)
The Conflicts Detected screen lets you specify how to handle connection name conflicts:
- Rename
Appends a conflict suffix value (see the last bullet in this list) to all connections or activities migrating into the current release LEI Administrator that have a same-name match in that LEI Administrator. - Overwrite
Overwrites connections/activities in the current release LEI Administrator with their same-name counterparts from the source LEI 3.x or DECS Administrators. - Skip
Does not migrate connections/activities from the source LEI 3.x or DECS Administrators if they have a same-name counterpart in the current release LEI Administrator. - Choose Conflict Suffix
Appends a global suffix to every incoming connection/activity whose name matches a connection that already exists in the current release LEI Administrator.
After completing the Conflicts Detected screen, click Continue Migration to continue.
You are given the option to migrate the LEI LSX format scripts from the LEI 3.x Script Vault.You can either migrate all LEI LSX scripts or individually choose which scripts to migrate.
The contents of your LEI 3.x or specified DECS Administrator are migrated to the LEI 6.x/7.x Administrator. Optionally, the contents of your LEI 3.x Script Vault are migrated to the current release LEI Script Vault. Migrated activities and connections are migrated and their functionality updated. For example, an LEI 3.x Replication Activity Document now displays the master connection on the left of the form. When the migration process is complete, a result screen appears:
Figure 6. Migration Utility completion screen
Click Finish to exit the utility. Then run the supplied RefreshAllDocuments agent in the current-release LEI Administrator. You can find this agent on the Actions menu in the LEI Administrator top bar. If the RefreshAllDocuments agent encounters errors, it creates a RefreshErrors.txt file in the Notes program directory on the Notes client machine from which you ran the agent.
Optionally, you can open and view the migration.log file located in the Lotus\Domino directory. The migration log contains a list of all migrated activities and connections, a list of activities or connections that did not migrate because of duplicate naming, and a list of activities that did not migrate because they use Lotus Connectors that are no longer valid, such as the EDA/SQL Connector. It also contains the names of LEI LSX scripts that were migrated from the LEI 3.x Script Vault (leivlt.nsf).
Troubleshooting common migration errors
If an error occurs during migration, there are several sources of information that can help diagnose the issue. In addition, you can launch the run_migration executable from a command line prompt using an option that creates a text file containing more detailed troubleshooting information. You can specify the location in which to create the debug file. Example syntax for the command line is:
run_migration -is:log c:\temp\mig.txt
Other locations containing useful information include the migration.log created during a migration, the console.log stored in the directory IBM_TECHNICAL_SUPPORT found in the Domino Data directory, and the log.nsf also located in the Domino Data directory. The Domino server console window often contains useful information, such as issues relating to access and execution rights preventing the migration from continuing.
Specific migration error conditions include the following:
java.lang.UnsatisfiedLinkError: no nlsxbe (nlsxbe.dll) in java.library.path
If this error message appears, the Domino server is not in the system path. This prevents access to certain libraries that the Migration Utility needs to operate.
The Migration Utility displays error messages when it encounters an issue that blocks the migration. For example, the following error can appear if you enter an incorrect or misspelled server or administrator name, the server(s) are not running, or you have neglected to enter a name in the input box:
Figure 7. File does not exist error
Another error message you may encounter is the following:
Figure 8. Cannot access Administrator error
This error can be caused by multiple situations relating to access to either the LEI 3.x (leiadm.nsf) or 6.x/7.x Administrator (decsadm.nsf). If you see this error, open both databases in the Notes client to check that they are not corrupt and that the Domino server(s) are up and running correctly. Another issue that produces this error is inadequate access privileges to the Administrators. Review the Access Control List (ACL) settings in both databases to confirm that proper access is configured. The Domino server must have rights to access and copy the contents of both Administrators involved in the migration.
The Migration Utility expects that the machine in use is configured for access to the Domino server and that the path to the server is resolvable. Check the server's path resolution -- is it by IP address, domain address, and/or server name? Confirming the settings in the Domino Server document can often solve a resolution problem that prevents the Migration Utility from finding the server.
Another source of error information is the Domino server console window. For example, when the source Domino server is on one machine and the destination Domino server is on another, the source console displays a message relating to the Migration Utility access. If the two servers have successfully established communication, the console displays a message similar to the "Opened session for …" message. If this connection is successful (as evidenced by an opened session) and the utility still cannot find the LEI Administrator, look for missing access rights in the Administrator ACL.
Access is also governed by the security settings in a Domino Server document. Inadequate rights in the Execution Control List (ECL) can prevent the Migration Utility from running on the Domino server. If the following error is displayed in the server console window, it is likely the ECL for the server needs to be edited:
ECL Alert Result: Code signed by Enterprise Connector Products/Lotus Notes Companion Products was prevented from executing with the right: Access to current database.
Check the security configurations recommended in the LEI Installation Guide for the necessary access rights that LEI needs to operate correctly. The Migration Utility needs these same rights. Review the ECL for the server by opening the Server document. Select the Toolbar Action and choose Edit Administration ECL. The following screen is displayed:
Figure 9. Workstation Security Execution Control List screen
One requirement is that the ECL must contain Enterprise Connector Products/Lotus Notes Companion Products as illustrated in Figure 9.
With the help of this article, you should now be ready to run the LEI Migration Utility to migrate your LEI 3.x scripts, activity documents, and connection documents to LEI 6.x and 7.x. We have shown you how to prepare your LEI environment for migration and how to troubleshoot the most common error conditions you may encounter.
-
The Lotus Enterprise Integrator (LEI) product page provides general information about LEI.
-
The LEI documentation is a good source for detailed LEI technical information.
-
Participate in developerWorks
blogs and get involved in the developerWorks community.
Comments (Undergoing maintenance)
Table of contents
Local resources
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
