Contents


Using the REST API Tester to manage orphan tokens in IBM Business Process Manager V8

Comments

Making changes in the IBM Business Process Manager (BPM) V8 to a business process definition is common practice. There may be business logic changes between two different snapshot versions due to the incorporation of new rules or some other reason. When changes are made to a snapshot of a business process definition (BPD), which has been deployed to a runtime IBM BPM Process Server, there could be instances of an older snapshot that is still running. These instances could be left running or they may need to be migrated to the newer version of the snapshot. The purpose of this tutorial is to show how to migrate instances to a newer and changed version when the changes have left the user with orphaned instances. An orphan instance refers to an older instance that is not in a manageable state and needs to be migrated to the correct step in the new version of the BPD.

As stated above, this tutorial will show how an orphan token can arise and how to deal with the orphan token. We will show this with two different approaches:

  • Use the IBM BPM REST API Tester to move an orphan token to a valid step in the newly deployed snapshot.
  • Run the BPMCheckOrphanTokens command to identify where orphan tokens may arise in the BPD and how to author a policy file to migrate the orphan tokens.

Importing the Hiring Sample application

This section will simulate the creation of an orphan token. We will then show how to move this orphaned token to a valid step in the BPD. Let us start with the Hiring Sample application, which is provided with IBM BPM (see Figure 1).

  1. Import the sample application from the following path: install_root\BPM\Lombardi\imports\standard_hiring_sample.twx.
    Figure 1. Standard Hiring Sample
    Standard Hiring Sample
    Standard Hiring Sample
  2. Deploy the Standard Hiring Sample application to the runtime IBM BPM Process Server. This snapshot is named "Standard Hiring Sample v801". Once the snapshot has deployed, you can see it as installed in your IBM BPM Process Center. Let us now start a few instances of this deployed version and switch to the Process Inspector View to note the instance numbers. The instance numbers are randomly generated and will not match the instance numbers we have shown below. Figure 2 shows the instance numbers that were generated.
    Figure 2. Instances of the Standard Hiring Sample
    Instances of                     the Standard Hiring Sample
    Instances of the Standard Hiring Sample

    The two instances above are now left in the current state of navigation. Note that the token is currently at the "Submit Job Requisition" step. Let us assume that after these instances have been started, a change is made to the BPD, which results in the deletion of the "Submit Job Requisition" step without taking note that this could impact the running instances. Such a scenario results in orphan tokens once the older instances are migrated to the new version. This happens because the step, at which these instances were waiting, is no longer a valid step in the newer version of the snapshot.

  3. Let us simulate the orphan token creation by deleting the "Submit Job Requisition" step so that the BPD now looks like Figure 3.
    Figure 3. Removed Submit Job Requisition step
    Removed Submit Job Requisition                     step
    Removed Submit Job Requisition step

Installing the application to runtime Process Server

  1. Install this new snapshot to a runtime IBM BPM Process Server. You will be presented with a dialog box to handle the running instances that belong to the previously installed snapshot, Standard Hiring Sample v801. Select to migrate the instances to the newly installed snapshot. The options are to delete, leave, or migrate the existing instances. Select the option to Migrate the older instances to the new instance as shown in Figure 4.
    Figure 4. Migrate running instances
    Migrate running instances
    Migrate running instances
  2. Now, let's go back to the Process Inspector and look at the state of the instances that we just migrated. Figure 5 shows the instances.
    Figure 5. Instances in Process Inspector
    Instances in Process Inspector
    Instances in Process Inspector
  3. If you click on the instance IDs 26275 and 26274 (instance IDs corresponding to your system), notice that the process inspector shows the state of these two instances as "unknown". Since the step that these two instances were on is no longer present in the new business process diagram, the instances are in an unknown orphaned state.

To get these two instances to a manageable and known state, we can move them to a step in the BPD, which is valid. Let's see how we can move the instances to a valid step using the REST API Tester.

Using the REST API Tester to manage tokens

