Moving process instances (detailed procedure)

Use this procedure to move process app instances from traditional Business Automation Workflow to Cloud Pak for Business Automation using the Process Admin Console.

Before you begin

Before you begin, ensure that you completed all prerequisites that are listed in Moving process instances between environments.

About this task

This procedure guides you through the complete move process by using the Process Admin Console. The move consists of six main steps that must be completed in sequence.

Procedure

  1. Open the Process Instance Move window.

    From the Installed apps page, locate the snapshot that contains the process instances that you want to move. Open the action menu for that snapshot and click Move instances. The move overview page opens and provides a summary of all steps in the move process.

    1. Read the overview information to understand the complete move workflow.
    2. Check each box to verify that you completed the required manual steps and fully understand the operational consequences of proceeding.
    3. Click Start move to proceed to target environment selection.
  2. Select the target environment and validate
    1. Select a target environment from the list, or click Manage target environments to add a new one.
      From the management page, administrators can add, edit, delete, or verify target environments. After adding or modifying a target environment configuration, you must restart the source environment including the Business Automation Workflow servers and the Deployment Manager (Dmgr) for the changes to take effect.
    2. Configure SSL for secure database connections (if required)

      If your target environment requires SSL/TLS encryption for database connections, configure SSL certificates before running the prerequisites validation. The following procedures apply to Microsoft SQL Server, Oracle, and PostgreSQL databases. No extra steps needed for DB2.

      For Microsoft SQL Server and Oracle:

      Note: If BAW installation path in traditional environment is not /opt/IBM/BAW, fix the path that is used in following steps.
      1. Ensure that the JDBC driver for SQL Server or Oracle exists in the traditional environment. For example, use /opt/IBM/BAW/jdbcdrivers/SQLServer/sqljdbc4.jar for SQL Server, or /opt/IBM/BAW/jdbcdrivers/Oracle/ojdbc8.jar for Oracle.
      2. From the Business Automation Workflow Process Admin Console, go to the Instance move > Target environments section. Create a new target environment with the Database Type set to SQL Server or Oracle, and ensure the Use SSL tunnel toggle is enabled.
      3. Open the WebSphere Admin Console and go to Security > SSL certificate and key management > Key stores and certificates > CellDefaultTrustStore > Signer certificates.
      4. Select the alias that contains your target environment name (created in Step ii) and where the Issued to field matches your database server's hostname or IP address.
      5. Click Extract.
      6. In the File name field, enter the full path where you want to save the certificate file. For the Data type, select Base64-encoded ASCII data, and then click OK.
        Tip: You can store the certificate file in the same folder as the JDBC driver. For example, use /opt/IBM/BAW/jdbcdrivers/SQLServer/db-ssl-cert.arm for SQL Server, or /opt/IBM/BAW/jdbcdrivers/Oracle/db-ssl-cert.arm for Oracle.
      7. Open a command-line window and run the following commands to import the database SSL certificate (exported in Step vi) into the default JRE truststore:
        cd /opt/IBM/BAW/java/bin
        ./keytool -importcert -alias target-env-db-ssl-cert -file /opt/IBM/BAW/jdbcdrivers/<DBType>/db-ssl-cert.arm -keystore /opt/IBM/BAW/java/jre/lib/security/cacerts -storepass changeit
      8. Restart the server and verify the status of target environment in Process Admin Console Target environments page.

      For PostgreSQL:

      Note: If you are not enabling Client Certificate Authentication, skip Step ii and iii.
      1. Download the latest PostgreSQL JDBC driver and place it in the traditional environment. For example, you can use the path: /opt/IBM/BAW/jdbcdrivers/PostgreSQL/postgresql.jar.
      2. Copy the following files (originally used to configure the PostgreSQL database for the CP4BA environment) into the traditional environment. Place them in the same location as the JDBC driver, for example, under the /opt/IBM/BAW/jdbcdrivers/PostgreSQL/folder:
        • client.crt (The client certificate for the database user)
        • client.key (The client private key for the database user)
        • root.crt (The root CA certificate that issued and signed the PostgreSQL server's certificate)
      3. Convert the client.key to PKCS8 format so that it can be recognized and used by WebSphere Application Server. Run the following command: 
        openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt -in client.key -out client.key.pk8
        Note: Generate client.key.pk8 in the same folder as client.key
      4. Use the Instance Move UI to create the new target environment for PostgreSQL, ensuring that the Use SSL tunnel toggle is enabled.

        If Client Certificate Authentication is required, specify the full path of client.crt, client.key.pk8 and root.crt in the Target environment page.

    3. Pair the target environment

      Pair the selected target environment with the source environment before process instance move.

      If you see the Set up target action or a "Set up target first" message, click Set up target and then Pair.

      Wait for the pairing process to complete. Pairing validates structural and version compatibility between the source and target environments to eliminate the risk of data conflicts. Note that environment pairing is permanent and irreversible. If a target environment is already paired with a different source environment, it cannot be repurposed; you must select an alternative, unpaired target environment.

      Important: The pairing process must succeed completely before you can execute the prerequisites check. If pairing fails for any reason, click View error details to troubleshoot and resolve the underlying issues, then retry the pairing operation. Alternatively, you can click Change target environment to select and pair a different target environment.
    4. Click Start check to run the prerequisites validation.
      The validation process checks for:
      • Snapshot in Target
      • In-Flight Process Instances
      • System Health
      • Child Tasks
      • Running System Tasks
      • Case Solution
      • IBM BPM Documents
      • Advanced Features
    5. Review the prerequisites check results.
      The results display the status of each check. If all checks pass, continue to the freeze step.
  3. Resolving Failed Prerequisite Checks
    If any checks fail during the validation phase, use the following steps to remediate the issues:
    1. Review failures: Inspect the list of failed checks and address the specific errors that the system identifies.
    2. Handle warnings: Some checks might generate warnings rather than hard failures. Review these items and perform any required manual interventions to address them.
    3. Re-evaluate: After resolving the identified issues, click Retry check to execute the prerequisites validation again. Continue this iterative process until all errors are cleared and all warnings are manually addressed or formally acknowledged.
    4. Alternative recovery: If the current target environment cannot be made compatible due to persistent failures, you can click Change target environment to select an alternative target environment.
  4. Freeze the snapshot

    After validation passes, freeze the snapshot in the source environment to prepare for move:

    1. Click Start freeze.
    2. Review the freeze operation information in the dialog.
      Important: The freeze operation puts the snapshot in read-only mode. Users cannot start new instances or modify existing instances during the move.
    3. Check the acknowledgment boxes to confirm you understand the freeze operation.
    4. Click Freeze snapshot.
      The freeze operation might take minutes to hours based on the number of active instances.
    After the freeze operation completes successfully, you have two options that are based on your readiness to proceed:
    • Proceed with move: Advance directly to the move step to begin moving your process instances to the target environment.
    • Cancel and revert: If you decide not to continue with the move process currently, you can click Start unfreeze to revert the snapshot and its process instances back to their original, active operating state.
  5. Start the move

    Initiate the move process with required acknowledgments:

    1. Click Start move.
    2. Review the move information dialog.
      Important: IBM BPM target store documents (case documents) are not moved automatically. Manually move them after the move completes. For more information, see Moving process instances between environments.
    3. Check the acknowledgment boxes to confirm you understand:
      • You backed up the target database
      • You understand IBM BPM target store documents require manual move
      • You understand this is a critical operation
    4. Click Start move to begin.
      The move begins and you can monitor progress in the move dashboard.
  6. Monitor move progress
    Monitor the move operation as it runs:
    1. Wait for the move to complete.
      The move runs automatically. You cannot perform any actions during the move except stopping it if needed.
    2. If you need to stop the move, click Stop.
      Important: If you stop the move before it completes, you must restart the move operation from the beginning.
    When the move completes, you see a "move complete" message and can proceed to the go live step.
  7. Go live

    After the move completes, activate the snapshot in the target environment:

    1. Wait for the move to complete.
      You see a "move complete" message.
    2. Check all verification boxes.

      Each checkbox represents a specific category of data that might not be moved or processed automatically during the move process and instead requires manual intervention. For example, if discrepancies exist between your environments, you must manually synchronize local group memberships between the source and target environments to ensure security and task assignment consistency.

    3. Choose one of the following options:
      • Go live: Activate the process application snapshot and resume all moved process instances in the target container environment.
      • Remove move data: If you decide not to cut over, remove all moved data from the target environment to roll back the move.
    4. If you choose to go live, click Go live.
    5. In the confirmation dialog, check the acknowledgment box and click Go live.
      The go live process activates the snapshot in the target environment. This process might take some time.
    Once the Go Live operation completes successfully, the snapshot becomes fully active in the target environment. Process instances that were Active in the source environment are automatically resumed and ready for business. Any instances that were suspended or failed before the move retains their respective states in the target environment for manual administrative review.

Results

Process instances are successfully moved from traditional Business Automation Workflow to Cloud Pak for Business Automation and are operational in the target environment. Users can access and work with moved instances in the containerized environment.

What to do next

After move, complete the following post-move tasks:

  • Reconcile search indexes: From the Process Admin Console, run search index reconciliation to ensure that all moved instances are searchable.
  • Verify Process Federation Server (PFS) configuration: If using PFS, update federation configuration to include the new target environment.
  • Monitor performance: Track system performance metrics for the first 24-48 hours after move.
  • Validate document access: Spot-check document access across different process instances.
  • Update documentation: Update user guides and training materials with new environment URLs and access procedures.
  • Decommission source environment: After you confirm a successful process instance move and verify stable operations in the target environment, plan to remove or archive the original snapshot in the source environment.

If you encounter issues, see Troubleshooting process instance move.