Question

How can we move tokens using REST APIs as part of production troubleshooting?

Answer 1

Token moves are the surgical way to unstick or reroute a running instance in production; the REST API does it with two calls (find the token, move it):

# 1. where is the instance? tokens + steps
GET /rest/bpm/wle/v1/process/2072.1234?parts=executionTree,diagram
# executionTree.root.children -> [{ "tokenId": "6", "name": "Wait for approval", "flowObjectId": "8d1f...", "createdTaskIDs": ["2078.99"] }]
# diagram.step -> [{ "ID": "8d1f...", "name": "Wait for approval", "type": "intermediateEvent" }, { "ID": "c2a0...", "name": "Ship order", "type": "activity" }, ...]

# 2. move token 6 to "Ship order" and resume the instance
POST /rest/bpm/wle/v1/process/2072.1234?action=moveToken&tokenId=6&target=c2a0...&resume=true&parts=none
BPMCSRFToken: <token>          (BAW 20+ / CP4BA; obtain with POST /rest/bpm/wle/v1/system/login)

# variants
POST ...?action=deleteToken&tokenId=6&resume=true          # remove a token (e.g. a duplicate parallel branch)
PUT  /rest/bpm/wle/v1/process/2072.1234?action=suspend        # suspend first when several changes are needed, resume after
PUT  /rest/bpm/wle/v1/process/2072.1234?action=retry          # for Failed instances: retry the failed step instead of moving

Rules for production: (1) suspend the instance, move, set variables if the target step needs data (PUT /process/{piid}/variables), resume; (2) the open task of the old position is closed by the engine when its token leaves (the user sees it disappear) - tell them; (3) moving into a sub-process or a parallel branch needs the target node inside the right scope - the diagram's step list includes nested steps; moving into a multi-instance activity is not supported; (4) record every move (instance, from, to, reason, who) - the instance's comments API is a good place (the instance comment action of the Process REST API); (5) the same operations exist in Process Admin > Process Inspector (Move / Delete token) and in the JavaScript API (TWProcessInstance.moveToken), and on CP4BA through the same classic REST resource. Operations tooling built on this (a "Tokens" dashboard) pays for itself quickly.

References

• Process REST API - process resource (executionTree, diagram, moveToken, deleteToken, retry)
• BPMCSRFToken