The REST API Tester is a stand-alone web application that you can use to test BPM-related REST resources. These APIs can also be called directly from a web browser by passing the correct parameters and following the syntax for the API. For the purpose of this tutorial, we will use the IBM provided REST API Tester to manage our orphan tokens.

  1. Navigate to the REST API Tester using the following URL:
    http://machinename:portnumber/bpmrest-ui/login.jsp

    Noting the instances that you need to migrate, let's first get the relevant data.

  2. Typing in the instance ID with an unknown state in the API CurrentState, you can see some details on the instance. Navigate to the CurrentState API in the REST API Tester as shown in Figure 6.
    Figure 6. REST API Tester
    REST API Tester
    REST API Tester
  3. Now let's move this instance to the "Approve" or "Reject Requisition" step in the snapshot. The snapshot you are working with is the newly deployed version. Since you need to move the stuck tokens to the Approve or Reject Requisition step, there are some parameters you need to provide to the moveToken API.

    In order to move a token to a step, the following parameters must be passed to the API in the REST API Tester:

    • instance_ID: The instance ID number of the process instance.
    • token_ID: The token ID number of the token to be moved.
    • target_step_ID: The ID number of the new process step in the target BPD.

    You can retrieve the first two parameters from the Process Inspector by looking at the instance details.

  4. To retrieve the target_step_ID to which the token will be moved, open the Process Designer and look in the properties for the Approve or Reject Requisitionstep. The target step ID is the ID that is shown in the bottom pane under the System ID as shown in Figure 7.
    Figure 7. Properties of Approve or Reject Requisition in Process Designer
    Properties of Approve or Reject Requisition in Process Designer
    Properties of Approve or Reject Requisition in Process Designer
  5. The token ID is the token number that is also shown in the Process Inspector. In this case, the token ID is 2 as shown in Figure 2.
  6. Let's call the REST API with all the parameters that you have now. On the IBM BPM REST API Tester, enter in the parameters as shown in Figure 8.
    Figure 8. Move the Token API in the REST API Tester
    Move the Token API in the REST API Tester
    Move the Token API in the REST API Tester
  7. After the execution of the above call, you see the result of the call on the right panel of the Tester as shown in Figure 9.
    Figure 9. Results of execution from the REST API Tester
    Results of execution from the REST API Tester
    Results of execution from the REST API Tester
  8. Navigating back to the IBM BPM Process Designer and in the Inspector view, if you refresh the instances, you can see that the token has now advanced and is at the step where you moved it (see Figure 10).
    Figure 10. Moved token in Process Designer
    Moved token in Process Designer
    Moved token in Process Designer

Using the BPMCheckOrphanTokens command

You can use the wsadmin command, BPMCheckOrphanTokens, to detect the possibility of any orphan tokens arising by comparing the two snapshots. This helps with the snapshot migration. IBM BPM users can avert the occurrence of orphan tokens.

This utility detects the possibility of orphaned tokens by comparing one snapshot with another and generating an output policy file. This file allows you to remedy orphaned tokens. After the policy file is generated, you can modify the file for one of the three options below to deal with orphan tokens:

  • Delete the token if it is no longer required in the new snapshot (default action).
  • Move the token to another step in the process.
  • Suspend the process so that the process instance data can be manipulated using the Process Inspector.

The next section makes all this clear as you begin the migration process again.

Migrating instances using a policy file

Taking the same Hiring Sample application example, you have removed the Approve or Reject Job Requisition step. This snapshot becomes the new version, which you will deploy to the runtime Process Server.

First, you will start a few instances of the older snapshot (Standard Hiring Sample v801). Once that is done in the Process Center Console, select to install the new version named "TestHiring2" and choose to leave the running instances. The running instances will be handled later with the policy file. Here are the steps that elaborate the above:

  1. Create a new snapshot with the removed step.
  2. Start a few instances of this snapshot.
  3. Install the snapshot to the Runtime Process Server.

    Note the instance numbers of the instances that were started in the Process Inspector as shown in Figure 11.

    Figure 11. Instances in Process Inspector
    Instances in Process                     Inspector
    Instances in Process Inspector
  4. Let's install this snapshot to the runtime Process Server. When installing to the runtime Process Server, select the option to leave the running instances as shown in Figure 12.
    Figure 12. Leave the Running instances
    Leave the Running                     instances
    Leave the Running instances
  5. After completing the steps above, let us know look at any potential orphan tokens that have been created by running the BPMCheckOrphanTokens command.

    Refer to the IBM BPM Information Center to establish a connection to the IBM BPM Process Server and to use JACL to generate the output file.

  6. Run the BPMCheckOrphanTokens command from the command line with the following parameters:
    • Process Acronym
    • Source Snapshot Name
    • Target Snapshot Name
    • Path to an output file (will be created)

    This command generates the policy file HSS.xml in the location you specified, such as "C:\temp". Listing 1 shows how to specify the connection to the Process Server using JACL and then to execute the BPMCheckOrphanTokens command with the above parameters.

    Listing 1. BPMCheckOrphanTokens command
    wsadmin.bat -connType SOAP -lang jacl -user admin -password admin -port 8880 -host localhost

    Once inside the wsadmin command, execute the BPMCheckOrphanTokensCommand as follows:

    wsadmin>$AdminTask BPMCheckOrphanTokens {-processAppAcronym HSS
    -sourceSnapshotName "Standard Hiring Sample v801" -targetSnapshotName
    "SnapshotChange" -outputFile C:\temp\HSS.xml}
    Process Application Acroynm : HSS
    Source Snapshot Name : Standard Hiring Sample v801
    Target Snapshot Name : SnapshotChange
    Output File : C:\temp\HSS.xml
  7. Navigate to the HSS.xml file and open it. It will have the format similar to Listing 2.
    Listing 2. Output file from BPMCheckOrphanCommand
    <?xml version="1.0" encoding="UTF-8"?>
    <orphanTokenPolicy>
       <processApplication acronym="HSS" id="2066.9ab0d0c6-d92c-4355-9ed5-d8a05acdc4b0" name="Hiring Sample">
          <sourceSnapshot acronym="SHSV801" id="2064.112395df-d19c-489b-bf73-fced37b52035" name="Standard Hiring
                    Sample v801"/>
          <targetSnapshot acronym="TH2" id="2064.6fd301b0-c188-46b9-922c-65f61ef13b41" name="TestHiring2"/>
          <process bpdId="25.c904b3b1-afc1-4698-bf5a-a20892c20275" name="Standard HR Open New Position">
            <step id="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67db"
                    name="Submit job requisition">
              <delete suspendProcess="false"/>
            </step>
              </process>
          </processApplication>
    </orphanTokenPolicy>

