IBM BPM, V8.0.1, All platforms > Migrating and upgrading your IBM BPM environment > Migrating from previous versions > Migrating your IBM BPM Advanced V7.5.x or WebSphere Process Server V7.x or V6.2.x runtime

Runtime premigration checklist

Before you begin the process of migrating to a new version of IBM BPM, you should verify each of the items in this checklist.


Hardware, operating system, and database prerequisites

Verify that your target migration environment–including hardware, operating systems, and database prerequisites–is a supported operating environment for IBM BPM V8.0.1.

Depending on your IBM BPM configuration, visit:


IBM BPM installation images

Download the IBM BPM installation images and the latest fix packs so they are ready to be installed on each system to be migrated. Validate that there is sufficient storage on the system to have IBM BPM and fix packs installed.

Upgrading DB2 for z/OS to supported versions

If your DB2 for z/OS database is at version 7, upgrade it to DB2 for z/OS version 8 or 9 before performing the migration. DB2 for z/OS version 7 is no longer supported by IBM.

If your DB2 for z/OS database is at version 7 or 8, upgrade it to DB2 for z/OS version 9 or 10 before performing the migration. DB2 for z/OS versions 7 and 8 are no longer supported by IBM.

After you upgrade your DB2 database to version 8 or 9, you must apply table and index updates to the Common database and the Business Process Choreographer database. Use the SQL in the dbscripts directory to assist you with applying table and index updates.

If you are upgrading from DB2 version 7, after you upgrade your DB2 database to version 9 or 10, you must apply table and index updates to the Common database and the Business Process Choreographer database. Use the SQL in the dbscripts directory to assist you with applying table and index updates.

To access the SQL, go to the following directories:

/WebSphere/V7T2DM/DeploymentManager/dbscripts/ProcessChoreographer/DB2zOSV8

/WebSphere/V7T2DM/DeploymentManager/dbscripts/CommonDB/DB2zOSV8

WAS_HOME/dbscripts/ProcessChoreographer/DB2zOSV8

WAS_HOME/dbscripts/CommonDB/DB2zOSV8

While in the directory, check for members like upgradeSchema610DB2zOSV7.sql, where 610 is the version of IBM BPM you are migrating from. If they are present, edit the SQL accordingly and apply the changes to the upgraded IBM BPM for z/OS database.


Upgrading Oracle database and JDBC driver

If you are using Oracle 9i, and have not yet upgraded your database to 10g or 11g, download the Oracle 10g or 11g install images and be prepared to upgrade to the new database version as a step in the procedures.

If you are using the Oracle ojdbc14.jar or the ojdbc5.jar JDBC driver, download the new ojdbc6.jar JDBC driver and be prepared to install it as a step in the procedures.


Checking for changesets in the database repository

When migrating from WebSphere Process Server V6.2 to IBM BPM V8.0.1, check for the existence of changesets in the database repository. A changeset defines one or more changes to be applied to the database.

Perform the following procedure to check for changesets in the database repository:

  1. Stop all the servers, either in stand-alone or in a clustered setup.
  2. Connect to the CommonDB database schema by using the SQL Command client.

  3. Run the SQL command as follows:

    select count(*) from w_statement 
    		where pred_id=(select id from w_uri where uri like '%changeSetState')
    		and obj_id IN (select id from w_obj_lit_string where litval IN ('DRAFT', 'PENDING' , 'APPROVED')) 
    		and obj_typ_cd=6 
    		and version_to=2000000000;

    If the SQL command reveals database records, there are changesets in the repository that are in the active state.

    As a result, no new content will be bootstrapped to the repository after migration, resulting in data loss and unexpected behavior. To avoid this scenario, run the following SQL command:

    update w_statement set obj_id=(select id from w_obj_lit_string where litval='PUBLISHED') 
    		where pred_id=(select id from w_uri where uri like '%changeSetState')
    		and obj_id IN (select id from w_obj_lit_string where litval IN ('DRAFT', 'PENDING' , 'APPROVED'))
    		and obj_typ_cd=6
    		and version_to=2000000000;

Update applications using WebSphere Adapters, version 6.0.2.x, 6.1.x.x, or 6.2.x

WebSphere Adapters versions 6.0.2.x and 6.1.x.x are not supported by IBM BPM version V8.0.1. This lack of compatibility necessitates that you update all the applications that use the WebSphere Adapters versions 6.0.2.x and 6.1.x.x and all the WebSphere Adapters versions 6.0.2.x and 6.1.x.x instances installed at node level to a compatible version for V8.0.1 migration.

