Migrating the runtime environments

IBM BPM, V8.0.1, All platforms > Migrating and upgrading your IBM BPM environment > Migrating from previous versions > Migrating from Teamworks 6 > Migrating from Teamworks 6 to IBM BPM V8.0.1
Migrating the runtime environments

Follow these detailed steps to migrate each Teamworks 6 runtime environment to IBM BPM V8.0.1.

If you have applied Hot Fix 10 to your Teamworks Release 6.2 SP2 (6.2.2) installation, you must uninstall the hot fix (remove materialized views) before migrating to IBM BPM V8.0.1.
The tw_author user must share the same password between the Process Center and the Process Sever, or the password check will fail when Process Designer connects with the migrated Process Server. If necessary, change the password of the tw_author user on the Process Center to match that of the tw_author user on the Process Server after the migration.

Migrate each Teamworks 6 runtime environment to IBM BPM V8.0.1 after completing the development environment migration and testing all of your process applications in the development environment.
If an SSL notification panel opens during the migration process, accept the SSL signer to the truststore.

Procedure

If it is not already installed, install the new version of IBM BPM in your runtime environment, following installation instructions for the Advanced or Standard edition of IBM BPM in the IBM BPM Information Center.

Complete necessary post-installation configuration tasks, such as creating profiles (stand-alone profiles or one or more dmgr and managed node profiles) and creating your deployment environment.
See Configuring IBM BPM for the Advanced or Standard edition of IBM BPM in the IBM BPM Information Center.
You created the Process Center in the previous steps for "Migrating the development environment." In this step, you create the target Process Server. Later, the upgrade tool will migrate the legacy process data of Teamworks 6 to this new Process Server. In Step 6, you will specify some information for the Process Center and the Process Server you have just created.
If you use an external LDAP security provider (such as Active Directory), complete configuration for each of your runtime environments as described in the following table.

Teamworks 6 security provider configuration Required IBM BPM V8.0.1 configuration
If you used the internal Lombardi security provider in conjunction with an external LDAP security provider (such as Active Directory) in Teamworks 6 Configure LDAP as instructed in Configure an LDAP security provider in the post-installation configuration topics for your edition of IBM BPM (Advanced or Standard) in the IBM BPM Information Center.
If you used only an external LDAP security provider in Teamworks 6 Configure LDAP as instructed in Configure an LDAP security provider in the post-installation configuration topics for your edition of IBM BPM (Advanced or Standard) in the IBM BPM Information Center. Additionally, you must delete all default Teamworks users and groups from your external LDAP security provider in your Teamworks 6 environment in order to avoid conflicts with the V8.0.1 security model. (Typically, default Teamworks users and groups begin with tw_, for example, tw_admin and tw_author.)
Make sure to track these changes to your external LDAP security provider in order to easily restore deleted data if required later, for example, in case you need to use your Teamworks 6 environment again.
Your Teamworks 6 environment will not be functional after you remove the default Teamworks users and groups from your external LDAP provider.
You must shut down your Teamworks 6 servers before removing the default users and groups.

If you have installed IBM BPM V8.0.1 in an ND configuration, run the wsadmin command to change its default file-based security provider to a custom provider that is compatible with the original Teamworks 6 provider.

Go to the following directory: target_INSTALL_ROOT /profiles/ deployment_manager_profile_name/bin.
Start the dmgr, and then run the wsadmin command as shown in the following examples.

Operating system Command
Windows wsadmin.bat -conntype SOAP -user user_name -password password -f target_INSTALL_ROOT/BPM/base/profile/actions/scripts/switchToCustomSecurityProvider.py -adminUserName tw_admin -adminPassword tw_admin -nodeName DN2 -serverName BPMPC.AppTarget.DN2.0
UNIX ./wsadmin.sh -conntype SOAP -user user_name -password password -f target_INSTALL_ROOT/BPM/base/profile/actions/scripts/switchToCustomSecurityProvider.py -adminUserName tw_admin -adminPassword tw_admin -nodeName DN2 -serverName BPMPC.AppTarget.DN2.0
Specify the -adminUserName, -adminPassword, -nodeName, and -serverName parameters in the order shown in the preceding examples. The -adminUserName parameter is the user ID that is used for administrative security, the -nodeName parameter denotes the name of any node, and the -serverName parameter denotes the name of any server or cluster member on that node where Process Server is configured. The -nodeName and -serverName parameters are required for copying the 98Database.xml file from the given node and server to the dmgr cell. After you run the wsadmin command, the IBM BPM internal security provider is changed to a custom provider.
The switchToCustomSecurityProvider.py command must be invoked exactly once per dmgr (once per cell) where Process Server is configured.
To make the security configuration changes available, restart the dmgr and all node agents.

