Chapter 6. Process instance migration

Process instance migration (PIM) service is a Technology Preview standalone service containing a user interface and a back-end, and packaged as a Thorntail uber-JAR. You can use the PIM service to define the migration between two different process definitions, known as a migration plan. The user can then apply the migration plan to the running process instance in a specific process server.

For more information about the PIM service, see Process Instance Migration Service in KIE (Drools, OptaPlanner and jBPM ).

6.1. Installing the process instance migration service

You can use the process instance migration (PIM) service to create, export and execute migration plans. The PIM service is provided through a GitHub repository. To install the PIM service, clone the GitHub repository, then run the service and access it in a web browser.

Prerequisites

  • You have defined processes in a backup-ed Red Hat Process Automation Manager development environment.

Procedure

  1. Download the rhpam-7.6.0-add-ons.zip file from the Software Downloads page for Red Hat Process Automation Manager 7.6.
  2. Unzip the downloaded archive.
  3. Move the rhpam-7.6.0-process-migration-service-standalone.jar file from the add-ons archive to a desired location.
  4. In the location, create a YAML file containing the kieserver and Thorntail configuration, for example:

    thorntail:
      deployment:
        process-migration.war:
          jaxrs:
            application-path: /rest
          web:
            login-config:
              auth-method: BASIC
              security-domain: pim
            security-constraints:
              - url-pattern: /*
                roles: [ admin ]
              - url-pattern: /health/*
      datasources:
        data-sources:
          pimDS:
            driver-name: h2
            connection-url: jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
            user-name: DS_USERNAME
            password: DS_PASSWORD
      security:
        security-domains:
          pim:
            classic-authentication:
              login-modules:
                UsersRoles:
                  code: UsersRoles
                  flag: required
                  module-options:
                    usersProperties: application-users.properties
                    rolesProperties: application-roles.properties
    kieservers:
      - host: http://localhost:8080/kie-server/services/rest/server
        username: KIESERVER_USERNAME
        password: KIESERVER_PASSWORD
      - host: http://localhost:8280/kie-server/services/rest/server
        username: KIESERVER_USERNAME
        password: KIESERVER_PASSWORD1
  5. Start the PIM service:

    $ java -jar rhpam-7.6.0-process-migration-service-standalone.jar -s./config.yml
  6. To enable auto-detection of a JDBC driver by Thorntail, add the JAR file of the JDBC driver name to the thorntail.classpath system property. For example:

    $ java -Dthorntail.classpath=./h2-1.4.200.jar -jar rhpam-7.6.0-process-migration-service-standalone.jar -s ./config.yml
    Note

    The h2 JDBC driver is included by default. You can use different JDBC drivers to connect to different external databases.

  7. After the PIM service is up and running, enter http://localhost:8080 in a web browser.

6.2. Creating a migration plan

You can define the migration between two different process definitions, known as a migration plan, in the process instance migration (PIM) service web UI.

Prerequisites

  • You have defined processes in a backup-ed Red Hat Process Automation Manager development environment.
  • The process instance migration service is running.

Procedure

  1. Enter http://localhost:8080 in a web browser.
  2. Log in to the PIM service.
  3. In the upper right corner of the Process Instance Migration page, from the KIE Service list select the KIE Service you want to add a migration plan for.
  4. Click Add Plan. The Add Migration Plan Wizard window opens.
  5. In the Name field, enter a name for the migration plan.
  6. Optional: In the Description field, enter a description for the migration plan.
  7. Click Next.
  8. In the Source ContainerID field, enter the source container ID.
  9. In the Source ProcessId field, enter the source process ID.
  10. Click Copy Source To Target.
  11. In the Target ContainerID field, update the target container ID.
  12. Click Retrieve Definition from backend and click Next.

    pim migration wizard
  13. From the Source Nodes list, select the source node you want to map.
  14. From the Target Nodes list, select the target node you want to map.
  15. If the Source Process Definition Diagram pane is not displayed, click Show Source Diagram.
  16. If the Target Process Definition Diagram pane is not displayed, click Show Target Diagram.
  17. Optional: To modify the view in the diagram panes, perform any of the following tasks:

    • To select text, select the pim selection icon icon.
    • To pan, select the pim pan icon icon.
    • To zoom in, select the pim zoom in icon icon.
    • To zoom out, select the pim zoom out icon icon.
    • To fit to viewer, select the pim fit to icon icon.
  18. Click Map these two nodes.
  19. Click Next.
  20. Optional: To export as a JSON file, click Export.
  21. In the Review & Submit tab, review the plan and click Submit Plan.
  22. Optional: To export as a JSON file, click Export.
  23. Review the response and click Close.

6.3. Editing a migration plan

You can edit a migration plan in the process instance migration (PIM) service web UI. You can modify the migration plan name, description, specified nodes, and process instances.

Prerequisites

  • You have defined processes in a backup-ed Red Hat Process Automation Manager development environment.
  • The PIM service is running.

Procedure

  1. Enter http://localhost:8080 in a web browser.
  2. Log in to the PIM service.
  3. On the Process Instance Migration page, select the Edit Migration Plan pim edit icon icon on the row of the migration plan you want to edit. The Edit Migration Plan window opens.
  4. On each tab, modify the details you want to change.
  5. Click Next.
  6. Optional: To export as a JSON file, click Export.
  7. In the Review & Submit tab, review the plan and click Submit Plan.
  8. Optional: To export as a JSON file, click Export.
  9. Review the response and click Close.

6.4. Exporting a migration plan

You can export migration plans as a JSON file using the process instance migration (PIM) service web UI.

Prerequisites

  • You have defined processes in a backup-ed Red Hat Process Automation Manager development environment.
  • The PIM service is running.

Procedure

  1. Enter http://localhost:8080 in a web browser.
  2. Log in to the PIM service.
  3. On the Process Instance Migration page, select the Export Migration Plan pim export icon icon on the row of the migration plan you want to execute. The Export Migration Plan window opens.
  4. Review and click Export.

6.5. Executing a migration plan

You can execute the migration plan in the process instance migration (PIM) service web UI.

Prerequisites

  • You have defined processes in a backup-ed Red Hat Process Automation Manager development environment.
  • The PIM service is running.

Procedure

  1. Enter http://localhost:8080 in a web browser.
  2. Log in to the PIM service.
  3. On the Process Instance Migration page, select the Execute Migration Plan pim execute icon icon on the row of the migration plan you want to execute. The Execute Migration Plan Wizard window opens.
  4. From the migration plan table, select the check box on the row of each running process instance you want to migrate, and click Next.
  5. In the Callback URL field, enter the callback URL.
  6. To the right of Run migration, perform one of the following tasks:

    • To execute the migration immediately, select Now.
    • To schedule the migration, select Schedule and in the text field, enter the date and time, for example 06/20/2019 10:00 PM.
  7. Click Next.
  8. Optional: To export as a JSON file, click Export.
  9. Click Execute Plan.
  10. Optional: To export as a JSON file, click Export.
  11. Check the response and click Close.

6.6. Deleting a migration plan

You can delete a migration plan in the process instance migration (PIM) service web UI.

Prerequisites

  • You have defined processes in a backup-ed Red Hat Process Automation Manager development environment.
  • The PIM service is running.

Procedure

  1. Enter http://localhost:8080 in a web browser.
  2. Log in to the PIM service.
  3. On the Process Instance Migration page, select the Delete pim delete icon icon on the row of the migration plan you want to delete. The Delete Migration Plan window opens.
  4. Click Delete to confirm deletion.