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 using the profile migration wizard

The profile migration wizard is a graphical user interface (GUI) that guides you through the process of migrating a profile. Migrating a profile is just one step in a series of steps required to migrate a stand-alone or ND environment.

Before you invoke the migration wizard, make sure you have performed any required steps. These steps differ depending on whether you are migrating a stand-alone environment or a ND environment. See the Migrating a stand-alone environment, Migrating an ND environment with full downtime, or Migrating an ND environment with minimal downtime topics.

Important: Check to see that the migration wizard is supported on your platform. Refer to the list of supported platforms in "Runtime migration tools."

CAUTION:

The BPMMigrateProfile step that is executed within the migration wizard might need customized values for the -javaoption and -requestTimeout parameters that are not specified through the wizard. On Solaris 64-bit platforms, for example, it might be necessary to override the default value for JVM heap size. In such cases, use the command-line utilities as explained in the topic "Migrating a profile using the command-line utilities" rather than the migration wizard.

This procedure describes the steps necessary to use the IBM BPM profile migration wizard to migrate a profile.

Procedure

1. Optional: Extract the application deployment configuration.

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

   The user-specified snapshot directory should not be located in the source or target product installation directories, so 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 ProcServer620 installation root directory to the /MigrationSnapshots/ProcServer620 snapshot directory:
   

   • 

     BPMQueryDeploymentConfiguration.sh /opt/ibm/WebSphere/ProcServer620 sourceProfile1 /MigrationSnapshots/ProcServer620

   • BPMQueryDeploymentConfiguration.bat "C:\Program Files\IBM\WebSphere\ProcServer620" sourceProfile1 c:\MigrationSnapshots\ProcServer620

   
   

   • BPMQueryDeploymentConfiguration.sh /opt/ibm/WebSphere/ProcServer620 sourceProfile1 /MigrationSnapshots/ProcServer620

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

   <snapshot directory>/profiles/ <profile name>

   Edit the ApplicationMigrationInformation.xml file to mark the WebSphere Adapter instances to update to version 8.0 during runtime migration. See step 2 for information about editing the ApplicationMigrationInformation.xml file.

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

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

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

   1. Locate the ApplicationMigrationInformation.xml file.

      The ApplicationMigrationInformation.xml file resides in the following directory:

      <snapshot directory>/profiles/ <profile name>

   2. Edit the ApplicationMigrationInformation.xml file.

      Edit the value in <update> from "false" to "true" to update a specific WebSphere Adapter instance to version 8.0. Copy the version 8.0 RAR file of the WebSphere Adapter being marked for update into the following directory: target_INSTALL_ROOT/installableApps.

      Set <update> 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 has to be applied in a consistent manner.

      If the WebSphere Adapter at cluster scope needs to be updated to version 8.0, the corresponding instance of WebSphere Adapter defined at each individual node scope for nodes which 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 WebSphere Adapter instance. For more information on mapping of a cluster scoped WebSphere Adapter to a node scoped WebSphere Adapter, refer to Configure Resource Adapters in the WebSphere Application Server information center.

3. 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.

4. Invoke the migration wizard.

   Invoke the migration wizard using the BPMMigrate command from the target_INSTALL_ROOT/bin/bpm_migration directory.

   Use the following syntax:

   • 

     BPMMigrate.sh

   • BPMMigrate.bat

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

5. Read the Welcome screen.

   On the Business Process Management Profile Migration Wizard Welcome screen, read the information on the panel to learn about the migration process, and then click Next.

6. Select the wizard migration type: Typical or Custom.

   On the Select Typical or Custom migration screen, select either a typical wizard migration or a custom wizard migration, and then click Next.

   • If you select Typical, the migration wizard migrates the IBM BPM profile with the default configuration settings.

   • If you select Custom, the migration wizard allows you to customize the configuration settings.

   The default configuration settings are:

   • Snapshot directory:
     • 

       /MigrationSnapshots/ source_INSTALL_ROOT

     • C:\MigrationSnapshots\ source_INSTALL_ROOT

   • Target profile name: The default for the target profile name is the source profile name
   • Target profile directory: The default for the target profile directory is target_install_directory/profiles/ source_profile_name, where source_profile_name is the name of the source profile
   • Port value assignments: Same as source profile port assignments
   • Script compatibility (deployment manage profiles only): Set to true, so scripts from the source profile are still available post migration
   • Application directory settings (dmgr profiles only): Default target installation directory of the target profile

7. Select the source installation.

   On the Select an installation to use as the source of the migration screen, select the source installation directory from the list of detected IBM BPM products or select Browse to select the installation directory of IBM BPM products not detected, and then click Next.