Deploy and test your refactored process applications from the V8.0.1 Process Center to each newly installed and configured runtime process server. This step is required to ensure that the process assets that you imported from Teamworks 6 and refactored can actually run on an IBM BPM process server. This step enables you to isolate and resolve any deployment issues before you start to migrate each process server. For more information about handling issues with deployment of process applications, see Troubleshooting deployments.
Edit the upgrade.properties file by providing the correct values for the source (Teamworks 6) and target (IBM BPM V8.0.1) environments.

Go to the following directory: INSTALL_ROOT/BPM/Lombardi/tools/upgrade/upgrade_6x.
Open the upgrade.properties file with a text editor.
Modify each property as necessary. The properties are described in the following table.

Property Description Valid values and examples
utility.jar Set to the directory location of the utility.jar file in the new IBM BPM installation as described in Step 11 of this procedure. Directory location of utility.jar file in the new IBM BPM installation.
teamworks.upgrade.migrateStandaloneTasks By default, stand-alone tasks (tasks resulting from root or favorite services) are not migrated to the new version. This property is commented out by default.
If you want to migrate stand-alone tasks, uncomment this property after ensuring that the value is set to true.
teamworks.upgrade.migrateAdHocReports By default, ad hoc reports are not migrated to the new version. This property is commented out by default.
If you want to migrate ad hoc reports, uncomment this property after ensuring that the value is set to true.
teamworks.target.processServer.serverUser A valid user that has Read access to the process applications to which Teamworks 6 runtime data is migrated. tw_admin, tw_author
teamworks.target.processServer.serverPassword Password for the user specified for the preceding property. tw_admin, tw_author
teamworks.processCenter.serverHost The name of the host where the IBM BPM Process Center is installed. Provide the name or the IP address of the host computer.
teamworks.processCenter.serverPort The port used to access the IBM BPM Process Center on the host where it is installed. Example: 9086
teamworks.processCenter.serverUrl The bootstrap URL for the IBM BPM Process Center server.
You can find this value in the INSTALL_ROOT/AppServer/profiles/ profile_name/config/cells/ cell_name/nodes/ node_name/servers/ server_name/process-center/config/system/50AppServer.xml file under the jndi-url element.
Example: corbaname:iiop:burgundy.mycompany.com:12812
teamworks.processCenter.serverUser A valid user that has Read access to the process applications stored in the IBM BPM Process Center repository. tw_admin, tw_author
teamworks.processCenter.serverPassword Password for the user specified for the preceding property. tw_admin, tw_author
teamworks.target.eventManager.resumeAllSchedulersOnCompletion By default, schedulers for the Event Manager are started when migration is complete. (To learn more about the Event Manager, see the administrative topics in the IBM BPM Information Center.) This property is commented out by default.
If you want to disable schedulers for the Event Manager, uncomment this property after ensuring that the value is set to false.
teamworks.source.processServer.dbType The type of database used by Teamworks 6 Process Server. Valid values: DB2, MSSQL, ORACLE
teamworks.source.processServer.dbDriver The database driver for the Teamworks 6 Process Server. Examples: com.ibm.db2.jcc.DB2Driver, com.jnetdirect.jsql.JSQLDriver, oracle.jdbc.driver.OracleDriver
teamworks.source.processServer.dbUrl The URL for the Teamworks 6 Process Server database. Example: jdbc:db2://localhost:50000/TW_PROC
teamworks.source.processServer.dbUser The user name used to access the Teamworks 6 Process Server database. Example: teamworks
teamworks.source.processServer.dbPassword The password used to access the Teamworks 6 Process Server database. Example: teamworks
teamworks.source.performanceServer.dbType The type of database used by Teamworks 6 Performance Server. Valid values: DB2, MSSQL, ORACLE
teamworks.source.performanceServer.dbDriver The database driver for the Teamworks 6 Performance Server. Examples: com.ibm.db2.jcc.DB2Driver, com.jnetdirect.jsql.JSQLDriver, oracle.jdbc.driver.OracleDriver
teamworks.source.performanceServer.dbUrl The URL for the Teamworks 6 Performance Server database. Example: jdbc:db2://localhost:50000/TW_PERF
teamworks.source.performanceServer.dbUser The user name used to access the Teamworks 6 Performance Server database. Example: teamworks
teamworks.source.performanceServer.dbPassword The password used to access the Teamworks 6 Performance Server database. Example: teamworks
teamworks.processCenter.dbType The type of database used by the IBM BPM Process Center. Valid values: DB2, MSSQL, ORACLE
teamworks.processCenter.dbDriver The database driver for the IBM BPM Process Center database. Examples: com.ibm.db2.jcc.DB2Driver, com.jnetdirect.jsql.JSQLDriver, oracle.jdbc.driver.OracleDriver
teamworks.processCenter.dbUrl The JDBC URL to the IBM BPM Process Center Server database. Example: jdbc:db2://localhost:50000/PR_CTR
teamworks.processCenter.dbUser The user name used to access the IBM BPM Process Center database. Example: bpmuser
teamworks.processCenter.dbPassword The password used to access the IBM BPM Process Center database. Example: bpmuser
dmgr.hostname The host name of the dmgr. Provide this property if the migration target is a ND environment. Example: dmgr.hostname=localhost
dmgr.soap.port The soap port of the dmgr. Provide this property if the migration target is a ND environment. Example: dmgr.soap.port=8879
dmgr.admin.username The user name of the dmgr administrator. Provide this property if the migration target is a ND environment. Example: dmgr.admin.username=tw_admin
dmgr.admin.password The password of the dmgr administrator. Provide this property if the migration target is a ND environment. Example: dmgr.admin.password=tw_admin