The file has various pieces of information in it. The section beginning with <step id> shows places in the snapshot that are candidates for orphan tokens. This particular file indicates that there can be orphans at the Submit Job Requisition step.

<step id="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67db" name="Submit job requisition">

You will now use this policy file to migrate your orphan tokens.

Migrating snapshots in the Process Admin Console by specifying the policy file

In the HSS.xml output file, you need to decide what you want to do with orphan tokens at the Submit Job Requisition step. By default, any orphan tokens will be deleted as seen in the file. You can choose to move the orphans to a step in the Process Diagram.

  1. To do so, specify the target step ID (you saw this earlier using the REST API Tester) and change the Delete option to a Move option in the policy file. Retrieve targetStepID from the Process Designer and add the Move tag in place of the Delete tag.

    The changed file now looks like the one shown in Listing 3.

    Listing 3. Policy file
    <?xml version="1.0" encoding="UTF-8"?>
    <orphanTokenPolicy>
       <processApplication acronym="HSS" id="2066.9ab0d0c6-d92c-4355-9ed5-d8a05acdc4b0" name="Hiring
                    Sample">
         <sourceSnapshot acronym="SHSV801" id="2064.112395df-d19c-489b-bf73-fced37b52035" name="Standard Hiring
                    Sample v801"/>
         <targetSnapshot acronym="TH2" id="2064.6fd301b0-c188-46b9-922c-65f61ef13b41" name="TestHiring2"/>
         <process bpdId="25.c904b3b1-afc1-4698-bf5a-a20892c20275" name="Standard HR Open New Position">
          <step id="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67db" name="Submit job requisition">
             <move targetStepId="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67c6" 
               name=" Approve or reject requisition"/>
          </step>
         </process>
        </processApplication>
    </orphanTokenPolicy>
  2. Navigate to the Process Admin Console Snapshot that is the target snapshot for your migration. You will be presented with a dialog in which to specify the source snapshot and its instances as described in the next step.
  3. Navigate to the Process Admin Console for Process Server. As Figure 14 shows, the Process Admin Console presents you with a dialog when you select the snapshot to which you want to migrate the instances. In this particular case, you have selected the snapshot "TestHiring2" under Installed Apps. Select Standard Hiring Sample v801 as the source snapshot to migrate from. After making changes to the HSS.xml file, rename it to "Policy.xml" and specify that file as the policy file for orphan tokens as shown in Figure 13.
    Figure 13. Select source snapshot for migration
    Select source snapshot for                     migration
    Select source snapshot for migration
  4. Once the file has been validated successfully, the Migrate option will be available for selection. The results of the migration are shown in Figure 14.
    Figure 14. Process Instance Migration summary
    Process Instance Migration                     summary
    Process Instance Migration summary
  5. Let's go back to the Process Inspector and look at the instances to check their current state after migration. Figure 15 shows that the instances were migrated successfully and are now at the next step, which is "Approve or Reject Requisition".
    Figure 15. Migrated process instance
    Migrated process instance
    Migrated process instance

Conclusion

This tutorial showed how to manage orphan tokens. You can use a policy file to manage orphan tokens or the REST API to move the orphaned instances to a valid step in the business process definition. Checking a policy file to see where orphan tokens reside prior to migration is a prudent business choice before performing any migration. This can be accomplished by running the BPMcheckOrphanTokens command.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management
ArticleID=984709
ArticleTitle=Using the REST API Tester to manage orphan tokens in IBM Business Process Manager V8
publish-date=09302014