Perform the updates using one of the following methods:


Update applications using CICS Adapters, version 6.x

CICS Adapters version 6.x are not supported during runtime migration. This necessitates that you update all the applications that use the CICS Adapters version 6.x and that you update all CICS Adapters version 6.x instances installed at node level to a compatible version for V8.0.1.

Perform the updates by uninstalling the CICS Adapter and related applications manually from the source environment before you perform the runtime migration. Update the CICS Adapter in IBM Integration Designer and redeploy the adapter to the target environment manually after you have completed runtime migration procedures.

For more information on updating the applications to use the CICS Adapter V8.0, see the WebSphere Adapter documentation in the IBM Integration Designer information center.


Applying the WebSphere Adapter interim fix

If any of the applications in the source environment embed any of the WebSphere Adapters (with the exception of SAP) at version 6.2.0 or use WebSphere Adapter version 6.2.0 configured at the node level, and should not be updated to V8.0.1 during runtime migration, you must apply an adapter interim fix in the source environment before starting the migration procedure. This can be done as follows:

  1. Obtain the "Mandatory adapter fix for running 6.1 and 6.2 Adapters on WPS v7.0" for the WebSphere Adapter(s) your applications use. Contact the IBM support team to obtain the corresponding Adapter interim fix.

  2. Apply this fix over the WebSphere Adapter on the source environment. Use one of the following procedures, depending on whether the WebSphere Adapter is embedded in the application or installed at the node level.

    • If the WebSphere Adapter is embedded in the application, use the following procedure to apply the interim fix:

      1. Log on to the administrative console.

      2. Select the Application, then click Update.

      3. In the Application update options section, select Replace or add a single module, then type the name of the WebSphere Adapter RAR file that represents the single module you want to update.

      4. Click Browse to select the updated RAR file on the local file system that has the changes.

      5. Select the default values in the remaining steps, then click Finish. This will ensure that existing configurations, for example, are not changed and that only JAR files will be updated.

    • If the WebSphere Adapter is installed at the node level, use the following procedure to apply the interim fix:

      1. From the administrative console, browse the WebSphere Adapter instance and make note of all Managed Connection Factory and ActivationSpec instances configured for the adapter.

      2. Select the WebSphere Adapter, then click Delete to uninstall the adapter.

      3. Install the new version of the WebSphere Adapter.

      4. Configure the Managed Connection Factory and ActivationSpec instance made note of in Step a.

    If the dependent applications have configuration for ManagedConnectionFactory and ActivationSpec in the .import and .export files, you can also uninstall and install the application to re-create the configuration for ManagedConnectionFactory and ActivationSpec. If the application uses JNDI reference to configure the ManagedConnectionFactory and ActivationSpec, you must manually re-create the instances as documented in steps 1 and 2.


Update WebSphere Adapter for SAP


Important: If the source environment is 6.2, you must perform the update activities for the WebSphere Adapter for SAP. If the source environment is 7.x, this is not necessary.

Configure the new SAP application dependency libraries to the target environment before starting any cluster or server processes that have applications using WebSphere Adapter for SAP. Without the SAP application libraries configured, the WebSphere Adapter for SAP cannot connect to the SAP application and perform the needed function for the application to work successfully. For details on which libraries to configure and in which directories, see Adding external software dependencies to the server runtime.

6.2.x versions of WebSphere Adapter for SAP are not supported by IBM BPM V8.0.1 because of incompatible changes introduced by the SAP SAPJCO library updated to support the Java Runtime Environment version 1.6. You must update all the applications that use the WebSphere Adapter for SAP and update all WebSphere Adapter for SAP instances installed at node level to V8.0.1. Perform the updates using one of the following methods:


Source profile backup directory storage

During migration, the profile being migrated is backed up in case a rollback is necessary. The space available for the profile backup directory should be at least the size of the configuration directory and applications of the source file.


Source database backup storage

You should back up your source product databases before migrating them, but first verify that sufficient space exists to back up these databases. The size required for the backups will depend on the size of your production databases and the specifics of your database backup strategy.


Source profile snapshot directory storage

The configuration files in the profile to be migrated are copied during the migration procedure to a snapshot directory that then becomes the source for the profile migration. The directory is an optional parameter for the BPMSnapshotSourceProfile command or a configurable value in the IBM BPM profile migration wizard and is defaulted to MigrationSnapshots.