Edit the ssl.client.props file under INSTALL_ROOT/BPM/Lombardi/tools/upgrade/upgrade_6x/resources if needed, and provide the correct values for the target (IBM BPM V8.0.1) environments. Refer to ssl.client.props client configuration file in the WebSphere Application Server Version 8.0 information center.
Create an instance mapping file. The instance mapping file maps instances of Teamworks 6 BPDs and services to equivalent constructs in IBM BPM V8.0.1.

Go to the following directory: INSTALL_ROOT/BPM/Lombardi/tools/upgrade/upgrade_6x
Run the upgrade command as shown in the following examples. Be sure to specify a unique file name for the resulting instance mapping file to avoid overwriting any existing instance mapping files.

Operating system Command
Windows upgrade_6x.bat -c upgrade.properties -b [file for resulting instance mapping xml]
UNIX ./upgrade_6x.sh -c upgrade.properties -b [file for resulting instance mapping xml]
The following parameters are available for use with the upgrade command:

Parameter Description
-profileName This parameter is optional and should be used if you want to run the migration against a profile that is different from the default profile for your IBM BPM environment. Specify the name of the profile that you want to use.
In a ND environment, specify the name of the Dmgr profile.
-nodeName (Required in ND environments) This parameter is required for network deployment environments. The upgrade command fails if you do not specify this parameter and the -serverName parameter in network deployment environments. Specify the node name of one cluster member in your ND environment.
-serverName (Required in ND environments) This parameter is required for network deployment environments. The upgrade command fails if you do not specify this parameter and the -nodeName parameter in network deployment environments. Specify the server name of a cluster member that matches the node name.

The upgrade command gathers process instance information and creates an instance mapping file.

Examine the instance mapping file and enter any information that is missing.

