Token Simulation
Introduction
Token simulation animates a process or case model directly in the editor, so you can watch how work moves through it before anything is published. A token is a marker for one thread of execution: in a process it travels along the sequence flows from element to element, and in a case it is expressed as the lifecycle state of each plan item. Where the model asks a question the diagram alone cannot answer (which path does this gateway take, is this condition met, how many instances does this loop run), the simulation asks you.
The simulation runs entirely in your browser. Nothing is deployed, no process or case instance is created, no service is called and no data is stored. It is therefore safe to run at any time, on any model, including models you cannot edit: a published revision, a model in a workspace you only have read access to, or a model someone else has locked.
Token simulation complements the other two ways of checking a model:
| What it answers | |
|---|---|
| Model validation | Is the model correctly configured? (static checks, no execution) |
| Token simulation | Where can work flow, and what does the model look like while it runs? |
| Model testing | Does the model produce the expected result? (asserted, executed on a runtime) |
Because the simulation has no process or case variables, it shows you reachability, not decision logic. See What token simulation does not do. To assert real behaviour against expected values, use model testing.
Starting a simulation
Open a process (BPMN) or case (CMMN) model and click Token simulation in the editor toolbar. Click the same button again to leave simulation mode.
While simulation mode is on, the model cannot be changed: the palette is hidden and editing, undo and redo, auto layout, the data contract, model variables and the Tests panel are unavailable. The button itself is never disabled, so a model that is read-only can still be simulated.
Leaving simulation mode discards everything the session held: the run, the breakpoints you set and the instance counts you chose. Reset inside the session is different: it clears the run but keeps that setup, so you can immediately run the same scenario again.
The simulation controls
A control panel sits at the bottom of the canvas for the whole session.
| Control | What it does |
|---|---|
| Play / Pause | For a case, Play starts the case. For a process, it pauses and resumes a run that was started from a start event. |
| Reset | Clears the run. Breakpoints, instance counts and repetition counts are kept. |
| Speed | How fast the animation runs, from 1 to 10 (5 by default). Speed also sets how long a token dwells at an element: about two seconds at speed 1, a fifth of a second at speed 10. |
| Status | For a process, the number of live tokens. For a case, how many plan items are active, available and completed. |
| Execution Log | Opens and closes the execution log. |
| Step through the run | Opens the step-replay view. Available once at least one step has been recorded. |
| Stop at waiting tasks (process) / Stop at manual tasks (case) | Whether the run stops at steps that would wait for a person or an external system, or drives through them by itself. Off by default. |
Simulating a process model
Starting tokens
Before the run starts, every top-level start event shows a green play control and the canvas shows Click a start event to begin. Click a start event to create the first token. If the model has no start event, the canvas says so instead.
The controls stay available while the run is going, so clicking a start event again adds another token. Several tokens can be in flight at once: each one has its own colour, which its forked children inherit, so you can follow a single branch through a busy diagram.
Reading the diagram
A token resting at an element is drawn as a coin, a coloured disc with a count. When one element holds more than one token, for example each instance of a multi-instance activity, the coins are drawn as a single stack showing the total. A token that is moving is animated along the sequence flow it is travelling on.
The ring around a coin tells you why the token is not moving:
| Ring | Meaning |
|---|---|
| No ring (white) | Running |
| Amber | Waiting for something: an event, a trigger, or a path choice |
| Red | Held at a breakpoint |
| Faded coin | The token has finished |
The diagram itself is not recoloured as the run progresses: the coins and the execution log are what tell you where the tokens have been. When you replay a real instance in Flowable Work, the history diagram keeps its usual completed and active colouring underneath the tokens.
Choosing a path at a gateway
When a token arrives at a diverging exclusive or inclusive gateway, it parks and a popup appears above the gateway listing every outgoing sequence flow. Hovering a row highlights that flow on the diagram, so you can see where it leads before committing; the paths you have selected are highlighted as well. The popup can be dragged out of the way.
- An exclusive gateway offers the flows as options with the first one preselected. Confirming sends the token down that one flow.
- An inclusive gateway offers them as checkboxes with none selected, and Confirm stays disabled until you tick at least one. The token forks down every flow you ticked.
Exclusive gateway: radio options, exactly one path. Here the token takes the Yes flow, highlighted in blue.
Inclusive gateway: checkboxes, one or more paths. Here Task A and Task C are ticked, so the token forks down both (highlighted in blue) and Confirm shows the count.
Each gateway shows one popup at a time, for the token that arrived first; the next token's popup opens as soon as you have resolved the current one. Several different gateways can be waiting at once, and each popup carries the colour of the token that is deciding.
Sequence-flow conditions are not evaluated. Your choice is the decision. An event-based gateway works differently: the token waits there, and trigger controls appear on the catching events it leads to, so you pick which event arrives.
Waiting steps
Some elements wait for something outside the process: user and form tasks, receive tasks, receive-event and send-and-receive-event tasks, external worker tasks and call activities.
With Stop at waiting tasks off (the default), a token pauses briefly at these elements and then continues on its own, which gives you an uninterrupted overview of the flow.
With the toggle on, the token parks there with an amber ring and a green Complete task control appears on the element. Clicking it advances the token, which lets you drive the model step by step and decide the order in which parallel branches proceed.
Events are not governed by that toggle: a catching intermediate event (a message, signal, timer, registry or variable-listener event) always waits, and shows Trigger event when a token reaches it. Boundary events show Trigger boundary event while their host activity holds a token, including a token somewhere inside a sub-process the boundary event is attached to. Triggering an interrupting boundary event cancels its host and sends the token down the boundary event's own flow; a non-interrupting one leaves the host running.
Multi-instance elements
A multi-instance activity shows a small − / + stepper below it. Use it to choose how many tokens are spawned for a parallel multi-instance element, or how many iterations a sequential one runs.
The starting value comes from the model's loop cardinality when it has one, or from a default. At most 10 instances are simulated; if the model asks for more, the run tells you once and names the elements it capped.
While a sequential multi-instance task runs, a coin on its input side counts down the iterations still to come as the count on its output side climbs.
Breakpoints
Hover an element and click the breakpoint control in its top-left corner to set a breakpoint; a red dot marks it. When a token reaches a breakpointed element it stops there with a red ring, and a play control on the element resumes it.
Breakpoints survive Reset, so they are the natural way to re-run a scenario and stop at the same place each time. They can be set before the run starts. Elements that are already waiting steps cannot be breakpointed while Stop at waiting tasks is on. Their Complete task control already gives you the same control over them.
Sub-processes, boundary events and terminate end events
Tokens enter embedded and event sub-processes and are drawn inside them; each sub-process gets its own execution scope, so terminating it removes the tokens it contains. Terminate end events do the same for the whole process. Parallel and inclusive gateways fork and join, and a token that can never be joined is reported in the log as stuck, possible unbalanced join, usually the sign of a converging gateway that can never receive all the branches it waits for.
An interrupting boundary event on a sub-process (or activity) can be triggered while a token is inside it: doing so cancels the whole sub-process scope (removing every token it contains) and sends a single token down the boundary event's own flow.
Simulating a case model
Starting the case
A case has no start event: press Play in the control panel to start it, as the canvas prompts. The case plan model becomes active and the plan items follow their lifecycle from there.
Plan item states
Instead of coins, each plan item is drawn with a coloured outline ring showing its lifecycle state. The control panel counts how many items are active, available and completed.
| Ring | Plan item state |
|---|---|
| Amber | Available or enabled: ready, but not running |
| Green | Active |
| Blue | Completed |
| Grey | Terminated |
| Dark grey | Disabled |
| Red | Held at a breakpoint |
Breakpoints work as they do for processes: set them on eligible plan items, and resume with the play control that appears on the item.
Manually activated items
A plan item with manual activation becomes enabled rather than active, exactly as it would at runtime, and shows a start control. Click it to activate the item.
Two ways to say "not this one":
- Disable (don't run this item) on an enabled item disables it, as an end user would.
- Disable before running (won't run) marks an item you have not reached yet. When the case would enable it, it goes straight to disabled instead. Click again to re-enable it.
Disabling items is how you check that a stage or case still completes when optional work is skipped, and that it correctly does not complete when required work is.
Repeating items
A plan item with a repetition rule shows a − / + stepper below it, like a multi-instance activity, setting how many times it runs in the simulation. The starting value comes from the model.
Criteria and conditions
Entry and exit criteria fire when the parts they depend on are satisfied: completing the source item fires the entry criterion of the next, and an exit criterion terminates its item, cascading through a stage or the whole case where that applies.
A criterion whose sentry also carries a condition cannot be evaluated, because the simulation has no case variables. When such a criterion is otherwise satisfied, the simulation asks you: Condition met — fire criterion, or Condition not met — skip.
Event listeners and milestones
An active user event listener shows a trigger control, so you can fire it whenever you want. Timer event listeners occur by themselves after a short delay rather than at a real date or duration, and can also be triggered by hand.
Milestones occur through their entry criterion, and stage and case auto-completion follows the model's auto-complete and required settings.
Reactivating a completed case
Once the case plan model has completed or terminated, a reactivate event listener in the model offers Reactivate case.
Reactivation depends on rules whose conditions the simulation cannot evaluate, so it opens a dialog listing every element that carries reactivation rules, together with the rules from the listener itself. Each element has up to three rules (Direct activation, Ignore and Default), evaluated in that fixed order; the first one that holds decides the outcome. Tick the condition you want treated as met for each element; the first match wins, in the order shown.
| Rule | Outcome |
|---|---|
| Direct activation | The element is activated immediately when the case comes back |
| Ignore | The element is excluded from the reactivated case |
| Default | The element starts fresh, as it would in a new case |
For how these rules and their condition expressions work on a real runtime, see Reactivate event listener.
Confirming reactivates the case and the run continues from there.
The execution log
The Execution Log button opens a floating window listing every step of the run, newest at the bottom. Each row shows the time elapsed since the run started, and what happened: a token entering or leaving an element, a fork or a join, a plan item becoming available or active, a completion, a termination, an event trigger, a pause. For a process, a coloured dot identifies which token produced the row, using the same colour as its coin on the diagram.
The log doubles as the index for stepping through the run: clicking a row jumps the diagram to that step. The window can be moved and resized.
A session records its first 10,000 steps. A run that goes beyond that (in practice only a looping model) keeps running, and the log says that step replay covers the recorded part only.
Stepping through a run
Step through the run pauses the run and reconstructs the state of the diagram at any recorded step, so you can go back over what happened at your own pace.
The controls change while the view is open: previous step, next step, a slider to move freely through the run, and the position as Step 3 / 47. Rows after the current step are dimmed in the log as "not yet reached", and clicking any row jumps straight to it.
The view is read-only: the controls that would act on the live run are hidden, and a token that was animating along a flow is drawn resting instead. Back to live returns to the run exactly where it was paused.
Replaying a run from the Work history tab
The same visualisation is available in Flowable Work to replay what a real work item actually did. This lives on the work item's History tab, whose Diagram view shows the process or case diagram of the instance. See History in the Work user guide for the tab as a whole. Everything below is the replay control on that diagram.
Open the work item, go to History → Diagram, and click Replay execution next to the zoom controls. Stop replay returns to the ordinary diagram.
The control appears for process and case history diagrams that have something to replay: an instance with completed activities, or one still parked on its first step. The replay follows the recorded history rather than asking you for decisions: gateway paths come from the path the instance really took, and tokens stop at the activities the instance is still waiting on. The execution log and the step-replay view work exactly as they do in the editor, so you can step through a finished instance one recorded step at a time.
If the model has changed since the instance ran and the recorded history no longer matches the diagram, the replay says so rather than showing a misleading run.
What token simulation does not do
Token simulation is a modelling aid, not an engine. It is very good at showing whether work can reach an element, where a flow dead-ends, whether a join can ever complete, which items a stage waits for, and what a model looks like while it runs. It deliberately does not reproduce runtime behaviour that depends on data, and the differences below are the ones worth knowing about.
| Area | In the simulation |
|---|---|
| Variables and expressions | There are none. Nothing is evaluated. |
| Sequence-flow conditions | Not read: you choose the path at the gateway. A condition that can never be true, or a missing default flow, still simulates fine. |
| Sentry conditions and rule conditions (case) | Not read: you state whether the condition holds. |
| Multi-instance and repetition counts | Taken from loop cardinality or a default; collections and completion conditions are not read. A parallel or sequential multi-instance loop runs the full count (at most 10). Case repetition gated by an entry criterion instead runs once each time that criterion fires. |
| Call activities, process tasks and case tasks | Treated as a single waiting step. The called process or case is not loaded or executed, and in/out mappings are not modelled. |
| Forms, service calls, decision tables, scripts | Not executed. A task that would call out simply completes. |
| Timers | A timer catch or boundary event in a process waits until you trigger it; a timer event listener in a case occurs by itself after a short delay. Real dates, durations and cron expressions are not honoured. |
| Compensation | A compensation boundary event can be triggered while its activity is running, which shows that the handler is reachable. It does not model compensation of an activity that has already completed. |
| Transaction settings | Asynchronous continuations (async, asyncLeave) and synchronous event sending change when an activity runs, not where the token goes, so they make no difference to the simulation. |
| Case plan item states | Approximated to seven states. Available, enabled, active, completed, terminated and disabled are shown (enabled is distinguished when replaying a real instance too), but failed, suspended and asynchronously-active have no representation. |
| Discretionary items and case-file-item sentries | Not simulated. |
For checks that must hold as the model evolves (asserting variables, outcomes and paths, and running them repeatedly), use Model testing and Flowable Inspect.