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 migration subprocedures

Migrating a profile to a remote system

Use this procedure to migrate a server profile to a remote system.

If you want to migrate to a machine with a different operating system (for example, from Windows to Linux), or if you want to migrate from a 32-bit to 64-bit machine or vice versa, install the new version of IBM BPM on a third machine with the same operating system and bit type as the migration source machine (for example, Windows if you are migrating from Windows to Linux). Then run the BPMCreateRemoteMigrationUtilities command to create a compressed file that you can use on the migration source machine. You cannot create the migration file on the target machine because a compressed file created on Windows 64-bit, for example, will not work on a machine with a Windows 32-bit operating system, or a Linux or AIX operating system. If you see errors related to the Java Runtime Environment (JRE), set the JAVA_HOME property in the BPMSnapshotSourceProfile.bat/.sh file to point to the JRE from the source product installation.


Procedure

Follow the steps in this procedure to migrate a profile to a remote system.

  1. Optional: Required only for a federated profile. If the profile that is being migrated is a federated profile, synchronize the profile with the new dmgr.

    1. Obtain the new migrated dmgr host and port number.
    2. Edit the source_node_profile_root/properties/wsadmin.properties file. Change the com.ibm.ws.scripting.host value to the new host. Change the com.ibm.ws.scripting.port value to the new port.

    3. Run the syncNode command from the bin directory.

      For example: 

       source_node_profile_root\bin\syncNode.bat myV8DmgrHost.mycompany.com 8879 -username myuser -password mypass

      source_node_profile_root/bin/syncNode.sh myV8DmgrHost.mycompany.com 8879 -username myuser -password mypass
      For more information about manually synchronizing all nodes, see Manually synchronize all nodes in the Websphere Application Server information center.

  2. Create the remote migration utilities image.

    These utilities must be copied to the migration source machine and are used to create the snapshot.

    On the system that has the new version installed and the same operating system as the source system, create a remote migration image using the BPMCreateRemoteMigrationUtilities command from the target_INSTALL_ROOT/bin directory.

    Use the following syntax:

    The location of the remoteMigrationUtilities.zip file is displayed when you run the BPMCreateRemoteMigrationUtilities command. By default, the remoteMigrationUtilities.zip file is located in the appserver_root/util/migration directory.

    For more information about the BPMCreateRemoteMigrationUtilities command, see the BPMCreateRemoteMigrationUtilities command.

  3. Using FTP, RCP, or some other mechanism, copy the remote migration utilities from the target system to the source system, and then extract the remote migration utilities into their own unique directory on the source system.

    On UNIX platforms, use the unzip remoteMigrationUtilities.zip command to extract the contents of the compressed file. If there is no unzip tool installed on the UNIX system, either install the unzip tool manually or use the INSTALL_ROOT/java/bin/jar xf remoteMigrationUtilities.zip command to extract the contents.

    Important: On UNIX platforms, ensure that all extracted files have execute permission for the logged-in user. If they do not, use the chmod command to grant execute permission for all extracted files.

  4. Optional: Required if your applications use WebSphere Adapters:

    1. Extract the application deployment configuration.

      If you have applications that use WebSphere Adapters, extract the application deployment configuration using the BPMQueryDeploymentConfiguration command from the remote_migration_utilities/bin directory.

      The user-specified snapshot directory should not be located in the source or target product installation directories, so that those directories can be removed later if necessary without impacting the configuration files in the snapshot directory.

      Use the following syntax to extract the deployment configuration for a source profile named sourceProfile1 located in the ProcServer installation root directory to the /MigrationSnapshots/ProcServer snapshot directory:


      The BPMQueryDeploymentConfiguration command generates the ApplicationMigrationInformation.xml file to the following directory: 

       snapshot directory/profiles/ profile name

      For more information about the BPMQueryDeploymentConfiguration command, see BPMQueryDeploymentConfiguration command-line utility.

    2. Edit the XML file that contains the application deployment configuration.

      If you extracted the application deployment configuration as described in the previous step, edit the ApplicationMigrationInformation.xml file to mark the WebSphere Adapter instances to update to the new version during runtime migration.

      1. Locate the ApplicationMigrationInformation.xml file.

        The ApplicationMigrationInformation.xml file is located in the following directory: 

         snapshot directory/profiles/ profile name
      2. Edit the ApplicationMigrationInformation.xml file.

        Change the value in <update> from false to true to update a specific WebSphere Adapter instance to the new version. Additionally, copy the new version RAR file of the WebSphere Adapter being marked for update into the following directory: target_INSTALL_ROOT/installableApps.

        Set the <update> value to true for any application that embeds WebSphere Adapter for SAP or WebSphere Adapter for SAP instances configured at Node or Cluster scope.

        CAUTION:

        If the WebSphere Adapter deployed at node level is used to configure the WebSphere Adapter at cluster scope, the update of the WebSphere Adapter must be applied in a consistent manner. If the WebSphere Adapter at cluster scope needs to be updated to the new version, the corresponding instance of WebSphere Adapter defined at each individual node scope for nodes that are participating in the cluster must be updated as well. Failure to perform the WebSphere Adapter update in a consistent manner for participating nodes and cluster level can lead to failures of applications using a WebSphere Adapter instance. For more information on mapping of a cluster-scoped WebSphere Adapter to a node-scope WebSphere Adapter, see Configure Resource Adapters in the WebSphere Application Server information center.

  5. Optional: Required if a custom resource that relies on third-party libraries, such as a custom MQ JMS provider, is configured in the source environment. The dependent third-party libraries will not be migrated, so you must copy them to the target environment manually in order to make the custom resource work correctly in the target environment.

    For a side-by-side migration:

    1. If the dependent third-party libraries are in a folder under <WAS_INSTALL_ROOT> in the source environment, copy them to the same folder under <WAS_INSTALL_ROOT> in the target environment.

    2. If the dependent third-party libraries are in a folder outside <WAS_INSTALL_ROOT> in the source environment, make sure they are in the same location in the target environment after migration.

    For a remote migration:

    No matter where the dependent third-party libraries are placed in the source environment, copy them to the same folder in the target environment.

    If you are migrating from a Windows system to a Linux or UNIX system, or from a Linux or UNIX system to a Windows system, besides copying the third-party libraries to the target environment, you must also modify the configuration of the custom resource so that it refers to the correct location of the libraries, because of the different file path formats of the operating systems.

  6. Create a snapshot of the migration source profile.

    On the migration source system, use the BPMSnapshotSourceProfile command from the remote_migration_utilities/bin directory to create a snapshot directory containing the configuration files that will be migrated. Use the -remoteMigration option to indicate that the target profile will not be created on the same machine. This option saves additional configuration information from the source profile that will be used during remote migration.

    Use the following syntax with the -remoteMigration option to snapshot a source profile named sourceProfile1 located in the ProcServer installation root directory to the /MigrationSnapshots/ProcServer snapshot directory:

    • BPMSnapshotSourceProfile.sh -remoteMigration true /opt/ibm/WebSphere/ProcServer sourceProfile1 /MigrationSnapshots/ProcServer

    • BPMSnapshotSourceProfile.bat -remoteMigration true "C:\Program Files\IBM\WebSphere\ProcServer" sourceProfile1 c:\MigrationSnapshots\ProcServer

    If you see errors related to the JRE, set the JAVA_HOME property in the BPMSnapshotSourceProfile.bat/.sh file to point to the JRE from the source product installation.

    For more information about the BPMSnapshotSourceProfile command, see the BPMSnapshotSourceProfile command.

  7. Copy the migration source snapshot directory to the migration target system.

    Create a compressed file of the source snapshot directory, copy it to the same directory on the target system, and extract it there.

  8. Create the target profile.

    Create the target profile using the BPMCreateTargetProfile command. This profile will not be ready for use until the BPMMigrateProfile command is used to migrate the source profile to the new target profile.

    Use the following syntax to create a target profile for the migration using the source profile named sourceProfile1 copied to the /MigrationSnapshots/ProcServer snapshot directory:

    For more information about the BPMCreateTargetProfile command, see BPMCreateTargetProfile command.

  9. Migrate the source profile to the target profile.

    Migrate the source profile to the target profile using the BPMMigrateProfile command. This command reads the configuration information from the snapshot directory specified by the BPMSnapshotSourceProfile command and copied over to the target system, and migrates it to the target profile.

    Use the following syntax to migrate the source profile named sourceProfile1 copied into the /MigrationSnapshots/ProcServer directory to the target profile:

    • BPMMigrateProfile.sh -username source_profile_user_name -password source_profile_password /MigrationSnapshots/ProcServer sourceProfile1

    • BPMMigrateProfile.bat -username source_profile_user_name -password source_profile_password C:\MigrationSnapshots\ProcServer sourceProfile1

    On Windows, even if security is enabled, the -username and -password parameters do not need to be specified if the server is running as a Windows service. In that case, the parameters are automatically passed into the script that the Windows service uses to shut down the system.

    For more information about the BPMMigrateProfile command, see BPMMigrateProfile command.

  10. Check the migration status.

    Use the BPMMigrationStatus command from the migrated profile/bin directory to verify the current state of the migration.

    The expected result is as follows: 

    Snapshot: Success
Create: Success
Migrate: Success

    The BPMMigrationStatus command reads the status from the snapshot_folder/profile_name/logs folder.

    If you delete the contents of this folder, the command will not be able to obtain the correct status.

    For more information about the BPMMigrationStatus command, see BPMMigrationStatus command.

  11. Scan the file system under the profile directory for occurrences of the old hostname value. Analyze the configuration where the old hostname is still being used and replace it with the new hostname, unless the old hostname is needed, for example, if the database is still present on the old hostname machine.


Results

The profile is migrated from an earlier version of IBM BPM to IBM BPM V8.0.1 on a remote system.


What to do next

Verify that the migration was successful. For instructions, see Verifying migration.

Runtime migration subprocedures


Related tasks:
Migrating an ND environment with full downtime
Migrating an ND environment with minimal downtime