Go to the directory that you specified for the instance mapping file in the previous step.
Open the instance mapping file with a text editor.
Ensure that a mapping from Teamworks 6 to IBM BPM V8.0.1 exists for each BPD that has in-flight instances and for each service that results in a task. (Services that produce tasks require an entry in the mapping file only if the teamworks.upgrade.migrateStandaloneTasks property in the upgrade.properties file is set to true.) Plus, each mapping entry must have a designated snapshot and process application for IBM BPM V8.0.1 To learn how to examine and adjust the generated instance mapping file, see Instance mapping file examples.
If : For Process Servers that are not connected to the Process Center (offline), you must open the resulting instance mapping file and manually create a mapping entry for each BPD that has in-flight instances and for each service that results in a task. (Services that produce tasks require an entry in the mapping file only if the teamworks.upgrade.migrateStandaloneTasks property in the upgrade.properties file is set to true.) The mapping file includes the format to follow for the required entries.
Stop the Teamworks 6 servers. Instructions for stopping Teamworks servers are available in your Teamworks Installation and Configuration Guide.
Before stopping Teamworks 6 servers, be sure that you send definitions to the Performance Server. If not, queries of performance data may not work as expected after the migration. To send definitions, select File > Send Definitions to Performance Server from the main menu in Teamworks Authoring Environment.
Migrate encrypted passwords to an updated encryption level for IBM BPM.

Copy the utility.jar file from [Teamworks_home]/upgrade/lib in the Teamworks 6 installation to the filesystem of the new IBM BPM installation.
In the INSTALL_ROOT/BPM/Lombardi/tools/upgrade/upgrade_6x directory, modify the upgrade.properties file to set the value of the utility.jar property to the directory location of the utility.jar file in the new IBM BPM installation.

If you are migrating a ND environment, manually start the messaging cluster and keep all other clusters stopped (the application cluster and the support cluster) before migrating.
Run the upgrade command, passing the instance mapping file as a parameter.
If you deployed and tested your refactored process applications as described in Step 5, run the upgrade command with the -cleanAndRestart flag to ensure that the databases in each runtime environment are ready for migration.

Go to the following directory: INSTALL_ROOT/BPM/Lombardi/tools/upgrade/upgrade_6x
Run the upgrade command as shown in the following examples.

Operating system Command
Windows upgrade_6x.bat -c upgrade.properties -cleanAndRestart [completed instance mapping file]
UNIX ./upgrade_6x.sh -c upgrade.properties -cleanAndRestart [completed instance mapping file]

The following parameters are available for use with the upgrade command:

Parameter Description
-profileName This parameter is optional and should be used if you want to run the migration against a profile that is different from the default profile for your IBM BPM environment. Specify the name of the profile that you want to use.
Important: -profileName should be the name of a process server profile, not a process center profile (which is the default).
In a ND environment, specify the name of the Dmgr profile.
If you deployed and tested your refactored process applications as described in Step 5, run the upgrade command with the -cleanAndRestart flag to ensure that the databases in each runtime environment are ready for migration.
Important: Back up your databases before you run the command. The clean and restart task cannot be rolled back.
-nodeName (Required in ND environments) This parameter is required for network deployment environments. The upgrade command fails if you do not specify this parameter and the -serverName parameter in network deployment environments. Specify the node name of one cluster member in your ND environment.
-serverName (Required in ND environments) This parameter is required for network deployment environments. The upgrade command fails if you do not specify this parameter and the -nodeName parameter in network deployment environments. Specify the server name of a cluster member that matches the node name.
-perfNodeName (Required in ND environments) This parameter is required for network deployment environments. The upgrade command uses this parameter to start and stop Performance Data Warehouse. Specify the node name of the cluster member that installed the Performance Data Warehouse in your ND environment. Typically, this is the support cluster.
-perfServerName (Required in ND environments) This parameter is required for network deployment environments. The upgrade command uses this parameter to start and stop Performance Data Warehouse. Specify the server name of the cluster member that installed the Performance Data Warehouse in your ND environment. Typically, this is the support cluster.

If you have V8.0.1 in an ND configuration, run the migration against the dmgr profile of your ND environment.
The upgrade command will change source version passwords for tw_admin, tw_user, tw_author, and tw_webservice internal users with passwords set for these users in the IBM BPM V8.0.1 WebSphere Application Server administrative console during profile creation. For better security, reset these passwords after migration. Refer to "Changing the default administrative password.
The original internal user's password will be overwritten by the new password at the target system. The internal users include tw_admin, tw_user, tw_author, and tw_webservice. For better security, reset these passwords after migration if they are the default passwords.
The upgrade command installs process applications from IBM Process Center and migrates process instances. The upgrade command displays progress information as it completes the migration tasks and logs more detailed information to: INSTALL_ROOT/profiles/ PROFILE_NAME/logs. PROFILE_NAME is the value that you specified for the -profileName parameter.
If you did not specify this parameter, PROFILE_NAME is the default profile name of the cell. The log file name contains the name of the tool as the prefix and the timestamp of the current time.
If you set the -nodeName and -serverName parameters, these are also part of the log file name. If the upgrade command fails, you should address identified problems and then start from the beginning of this procedure.