8. Select the source profile.

   In the Select a source profile to use as the source of the migration screen, select the source profile from the list, enter the username and password if the profile has security enabled, then click Next.

9. Define the custom settings or skip to the verify step for a typical migration.

   If you selected Typical in Step 6, skip to Step 10.

   If you selected Custom in Step 6, use the following steps:

   1. Select the snapshot directory.

      On the Enter or browse for the snapshot directory to use for the source profile screen, keep the default snapshot directory or click Browse to navigate to a new snapshot directory, then click Next.

   2. Specify the target profile name and target profile directory.

      On the Select the target profile name and directory screen, keep the default target profile name and directory, or enter a new target profile name and directory in the Target profile name and Target profile directory fields. Click Next.

   3. Select the application migration setting.

      This screen appears only if you are migrating a dmgr profile.

      On the Select the application migration setting screen, specify where the migrated applications should be located and then click Next. The default selection is: Install the applications in the default directory of the target installation.

      • Install the applications in the default directory of the target installation.
      • Keep the current application installation directories.

        Restrictions: If you choose this option, the location is shared by the existing installation and the new installation.

        If you keep the migrated applications in the same locations as those of the earlier version, the following restrictions apply:

        • Mixed-node support limitations must be followed. This means that the following support cannot be used when invoking the wsadmin command:
          • Precompile JSP

          • Use Binary Configuration
          • Deploy EJB

        • You risk losing the migrated applications unintentionally if you later delete applications from these locations when administering (uninstalling, for example) your previous installation.

   4. Select the port migration setting.

      This screen appears only if you are migrating a stand-alone profile.

      On the Select the port migration setting screen, select one of the following options for assigning target profile port values, and then click Next.

      • Use the same port assignments as the source profile.
      • Do not override the ports that were created with the target profile.

      • Assign available ports to the target profile beginning with the following port number:

        If you select this option, enter the first value of the block of consecutive port numbers to assign.

      The default selection is: Use the same port assignments as the source profile.

   5. Select the script compatibility setting.

      This screen appears only if you are migrating a dmgr profile.

      On the Select the script compatibility setting screen, select or clear the Enable source profile administrative scripts for use in the target installation box, then click Next. Selecting this option sets the optional WebSphere Application Server -scriptCompatibility parameter to true. Setting this parameter to true enables the migration to create the following WebSphere Application Server version 6.x configuration definitions:

      • Transport

      • ProcessDef
      • Version 6.x SSL

      instead of the following WebSphere Application Server version 8.0 configuration definitions:

      • Channels

      • ProcessDefs
      • Version 7.0 SSL

      Select this option in order to minimize impacts to existing administration scripts.

      For example, if you have existing wsadmin scripts or programs that use third-party configuration APIs to create or modify the version 6.x configuration definitions, select this option.

      This is meant to provide a temporary transition until all of the nodes in the environment are at the WebSphere Application Server version 8.0 level. When they are all at version 8.0, perform the following actions:

      1. Modify your administration scripts to use all of the version 8.0 settings.

      2. Use the convertScriptCompatibility command to convert your configurations to match all of the version 8.0 configurations. See convertScriptCompatibility command in the WebSphere Application Server information center.

         When following the directions at this link to use the convertScriptCompatibility command, use the BPMMigrateProfile command rather than the WASPostUpgrade command.

10. Verify the migration wizard selections.

    On the Profile migration summary screen, verify the migration selections you made in the wizard, then click Next to begin the migration.

11. Monitor the status of the migration.

    The Migration execution screen displays the status of the profile migration. Monitor the migration to validate that it is running successfully.

12. Retry the migration if it fails.

    If the profile migration fails while copying the source profile, creating the target profile, or migrating the source profile to the target profile, use the following procedure to retry the migration.

    1. Fix the root cause of the failure.
    2. Remove the following artifacts created by the failed migration:

       • The snapshot directory

       • The target profile (using manageprofiles.sh)

       If a dmgr profile was being migrated, and the source dmgr has been disabled, it should be re-enabled using the migrationDisablementReversal command to roll back the migration. However, if the profile migration is going to be re-executed, reversing the disablement of the dmgr is unnecessary.

    3. Use the back button or restart the wizard to run the migration again.

13. Click Next if the migration completed successfully, and click Finish to exit the wizard.

Results

The profile is migrated from an earlier version of IBM BPM to IBM BPM V8.0.1.

What to do next

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

Runtime migration subprocedures

Related concepts:
Runtime migration tools

Related tasks:
Migrating a profile using the command-line utilities