Last week we released a new version the ProcessMaker I/O workflow engine API which enhances the ProcessMaker I/O by opening up an additional endpoint to the API to let users work with process tokens. Let’s look at how these process tokens work.
The findTokens API Endpoint
The ProcessMaker I/O engine creates a process token whenever a process instance starts. Tokens are used to manage the lifecycle of an instance. You can think of the token flow as the heartbeat of the engine.
The new API endpoint uses the GET method and looks as follows:
https://docs.api.processmaker.io/#operation/findTokens
How the Process Tokens Concept Works
To use this endpoint, you are going to be inputting a process ID and an instance ID. This is because process tokens are specific to each instance in a process.
But what is a process token?
Process Tokens essentially control the very concept of the “workflow” in a workflow engine. It is not possible to run the engine without tokens. Whenever the engine needs to process something, it issues tokens to compute what will happen in the next task of the workflow. To better understand token flow, imagine a chessboard. On a chessboard after each opponent has a turn, there is a unique configuration of the pieces on the board. Based on the configuration of the pieces on the board, we know all the possible next moves.
Token flow works the same way. Look at the image below. At the start event, we know that the only possible token path is the sequence flow out of the start event. This is represented by “T1” in the sequence flow. Once the token reaches the first task, we know that there is still only one path outward from that task (still “T1”). However, when the token reaches the parallel gateway, there are two paths forward. So, at this gateway, something interesting happens. The initial token “T1” dies and gets exchanged for a 2 new tokens (T2 and T3). Since these 2 tokens are flowing out from the same parallel gateway, they will share the same token key. These tokens then die at the Parallel join and a fourth token is born – “T4.”
What you can do with Process Token Flow
By providing access to the token flow, we allow a process administrator to see the positions of each process in the engine at a given moment in time. If you are a developer adding the ProcessMaker I/O API to your application, you can now add interfaces, indicators, and views which will show users or admins to do and see the following:
- Find the place and object where a running instance is paused.
- Calculate how many tokens are in an instance.
- Detect objects that have a large number of tokens waiting for an action in order to continue the process. For example, a user approval task might have numerous pending tokens indicating a user that is not processing cases fast enough. So, based on this token count we might want to create indicators to prompt things like escalations depending on the type of software we are building based on ProcessMaker I/O.
- Develop statistics and reporting related to hot zones and bottlenecks in the process.
- Identify the current object where a token is at any given time.
Exploring further the Tokens Endpoint
Tokens are created by either hidden or explicit start events that kick off a new process instance. A token dies when it reaches the end event in a process. A token’s movement can be traced through the full sequence flow of a process as it passes through gateways, activities, and events. In addition, tokens can also be created and killed by the different flow elements. As we saw above, a parallel gateway produces a token for each of the Sequence Flows that flow out of the parallel gateway.
Note – a token does not occur with a Message Flow. The message flow is drawn with a dashed line in BPMN. It is not the same as a sequence flow. Tokens do not apply to Message Flows. It only follows the sequence flow of a process. In other words, sending a message from a message event does not generate or push a token forward. However, if a message event reaches another start event, then a token will be created with the new start event.
As always, if you have any questions or feedback, you can email us or ask your questions on our public portal.