Before migration, verify that there is sufficient storage for the snapshot directory. The storage requirements can be estimated by summing up the following amounts:

Target profile directory storage

During migration the target profile is created by using the BPMCreateTargetProfile command or the IBM BPM profile migration wizard, and the source profile is migrated to the target profile referenced from the target installation.

Before migration, verify that there is sufficient storage for the target profile directory. The storage requirements can be estimated by summing up the following amounts:


Business Process Choreographer data migration: Materialized views

If you were using a custom table definition file for named materialized views, they will be dropped by the data migration script. IBM BPM can re-create the named materialized views only if the customTableDefinition entry points to a custom table definition XML file that it can access. To verify that IBM BPM can re-create your named materialized views, perform the following:

  1. Verify that IBM BPM is up and running.

  2. In the administrative console, click either Servers > Application servers > serverName or Clusters > clusterName, then under Business Integration expand Business Process Choreographer, then click Business Flow Manager > Custom Properties.

  3. In the list of custom properties for the business container, search for an entry named customTableDefinition. This entry specifies the file system location of the custom table definition file, for example, path/customData.xml.
  4. Verify that the XML file exists:

    • In a stand-alone environment, on the server node

    • In a cluster environment, on each node that hosts a cluster member

    If the file system location of the XML file contains a WebSphere variable, for example, ${WAS_INSTALL_ROOT}, the value of this variable can change during migration. You might need to copy your XML file to the new location before you start your migrated servers or clusters.

  5. Verify that the XML file can be accessed by IBM BPM.


Ulimit setting

On UNIX systems, to avoid an error during profile migration caused by too many open files, increase the ulimit setting on the system running the profile migration process.


Database authorization

Verify whether you will be able to run all the database scripts using a single user ID, or whether your database administrator might have to run any of them.

See the information in the Databases topic for more information on the required permissions for the product databases.


Determining the migration type

If you are migrating a stand-alone profile, determine whether you plan to do a side-by-side migration, a migration to a remote system, or a migration that requires the operating system on the source system to be upgraded during the migration process.

If you are migrating a stand-alone profile, determine whether you plan to do a side-by-side migration or a migration to a remote system. If you are migrating a ND environment, analyze the full downtime and minimal downtime procedures carefully to determine which procedure more closely fits your requirements.


Checking the maximum heap size of the JVM

If you are migrating an environment with 64-bit Java architecture to an environment with 32-bit Java architecture on a Windows platform, check the maximum heap size property of the JVM setting for each server in the source environment. The maximum heap size of the 32-bit JVM on a Windows platform is 1.5 G. If this value is greater than 1.5 G, the server in the target environment will not start and will display the following error message: JVMJ9VM015W Initialization error for library j9gc26(2): Failed to instantiate heap; Could not create the Java virtual machine. Either migrate to 8.0.1 with 64-bit Java architecture, or lower the value of the maximum heap size of the JVM before migrating.

To change the JVM configuration settings, complete the steps in Java virtual machine settings in the WebSphere Application Server information center.


Migrating root configurations to non-root

If you are migrating a previous version environment with root user permissions to V8.0.1 with non-root user permissions, complete the steps in Migrating root configurations to non-root in the WebSphere Application Server information center before attempting the migration procedure.

The reference to USER_HOME in the "Migrating root configurations to non-root" instructions refers to the USER_INSTALL_ROOT or the root directory of the source profile.


Migrating non-root configurations to root

If you are migrating a previous version environment with non-root user permissions to V8.0.1 with root user permissions, complete the steps in Migrating non-root configurations to root in the WebSphere Application Server information center before attempting the migration procedure.


Migrating WebSphere Integration Developer

If you are migrating the target runtime environment to IBM BPM V8.0.1, you will be able to run the applications that you previously deployed, even if you have not migrated WebSphere Integration Developer. However, if you want to edit the applications, you must also migrate WebSphere Integration Developer or IBM Integration Designer to a compatible version so that the major versions of the two products match.

If you are migrating the target runtime environment to IBM BPM V8.0, and want to run and edit the applications that you previously deployed, install the latest version of IBM Integration Designer on a supported operating system, and then re-create the required applications.


Enabling application security

Verify that application security is enabled.Refer to Configure application security.

Migrating your IBM BPM Advanced V7.5.x or WebSphere Process Server V7.x or V6.2.x runtime