If for some reason the Process Center is not reachable, for example, if the Process Center and the offline Process Server are located in separate networks, follow the instructions in Create an installation package and then the instructions in Extracting an installation package to a file. Place the extracted installation package in the INSTALL_ROOT/BPM/Lombardi/tools/upgrade/upgrade_6x/install-apps directory to migrate the runtime environment.
So that the migration tool can migrate ad hoc reports when the Process Center is not reachable during migration, use the upgrade_6x -g/-generateAdhocReport path command to generate the installation package for ad hoc reports and place it in the install-apps folder.
Run your regression test suite to identify any issues that may have been introduced during this process.
Decommission the Teamworks 6 Process Server.
Archive the Teamworks 6 Process Server and Performance Server databases and then delete or drop those databases.
Move the upgrade.properties file to a safe location. The upgrade.properties file contains passwords; this step is required in order to avoid a security breach.

Instance mapping file examples
The instance mapping file that you generate for each runtime environment must be complete as shown in the provided examples.

: Migrating from Teamworks 6 to IBM BPM V8.0.1

Related tasks:
Migrating the development environment

Related information:
Changing the default password for tw_admin and tw_user
Create an installation package
Extracting an installation package to a file

Operating system	Command
Windows	wsadmin.bat -conntype SOAP -user user_name -password password -f target_INSTALL_ROOT/BPM/base/profile/actions/scripts/switchToCustomSecurityProvider.py -adminUserName tw_admin -adminPassword tw_admin -nodeName DN2 -serverName BPMPC.AppTarget.DN2.0
UNIX	./wsadmin.sh -conntype SOAP -user user_name -password password -f target_INSTALL_ROOT/BPM/base/profile/actions/scripts/switchToCustomSecurityProvider.py -adminUserName tw_admin -adminPassword tw_admin -nodeName DN2 -serverName BPMPC.AppTarget.DN2.0

