BPMCheckOrphanTokens - Care and Feeding Guide

Follow

 

The wsadmin command "BPMCheckOrphanTokens" is used to determine whether there is a likelihood of tokens being orphaned when migrating from one snapshot to another on a runtime Process Server.


It does currently appear to have some undocumented limitations and IBM's L3 team is investigating.

It is therefore recommended that all precautions possible are taken before a migration in a live Production environment.

Invoke the wsadmin command in the appropriate profile/bin directory.

From a command line prompt, navigate to the .../bin directory for the Process Center profile. Do not run this in the DMGR profile.
e.g:

C:\IBM\BPM\v8.5\profiles\Node1Profile\bin>

 

Connect wsadmin with the appropriate parameters

C:\IBM\BPM\v8.5\profiles\Node1Profile\bin>wsadmin -host 127.0.0.1 -port 8880

If successful you should get something like this:

WASX7209I: Connected to process "SingleClusterMember1" on node Node1 using SOAP
connector; The type of process is: ManagedProcess
WASX7029I: For help, enter: "$Help help"

If you get this message:

WASX7209I: Connected to process "dmgr" on node Dmgr using SOAP connector; The
type of process is: DeploymentManager

the SOAP port you supplied is not correct for the ManagedProcess and when you attempt to run the BPMCheckOrphanTokens command you will get this failure:

java.lang.RuntimeException: java.lang.RuntimeException: This command should be executed for a node where IBM BPM teamworks application is running.,

 

Make a note ot the Process Application Acronym, the Source snapshot name and Target snapshot names and decide on your output file location.

The command line sequence is Acronym, Source, Target, Output file:

wsadmin>$AdminTask BPMCheckOrphanTokens {-processAppAcronym HSS -sourceSnapshotName "HSB" -targetSnapshotName "Stuart2" -outputFile C:\TokenPolicyFile2.xml }

The confirmation output will be:

Process Application Acroynm : HSS
Source Snapshot Name : HSB
Target Snapshot Name : Stuart2
Output File : C:\TokenPolicyFile2.xml

 

Examine the policy.xml file and modify if necessary before the migration

If there are no conflicts detected, the policy file will look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<orphanTokenPolicy>
<processApplication acronym="HSS" id="2066.9ab0d0c6-d92c-4355-9ed5-d8a05acdc4b0" name="Hiring Sample">
<sourceSnapshot acronym="S" id="2064.512245c3-2ed2-4998-ae45-6ba3bbad2746" name="Stuart"/>
<targetSnapshot acronym="S2" id="2064.99e7ecd8-0eb7-44ec-ad76-631964a4f3df" name="Stuart2"/>
</processApplication>
</orphanTokenPolicy>

If the tool believes there may be tokens at risk, additional information will be present for each suspect:

<?xml version="1.0" encoding="UTF-8"?>
<orphanTokenPolicy>
<processApplication acronym="HSS" id="2066.9ab0d0c6-d92c-4355-9ed5-d8a05acdc4b0" name="Hiring Sample">
<sourceSnapshot acronym="HSB" id="2064.865b2d5a-a3a1-48df-bd0e-24bbbc7589d5" name="HSB"/>
<targetSnapshot acronym="S99" id="2064.e8c49165-191d-436f-ae0a-ded2037162d7" name="Stuart99"/>
<process bpdId="25.c904b3b1-afc1-4698-bf5a-a20892c20275" name="Standard HR Open New Position">
<step id="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67c6" name=" Approve or reject requisition">
<delete suspendProcess="false"/>
</step>
</process>
</processApplication>
</orphanTokenPolicy>

Note that the default policy action is delete.

 

 

Edit policy action for each suspect token

    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 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:
    
    Before:
    
<process bpdId="25.c904b3b1-afc1-4698-bf5a-a20892c20275" name="Standard HR Open New Position">
<step id="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67c6" name=" Approve or reject requisition">
<delete suspendProcess="false"/>
</step>

    
    After:

<process bpdId="25.c904b3b1-afc1-4698-bf5a-a20892c20275" name="Standard HR Open New Position">
<step id="bpdid:5cd499bd441308ca:37d49876:12e27ee26e3:-67c6" name=" Approve or reject requisition">
<move targetStepId="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7ff4" name="A"/>
</step>

The policy file will not let you move a token to an invalid location.

 

 

Optional parameters

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.

 

Using your policy file

Once you have your policy file, amended as required, you then attach it to the Migrate dialog so that active instances can be dealt with in the way you defined. Your policy file will also be validated at this point.

 

 

When your instances complete migration, if all is well you should see a confirmation dialog something like this:

 

Have more questions? Submit a request

Comments

Powered by Zendesk