BPMCheckOrphanTokens command

Edit online
Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15
Use the BPMCheckOrphanTokens command to detect the possibility of orphaned tokens before installing a new snapshot and identify whether to delete or move each token.
This utility detects the possibility of orphaned tokens by comparing one snapshot with another. It allows you to identify what the system should do with each orphaned token that it encounters during migration. There are three options:
  • 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 process instance data can be manipulated using Process Inspector.

The BPMCheckOrphanTokens command checks activities only. These include user tasks, system tasks, decision tasks, subprocesses, event subprocesses, linked processes, and nodes.

The BPMCheckOrphanTokens command is run using the AdminTask object of the wsadmin scripting client.
Note: In an environment with multiple security domains configured, use the PALService MBean instead of this wsadmin command. See The Process Application LifeCycle (PAL) MBean.

Prerequisites

The following conditions must be met:
  • In a network deployment environment, you must run this command on the node containing the application cluster member that handles Workflow Server applications. Do not run this command from the deployment manager profile.
  • Run the command in the connected mode; that is, do not use the wsadmin -conntype none option.
  • To access the wsadmin command, the ID being used must have the WebSphere® Application Server deployer role. See Administrative roles External link opens a new window or tab for information about roles.
Attention: If you are using a SOAP connection, the command can take longer to complete than the specified SOAP timeout value. Although the command continues to run until it is finished, you might see the exception java.net.SocketTimeoutException: Read timed out. To prevent this exception, set a higher value for the com.ibm.SOAP.requestTimeout property in the profile_root/properties/soap.client.props file.

Location

Start the wsadmin scripting client from the install_root/bin directory.

Syntax

BPMCheckOrphanTokens 
-processAppAcronym process_application_acronym
-sourceSnapshotName snapshot_name | -sourceSnapshotAcronym snapshot_acronym
-targetSnapshotName snapshot_name | -targetSnapshotAcronym snapshot_acronym
-outputFile file_path
[-overwrite]

Parameters

-processAppAcronym process_application_acronym
A required parameter that identifies the process application that is to be installed. For example, the BillingDispute process application might have an acronym of BILLDISP.
Tip: If you do not know the acronym for a required parameter, use the BPMShowProcessApplication command to list the details of a process application, including acronyms.
-sourceSnapshotName snapshot_name
This parameter provides the snapshot name from which instances will be migrated (the old version). You must specify either this parameter or -sourceSnapshotAcronym.
-sourceSnapshotAcronym snapshot_acronym
This parameter identifies the snapshot from which instances will be migrated (the old version). You must specify either this parameter or -sourceSnapshotName.
-targetSnapshotName snapshot_name
This parameter provides the snapshot name to which instances will be migrated (the new version). You must specify either this parameter or -targetSnapshotAcronym.
-targetSnapshotAcronym snapshot_acronym
This parameter identifies the snapshot to which instances will be migrated (the new version). You must specify either this parameter or -targetSnapshotName.
-outputFile file_path
A required parameter that provides the file path to where the orphan token policy file will be generated and a name for that file.
-overwrite
An optional parameter that forces a replacement of an existing policy file with the new generated file.

Examples

The following example illustrates how to establish a SOAP connection to the IBM® Workflow Center server and then generate an orphaned token policy file for a process application with acronym OTA.

Important: In a network deployment environment, use the port configured for the application cluster member that runs the Workflow Server and Workflow Center applications. To determine the correct port number, see the administrative console Ports collection page (click Servers > Server Types > WebSphere application servers > server_name > Communications > Ports and find the value for SOAP_CONNECTOR_ADDRESS). 
wsadmin -conntype SOAP -port 8880 -host ProcessCenterServer01.mycompany.com 
-user admin ID -password administrator password -lang jython

wsadmin>AdminTask.BPMCheckOrphanTokens('[-processAppAcronym OTA -sourceSnapshotName 
"Version A" -targetSnapshotName "Version B" -outputFile C:\TokenPolicyFile_OTA.xml]')

The following example uses -sourceSnapshotAcronym and -targetSnapshotAcronym.

wsadmin -conntype SOAP -port 8880 -host ProcessCenterServer01.mycompany.com 
-user admin ID -password administrator password -lang jython

wsadmin>AdminTask.BPMCheckOrphanTokens('[-processAppAcronym OTA -sourceSnapshotAcronym
"Version A" -targetSnapshotAcronym "Version B" -outputFile C:\TokenPolicyFile_OTA.xml]')

The following example uses -sourceSnapshotAcronym and -targetSnapshotName.

wsadmin -conntype SOAP -port 8880 -host ProcessCenterServer01.mycompany.com 
-user admin ID -password administrator password -lang jython

wsadmin>AdminTask.BPMCheckOrphanTokens('[-processAppAcronym OTA -sourceSnapshotAcronym
"Version A" -targetSnapshotName "Version B" -outputFile C:\TokenPolicyFile_OTA.xml]')