Property	Description	Valid values and examples
utility.jar	Set to the directory location of the utility.jar file in the new IBM BPM installation as described in Step 11 of this procedure.	Directory location of utility.jar file in the new IBM BPM installation.
teamworks.upgrade.migrateStandaloneTasks	By default, stand-alone tasks (tasks resulting from root or favorite services) are not migrated to the new version.	This property is commented out by default. If you want to migrate stand-alone tasks, uncomment this property after ensuring that the value is set to true.
teamworks.upgrade.migrateAdHocReports	By default, ad hoc reports are not migrated to the new version.	This property is commented out by default. If you want to migrate ad hoc reports, uncomment this property after ensuring that the value is set to true.
teamworks.target.processServer.serverUser	A valid user that has Read access to the process applications to which Teamworks 6 runtime data is migrated.	tw_admin, tw_author
teamworks.target.processServer.serverPassword	Password for the user specified for the preceding property.	tw_admin, tw_author
teamworks.processCenter.serverHost	The name of the host where the IBM BPM Process Center is installed.	Provide the name or the IP address of the host computer.
teamworks.processCenter.serverPort	The port used to access the IBM BPM Process Center on the host where it is installed.	Example: 9086
teamworks.processCenter.serverUrl	The bootstrap URL for the IBM BPM Process Center server. You can find this value in the INSTALL_ROOT/AppServer/profiles/ profile_name/config/cells/ cell_name/nodes/ node_name/servers/ server_name/process-center/config/system/50AppServer.xml file under the jndi-url element.	Example: corbaname:iiop:burgundy.mycompany.com:12812
teamworks.processCenter.serverUser	A valid user that has Read access to the process applications stored in the IBM BPM Process Center repository.	tw_admin, tw_author
teamworks.processCenter.serverPassword	Password for the user specified for the preceding property.	tw_admin, tw_author
teamworks.target.eventManager.resumeAllSchedulersOnCompletion	By default, schedulers for the Event Manager are started when migration is complete. (To learn more about the Event Manager, see the administrative topics in the IBM BPM Information Center.)	This property is commented out by default. If you want to disable schedulers for the Event Manager, uncomment this property after ensuring that the value is set to false.
teamworks.source.processServer.dbType	The type of database used by Teamworks 6 Process Server.	Valid values: DB2, MSSQL, ORACLE
teamworks.source.processServer.dbDriver	The database driver for the Teamworks 6 Process Server.	Examples: com.ibm.db2.jcc.DB2Driver, com.jnetdirect.jsql.JSQLDriver, oracle.jdbc.driver.OracleDriver
teamworks.source.processServer.dbUrl	The URL for the Teamworks 6 Process Server database.	Example: jdbc:db2://localhost:50000/TW_PROC
teamworks.source.processServer.dbUser	The user name used to access the Teamworks 6 Process Server database.	Example: teamworks
teamworks.source.processServer.dbPassword	The password used to access the Teamworks 6 Process Server database.	Example: teamworks
teamworks.source.performanceServer.dbType	The type of database used by Teamworks 6 Performance Server.	Valid values: DB2, MSSQL, ORACLE
teamworks.source.performanceServer.dbDriver	The database driver for the Teamworks 6 Performance Server.	Examples: com.ibm.db2.jcc.DB2Driver, com.jnetdirect.jsql.JSQLDriver, oracle.jdbc.driver.OracleDriver
teamworks.source.performanceServer.dbUrl	The URL for the Teamworks 6 Performance Server database.	Example: jdbc:db2://localhost:50000/TW_PERF
teamworks.source.performanceServer.dbUser	The user name used to access the Teamworks 6 Performance Server database.	Example: teamworks
teamworks.source.performanceServer.dbPassword	The password used to access the Teamworks 6 Performance Server database.	Example: teamworks
teamworks.processCenter.dbType	The type of database used by the IBM BPM Process Center.	Valid values: DB2, MSSQL, ORACLE
teamworks.processCenter.dbDriver	The database driver for the IBM BPM Process Center database.	Examples: com.ibm.db2.jcc.DB2Driver, com.jnetdirect.jsql.JSQLDriver, oracle.jdbc.driver.OracleDriver
teamworks.processCenter.dbUrl	The JDBC URL to the IBM BPM Process Center Server database.	Example: jdbc:db2://localhost:50000/PR_CTR
teamworks.processCenter.dbUser	The user name used to access the IBM BPM Process Center database.	Example: bpmuser
teamworks.processCenter.dbPassword	The password used to access the IBM BPM Process Center database.	Example: bpmuser
dmgr.hostname	The host name of the dmgr. Provide this property if the migration target is a ND environment.	Example: dmgr.hostname=localhost
dmgr.soap.port	The soap port of the dmgr. Provide this property if the migration target is a ND environment.	Example: dmgr.soap.port=8879
dmgr.admin.username	The user name of the dmgr administrator. Provide this property if the migration target is a ND environment.	Example: dmgr.admin.username=tw_admin
dmgr.admin.password	The password of the dmgr administrator. Provide this property if the migration target is a ND environment.	Example: dmgr.admin.password=tw_admin

Operating system	Command
Windows	upgrade_6x.bat -c upgrade.properties -b [file for resulting instance mapping xml]
UNIX	./upgrade_6x.sh -c upgrade.properties -b [file for resulting instance mapping xml]

Parameter	Description
-profileName	This parameter is optional and should be used if you want to run the migration against a profile that is different from the default profile for your IBM BPM environment. Specify the name of the profile that you want to use. In a ND environment, specify the name of the Dmgr profile.
-nodeName (Required in ND environments)	This parameter is required for network deployment environments. The upgrade command fails if you do not specify this parameter and the -serverName parameter in network deployment environments. Specify the node name of one cluster member in your ND environment.
-serverName (Required in ND environments)	This parameter is required for network deployment environments. The upgrade command fails if you do not specify this parameter and the -nodeName parameter in network deployment environments. Specify the server name of a cluster member that matches the node name.

Operating system	Command
Windows	upgrade_6x.bat -c upgrade.properties -cleanAndRestart [completed instance mapping file]
UNIX	./upgrade_6x.sh -c upgrade.properties -cleanAndRestart [completed instance mapping file]