ShowTable of Contents
IBM® Connections® 3.0.1 contains essential new features and updates to version 3.0, including Moderation, Ideation Blog, and Custom Library. It also supports an update path from Lotus Connections 2.5, so you don't need not to update twice from Lotus Connections 2.5 to 3.0 and then to IBM Connections 3.0.1.
Migration is well known as a complex process in which it's easy to encounter problems. The official product documentation includes detailed steps and notes but does not focus on the issues. This article provides information about general troubleshooting steps and common migration issues for the 2.5 to 3.0.1 migration path, focusing on common considerations and basic production environment.
Typically, Connections migration aims to upgrade/migrate the following data and artifacts:
- Database schema and application data
- Application's content store
- Application's major configuration XML files
IBM Connections ships with tools to help you migrate, such as the migration tool, database transfer scripts, and database upgrade scripts. This article introduces troubleshooting the migration tool; the other two database parts will be addressed in a future article.
Before identifying any specific problems, however, it is useful to understand the big picture of 2.5 to 3.0.1 migration.
Understanding 2.5 to 3.0.1 migration
Connections 3.0.1 supports two update paths, 2.5 to 3.0.1 and 3.0 to 3.0.1, with the following differences between them:
2.5 to 3.0.1:
The 2.5 to 3.0.1 path is implemented similar to that of previous migrations, such as 2.5 to 3.0, which does a reinstall of IBM Connections 3.0.1 rather than in-place update.
3.0 to 3.0.1:
The 3.0 to 3.0.1 path is designed not strictly as a migration but rather as an update via a fixpack. This fixpack is different from the 2.5 fixpack combining ifixes. Since Connections 3.0 changed deployment by using IBM Rational® Install Manager (RIM), the fixpack is shipped with 3.0.1 and is launched by RIM.
In the 3.0 to 3.0.1 update, you don't need to use the migration tool. However, for the 2.5 to 3.0.1 update, the migration tool is the major tool that helps migrate IBM WebSphere® Application Server (WAS)-side artifacts. Here are the relevant migration concepts:
- Content store. Shared directories that store user configuration and file data. The content store location is input on the product installation panel, and the location can also be modified in the product operation process.
- Application configuration XML files: These are specific to the XML configuration files under the cell-level configuration directory of WebSphere Application Server for IBM Connections; for example, on Microsoft® Windows® 2003 it would be:
Not all the XML configuration files will be updated; that depends on the XSLT files provided by applications when there are elements that are needed to migrate.
When encountering a migration issue, you must check for its location. This section introduces how to check for such places and general information about them. In the next section, the relevant information is used to help analyze the issues. The below information has been divided into three parts, not in any particular order:
Migration procedure check
Before performing a 2.5 to 3.0.1 migration, you should read the Connections 3.0.1 product document topic, “Migrating to IBM Connections 3.0.1 from version 2.5 : ic301
,” which includes prerequisites, detailed steps, and notes on the migration process.
For example, the migration commands have been changed from previous versions. Two parameters, "-DDMUserid" and "-DDMPassword" have been added to the import command of the migration tool, and the SOAP connection to Deployment Manager might fail if they are missing.
Besides the commands, make sure to perform the proper steps when troubleshooting a migration issue. Typically, the migration procedure is as follows:
- Back up your current 2.5 deployment.
- Update your databases to version 3.0.1.
- Export your Lotus Connections 2.5 data.
- Install IBM Connections 3.0.1.
- Import your Lotus Connections 2.5 configuration settings and content stores to version 3.0.1.
- Perform any applicable post-migration tasks.
If the steps of your procedure are different, there may be some unexpected issues. For instance, if you import the content store and configuration files (Step 5) before updating the databases (Step 2), you may encounter data inconsistency issues. The reason will be illustrated later in the "Troubleshooting issues and their solutions" section.
Migration tool logs check
When you execute export/import commands, the migration tool generates real-time logs on a command line. Besides this command-line log, there is a log file, such as "migration.latest.log," under the directory of <LC_HOME>/migration/work.
Actually, the command-line logs include more information, including initial parameters of the internal config engine task in the beginning, update registry sync tasks, and some cleanup tasks, so it's recommended to redirect the log information into local files.
Using the log, you can find error information, blocked processes, and even if you just discover some unexpected values rather than obvious errors, it may help you determine the root cause.
The migration tool logs include specific parts of log information. To see the structure of these parts, let's use the import log as an example:
- Initial information of config engines (only command-line log)
- Initial migration tool
- Load current product version
- Back up current configurations and data into a backup directory
- Load exported product version
- Migrate content store and transform XML configuration files, one by one
- Post-config and cleanup work directory (only command-line log)
Each part contains detailed, easy-to-understand log information and, using the above outline, you can locate specific data easier. The structure of export log is similar and even simpler.
The migration tool also generates temporary directories in the process, which are also good resources for troubleshooting. The work directories of the export/import migration tool functions are described as follows:
- Export. The export directory is generated under the same directory as log files, which include 2.5 configuration files, content data, and properties.
- Import. Three directories are generated for this: backup, export, and import directories. The backup directory contains a backup of the 3.0.1 fresh-install content store and configuration files, and the export directory contains the exported 2.5 content store and configuration files.
The import directory contains 2.5 configuration files (under the "level0" subdirectory), 3.0.1 fresh-install configuration files, XSL files that can transform XML configuration files from one version to another (under the "level1" subdirectory), and the middle-transformed XML configuration files and final 3.0.1 XML configuration files (under the "level2" subdirectory).
These work directories and files within the log files are essential references that can help you diagnose issues.
Migration results also depend on other factors, such as:
- 2.5 source Connections server
- Freshly installed Connections 3.0.1 (before migration) and its database
- File system limits or network connections between shared folder and cluster nodes
For the Connections 2.5 server, enure that applications work well and that databases as well as content stores are integrated. For a 3.0.1 fresh-install environment, make sure applications are installed successfully and can be started properly.
Also, be sure to back up essential files such as the configuration folder, cells/<cell_name>/LotusConnections-config/ under the Deployment Manager profile, so you could return to the environment in case of migration failure.
Troubleshooting issues and their solutions
In this section, we focus on specific issues in the migration process that we categorize into the following parts:
- Obvious errors when using the migration tool
- Application does not work well
- Content store fails to migrate
- Data error/loss
- Customization of content store and UI
Common questions among these parts include (1) what is the issue and to what part does the issue belong, (2) how to resolve the issue, and (3) is there a way to avoid the issue. The issues and solutions discussed below can help you build a troubleshooting strategy for the 2.5 to 3.0.1 migration.
Errors in exporting/importing using the migration tool
The migration tool is the major component of the migration process. When you use it, there will be obvious errors that the migration tool reports directly to you:
The migration tool version.
The tool can be used to export 2.5 artifacts and import the 3.0 artifacts. For the 2.5 to 3.0.1 migration process, you should use the 3.0.1 migration tool to export from the 2.5 source environment, rather than using the 2.5 migration tool. Since the export lists are not the same between the versions, it could cause some properties files not to be exported.
You can obtain the 3.0.1 migration tool from the installed 3.0.1 product, or you can extract it from the 3.0.1 migration .zip file under Lotus_Connections_Install\LotusConnections\native of the 3.0.1 product installation package.
In the import, the 3.0.1 migration tool is already located under <LC_Home>/migration; for example, on Windows 2003, the default path is:
You just need to copy the "work" directory from the migration tool in the 2.5 environment, after export, to the same location in the 3.0.1 migration tool, and then you can perform the import.
Product version issues.
The migration tool detects current product versions as well as exported product versions when importing. If you export from a source environment that is not 2.5.0.x, such as 2.0.1 (including sub versions of 2.5), the migration tool will return a version error.
For instance, table 1 shows the "Current version is not supported" error on the command line. If the release is earlier than 2.5, the migration tool cannot perform an export and eventually displays "BUILD FAILED". The situation is similar with respect to the target version.
Table 1. “Current version not supported” error
Mon Mar 28 06:11:22 CST 2011
[echo] Initializing Lotus Connections migration tool
[echo] Starting log in C:\Documents and Settings\Administrator/lc-migration-20110328_0611_22.log
[echo] Starting log in C:\Documents and Settings\Administrator/lc-migration-20110328_0611_22.log
[copy] Copying 1 file to C:\Program Files\IBM\Lotus Connections\ConfigEngine\lib
[LoadProperties] Loading properties from: C:\Program Files\IBM\LotusConnections\ConfigEngine\profiles\AppSrv01\wkplc_comp.properties
[echo] Initializing Lotus Connections migration tool … Done.
[LoadVersion] Load product versions from C:\Program Files\IBM\Lotus Connections\ConfigEngine\..\version
[loadVersion] Prefix =
[LoadVersion] Product set = All
[LoadVersion] Current version is not supported.
[LoadVersion] at com.ibm.lconn.ant.task.LoadProductVersion$Product.fixLCVersion(Unknown Source)
[LoadVersion] at com.ibm.lconn.ant.task.LoadProductVersion$Product.(init)(Unknown Source)
[LoadVersion] at com.ibm.lconn.ant.task.LoadProductVersion.execute(Unknown Source)
[LoadVersion] at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:275)
[LoadVersion] at org.apache.tools.ant.Task.perform(Task.java:364)
[LoadVersion] at org.apache.tools.ant.Task.perform(Task.java:364)
Be sure to check your current product version before performing a migration. The version information can be found in the files under <LC_HOME>/version; for example, on Windows 2003, the directory is C:\Program Files\IBM\LotusConnections\version.
Problems with critical ConfigEngine properties.
The migration tool uses ConfigEngine, which is an internal toolkit. The ConfigEngine properties contain critical information for the migration tool, including core system parameters such as the WAS home directory and the Deployment Manager Simple Object Access Protocol (SOAP) port number.
For instance, if the "wkplc.properties" and "wkplc_comp" files are lacking, or if the migration tool cannot detect them, it returns error messages like 'java.lang.Exception: wkplc.properties could not be read' as shown at the bottom of table 2. These two property files are critical for export/import.
Table 2. "Native2ascii execution failed" error
Running Configuration Engine task 'lc-export'
1 file(s) copied.
The system cannot find the file specified.
1 file(s) copied.
C:\PROGRA~1/IBM/WEBSPH~1/APPSER~1/java/bin/native2ascii WPSConfig_temp.prop_ WPSConfig_temp.prop_
Loading system properties from WPSConfig_temp.prop_
WpsConfigLauncher setting system property JAVA_HOME=C:/PROGRA~1/IBM/WEBSPH~1/APPSER~1/java
WpsConfigLauncher setting system property local.cell=win2003r2-32itNode01Cell
WpsConfigLauncher setting system property was.root=C;/Program Files/IBM/WebSphere/AppServer
WpsConfigLauncher setting system property NodeName=win2003r2-32itNode01Cell
WpsConfigLauncher setting system property local.node=win2003r2-32itNode01Cell
WpsConfigLauncher setting system property was.ext.dirs=C:/Program Files/IBM/WebSphere/AppServer/java/lib;C:/Program Files/IBM/WebSphere/AppServer/classes;C:\Program Files/IBM/WebSphere/AppServer/lib;C:\Program Files/IBM/WebSphere/AppServer/installedChannels;C:/Program Files/IBM/WebSphere/AppServer/lib/ext;C:/Program Files/IBM/WebSphere/AppServer/web/help;C:/PROGRA~1/IBM/WEBSPH~1/APPSER~1/deploytool/itp/plugins/com.ibm.etools.ejbdeploy/runtime;./lib;./shared/app
WpsConfigLauncher setting system property cfg.trace=C:/PROGRA~1/IBM/LOTUSC~1/log/ConfigTrace.log
WpsConfigLauncher setting system property CellName=win2003r2-32bitNode01Cell
WpsConfigLauncher setting system property was.repository.root=C:/Program Files/IBM/WebSphere/AppServer/profiles/AppSrv01/config
WpsConfigLauncher setting system property server.root=C:/Program Files/IBM/WebSphere/AppServer
Executing native2ascii with native encoding 'Cp1252': wkplc.properties → wkplc_ascii.properties
java.lang.Exception: wkplc.properties could not be read.
ERROR: Native2ascii execution failed!
Executing native2ascii with native encoding 'Cp1252': wkplc_comp.properties → wkplc_comp_ascii.properties
These property files are stored under the properties directory <LC_HOME>\ConfigEngine\properties; however, this location has been changed between versions 2.5 and 3.0.1, and in 2.5, the properties are located under <LC_HOME>/ConfigEngine/profiles/<PROFILE_NAME>. You can check them when a relevant error occurs, try to correct the wrong property, and then re-run the migration tool.
If you encounter a failure to connect to the Deployment Manager when performing an export to 3.0.1, it could be also be caused by config engine properties. Since the migration tool retrieves the Deployment Manager SOAP port number from wkplc.properties, when a user modifies the port number in the WAS admin console, the port number will become obsolete in wkplc.properties.
You can avoid such errors by verifying the essential values in the properties before performing the migration.
Applications cannot be launched or logged in to successfully
These sorts of failures are common, not only in the migration process but also in a fresh product install. If you find that a migrated Connections 3.0.1 application does not work well, it's not necessarily caused by the migration process. It may be caused by issues with the source 2.5 environment and freshly installed 3.0.1 environment, so you urged to check the two environments before starting the migration commands, especially import, using the following checklist:
- The 2.5 source applications. Make sure all the applications can be started, that essential functions work well, and there are no critical bugs in these areas. You should also check the latest WAS runtime system.out logs and startServer.log on each node.
- Data integrity of 2.5 source environment. Check relevant database running logs, making sure there are not any critical errors, and check the content store. (We discuss common issues with content store in the following subsection.)
- The 3.0.1 database upgrade result. Check the database wizard result panel and database upgrade log files, making sure there are no critical issues. If you performed side-by-side migration, the you also should check the database transfer log files.
- The 3.0.1 fresh installation. Make sure the IBM Connections 3.0.1 product was installed successfully on the WAS side. Check the install log files, check that all the applications can be started successfully, and check the relevant WAS system.out.log and startServer.log files on each node.
Checking the 2.5 source and 3.0.1 fresh-install target environments may be difficult due to your actual production environment, requiring you to have experience with Connections product install and with database installation and administration.
If applications cannot be launched, it may be caused by omitting some steps after migration. These steps are similar to product install:
- Full synchronization between nodes after migration.
- Database connection. When applications don't start successfully, check database connections, using Resources – DBC – Data sources, in the WAS admin console to determine whether the connections are available.
Content stores are not migrated
The content stores of Connections applications are shared directories between cluster nodes. Their locations are stored in WAS variables, and the migration tool detects the locations through these variables. If you encounter any issues with content stores, follow these steps:
- Check the network connection. Make sure content store can be connected from other cluster nodes.
- Check the value of the WAS variables. Make sure they are correct according to current content store locations.
- Check if Activities are configured to multiple content stores. This is currently not supported by the migration tool. You may need to merge 2.5 content stores or configure multiple content stores for 3.0.1 manually. For more details, refer to the Product Documentation topic, "Defining multiple content stores: ic301."
Data inconsistency after migration
In another scenario, the content stores are migrated without any issues from source Connection servers to target Connection servers but there is some data inconsistency. These issues are due to problems with environmental parameters or error steps:
File system limitations of target Connections server. There may be some limitation parameters, such as the maximum number of files in single directory, the maximum numbers of subdirectories in a single directory, or disk size, that may prevent the target file system from storing all the source content data. The parameters can be checked before performing migration, as part of the 3.0.1 server preparation phase.
Backup/restore method of migrating databases. Besides the method of migrating databases using the database transfer scripts, you can also perform a side-by-side migration via the backup/restore method. This involves backing up the 2.5 source databases and restoring them to 3.0.1 target databases by native database tools, and then upgrading the databases to 3.0.1.
In this process, if the 2.5 Connections server is still in use during migration, that means there is still new to data write into 2.5 databases, and the backup/restore method may cause data inconsistency. For instance, the file attachments of applications are stored in the content store, and their location links are stored in the databases.
If you export the 2.5 content store before doing the database backup, the new uploaded file location links will exist in the backup 2.5 database image that will migrate to the 3.0.1 environment, but the actual files are not contained in the exported 2.5 content store.
Thus, in the migrated 3.0.1 environment, the related file attachments will be seen in the Web pages, but you cannot get their content when you click them.
Customization of content or configuration files are not migrated
If your Connections 2.5 environment has been customized, the customized information may not be migrated. With regard to XML configuration files, the migration tool will transform the essential 2.5 XML configuration files by the default XML schema. However, if there are any changes beyond this, the elements will not be migrated, nor will the customization of the UI.
So, you must do a manual migration for these components, per the Customizing: ic301
Product Documentation topic. Since there are changes from version 2.5, you should follow the standard when you do the migration.
This article has provided the background of the 2.5 to 3.0.1 migration, comparing the 2.5 to 3.0.1 and 3.0 to 3.0.1 processes, and introducing the concepts related to migration. You learned how to troubleshoot migration issues and about the general steps, including log structures, migration-tool internal work directories, and other considerations such as hardware factors.
We described some common issues and their solutions, which can provide examples when you encounter issues in your environment. However, the general steps may not be enough to address issues in some actual complex production environments, so if you have any questions/comments, please feel free to contact the authors.
About the authors
Fan Xiang Jun is a Software Engineer at IBM's China Software Development Lab in Shanghai, where he's been a member of the Lotus Connections Functional Verification Test (FVT) team since March 2009 and is responsible for IBM Connections migration from the 3.0 release. Before that, he worked on software development for the telecom industry for two years. You can reach Fan at email@example.com
Xie Ling is a Staff Software Engineer based at IBM's China Software Development Lab in Shanghai. He has been a member of the Lotus Connections FVT team since August 2007, before which he worked as a developer for IBM Workplace for Business Control and Reporting. You can reach Ling at firstname.lastname@example.org
Yao Jing is a Software Engineer working with the IBM Connections Install and Lotus Quickr Install team in Shanghai, China. She has three years of experience in install technology and has extensive knowledge of WebSphere Application Server deployment and configuration. You can reach Jing at email@example.com