Manage orphaned tokens after In-flight Instance Migration

There are two ways to manage orphaned tokens in IBM Business Process Manager Editions,

• Managing orphaned tokens with a policy file
• Managing tokens using the REST API Client and Process Inspector

Procedure to managing orphaned tokens with a policy file,

1. Generate a policy file using the wsadmin command. Use this XML file during the migration of active process instances. The wsadmincommand compares two snapshots and produces an XML file listing all the steps in the BPD where orphaned tokens could potentially occur. The command generates an XML representation of all possible locations of orphan tokens in a policy file.
2. Edit the policy file using a text editor.
   1. Go through the list of potential orphaned tokens and decide whether each token should be moved or deleted. By default, a delete action is specified for each token. You can change delete to move.
   2. When you are moving a potential orphaned token, you need to specify the target activity using the activity acronym. In Process Designer, select the target activity to which you want to move the orphaned token. From the Properties view for that activity, copy its system ID (which has a value like bpdid:b999d6be478ef107:21bb67e6:134387269e4:-7ff4) to your clipboard. The ID is case sensitive.
   3. Add a move instruction to the policy file in place of the delete instruction that is there by default. Paste the token ID into the instruction. Here is an example of a simple move instruction:

      <process bpdId="27d4fbbc-0175-4201-80d1-132100aca191" name="Top-level only">
          <step id="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7fe0" name="B">
            <move targetStepId="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7ff4" name="A"/>
          </step>
      </process>

      The policy file will not let you move a token to an invalid location. See Managing orphaned tokens for some general advice about moving potential orphaned tokens.
3. Optional: You can add an attribute to suspend the process for any activity in the policy file. That attribute suspends the process instance after a token has been deleted or moved so you can edit the data before resuming the instance. To use the suspendProcess option, set the attribute to "true".

   <move targetStepId="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7f72" name="E1" suspendProcess="true"/>

   The attribute suspendProcess="true" applies only to active instances. Inactive instances are not affected by the attribute. If an instance is already suspended, after migration using the orphaned token policy file it remains suspended.
4. From the Process Admin Console, select Installed Apps.
5. From the list of snapshots, select the one to which you are migrating data.
6. In the Migrate Inflight Data from Snapshot window, select a snapshot to migrate from, then browse to the location of the policy file and click Migrate.
7. Look at the result in the Process Inspector to ensure that all orphaned tokens have been deleted or moved or to adjust any data values after migration.

Procedure to managing tokens using the REST API Client and Process Inspector,

To move a token to a new activity, complete the following steps:

1. Use the Process Inspector in the Process Admin Console to inspect the currently running process instances and select the instance containing orphaned tokens that you want to move. Make a note of the process instance ID as well as the ID of the orphaned token, which will be shown in the execution call stack.
2. Use Process Designer to identify the system ID of the activity where you want to move the orphaned token (the target activity). Record the complete value of that activity, including the "bpdid:" prefix.
3. To move the token to a activity, in the REST API client, enter the following: :

   /rest/bpm/wle/v1/process/instance_ID?action=moveToken&tokenId=
   token_ID &target=target_step_ID[&resume=resume_value]

   The following identifies the parameters of the API:
   

   • instance_ID - the instance ID number of the process instance containing tokens to be moved
   • action - states the action to be taken (moveToken)
   • token_ID - the token ID number of the token you need to move
   • target_step_ID - the ID number of the new process step that you are moving the token to
   • resume_value - the action used to resume the instance after moving the token (set to "true" or "false"); the default value is "true"
4. Press Enter to complete the move.
5. The system returns one of the following response codes:

• 200 = Success
• 405 = Not Authorized
• 400 = Server Error (unable to move token)

Deleting tokens using the REST API client

1. Use the Process Inspector in the Process Admin Console to inspect the currently running process instances and select the instance containing orphaned tokens that you want to delete. Make a note of the process instance ID as well as the ID of the orphaned token, which will be shown in the execution call stack.
2. To delete the token, in the REST API client, enter the following: :

   /rest/bpm/wle/v1/process/instance_ID?action=deleteToken&tokenId=
   token_ID[&resume=resume_value]

   The following identifies the parameters of the API:
   

   • instance_ID - the instance ID number of the process instance containing tokens to be moved
   • action - states the action to be taken (deleteToken)
   • token_ID - the token ID number of the token you need to delete
   • resume_value - the action used to resume the instance after deleting the token (set to "true" or "false"); the default value is "true"
3. Press Enter to complete the delete action.
4. On the Inspector tab of Process Designer, verify that the orphan token is now deleted.

To delete a token from a process instance, complete the following steps:

1. Open the process instance in Process Inspector.
2. In the Actions panel, click Delete Orphaned Tokens.