bpmn-io / bpmn-js-token-simulation

A BPMN 2.0 specification compliant token simulator.

bpmn-js Token Simulation

A BPMN 2.0 specification compliant token simulator, built as a bpmn-js extension.

Try it on the classic booking example or checkout the full capability demo.

Installation

Install via npm.

npm install bpmn-js-token-simulation

Usage

Add as additional module to bpmn-js.

Modeler

import BpmnModeler from 'bpmn-js/lib/Modeler';
import TokenSimulationModule from 'bpmn-js-token-simulation';

const modeler = new BpmnModeler({
  container: '#canvas',
  additionalModules: [
    TokenSimulationModule
  ]
});

Viewer

import BpmnViewer from 'bpmn-js/lib/NavigatedViewer';
import TokenSimulationModule from 'bpmn-js-token-simulation/lib/viewer';

const viewer = new BpmnViewer({
  container: '#canvas',
  additionalModules: [
    TokenSimulationModule
  ]
});

Build and Run

Prepare the project by installing all dependencies:

npm install

Then, depending on your use-case you may run any of the following commands:

# build the library and run all tests
npm run all

# run the full development setup
npm run dev

# spin up the example
npm run start:example

Additional Resources

• Talk: Making of token simulation - The case for token simulation and how it builds on top of bpmn-js
• Talk: Token simulation internals - Detailed walk through the simulators core
• Talk: Your next BPMN engine - How we turned this project into a BPMN 2.0 spec compliant simulator
• Camunda Modeler Token Simulation plug-in - Token simulation for Camunda users

Licence

MIT

bpmn-js-token-simulation's Issues

I can change the animation speed

Add support for InclusiveGateway

Problem
When there are InclusiveGateway in the diagram, it's not possible to simulate anything:

Blanko end event termintes whole process instance?

Given the attached process model the first token that reaches the end event termintes the whole instance. This is actually not correct, the second token should continue.

test.zip

Make plugin work with viewer AND modeler

Currently the plugin is built to work with the bpmn-js modeler. It should also work with the viewer.

Adding attributes to tokens

Hi!

Just stumbled over this project and i can already see that this would be a tremendous tool for the business process simulation community if it were to get a more extensive feature set.

I might even be interested in working on this myself, but for now i would just like to hear if these are even possible.

---

Is the rate at which tokens enter the process configurable in any way? Where is this set?

• If this were to be made configurable then the viewer could be used to do token based replay by reading a process log and replaying the events (token flow) as they occur in the log. This is a feature of current defacto tools such as prom and fluxicon disco

Would it be possible to create complex tokens?

• A complex token is really just a object.
• Similar to coloured tokens of colored petri nets
• These tokens are then used to determine branching condition. The viewer itself would therefore have to evaluate the expression to determine token flow..
• Current tools only use stochastic distributions to determine branching behavior, which is not ideal for all simulation scenarios. We might have cases where we would like to specify a given input?

• how does the process perform if given x inputs tokens with y attributes?

Hope to hear from you!

Herman

Add support for InclusiveGateway

Problem
When there are InclusiveGateway in the diagram, it's not possible to simulate anything:

Support groups

Is your feature request related to a problem? Please describe

Groups are simple noops from the token flow perspective, they are marked as not supported right now though:

Describe the solution you'd like

Ignore group elements.

Describe alternatives you've considered

None.

Fix log size

Log logs 'Start Event' when task name missing

Manually trigger user tasks

Problem Description

The token should wait at user tasks (just like at events) and can be triggered manually to continue.

Describe the Solution

• Optionally, any activity may be marked as pausing, making incoming tokens halt at it.

Error bpmn-js-token-simulation in IE

Details of the error below when playing a diagram.

unhandled error in event listener
TypeError: Object doesn’t support property or method ‘includes’

Steps to reproduce:

1. Open BPMN in IE 11
2. Create diagram with simple Start and End event
3. Start "Token Simulation"
4. Click play button in Start Event

See screenshot for detailed console error.

Intermediate throw event not supported

Hi, intermediate throw event seems to be not supported, until i add it to ignored elements, the problem persits, is there any solution ?

Support send and receive tasks

Is your feature request related to a problem? Please describe

Send and receive tasks are currently not supported:

Describe the solution you'd like

• Send task simply passes through.
• Receive tasks functions like an intemediate catch event (need event trigger)

Describe alternatives you've considered

None.

cant change gateway output when inside a subprocess

Describe the Bug

When the execution is inside a subprocess there is no way to change the gateway-output. The button disappears as soon as the execution enters the subprocess and reappears then leaving it. If theres a loop inside the subprocess, this may end in an endless loop.

Steps to Reproduce

Create a model like this:

Activate the simulation, and make sure, the "no"-sequence-flow is active, for we want to see the timer work:

Then start the simulation. After the execution entered the subprocess, the gateway-button ist gone.
Now the execution follows the "no"-flow for ever.

When starting the simulation again and changing the gateway to the "yes"-flow (before button vanishes), you can see, that the button reappears as soon as the execution leaves the subprocess:

Expected Behavior

The gateway-button should always be visible to be able to leave such a loop.

Environment

• Host: Camunda modeler 4.4.0 win-x64
• OS: Windows 10
• Library version: 0.11.0

Namespace CSS

Prevent crashing bpmn-js

Description

bpmn-js-token-simulation can crash bpmn-js. As of now there's no way of either preventing that or giving any useful information about the source of the crash. It is to be investigated on which side should be responsible.

Possible Approaches

Catch Errors as a Plugin

• has been investigated in 2bd6358
• all constructors and methods are executed in try...catch statements
• any errors are logged in the console specifying the constructor/method that caused the error

Catch Errors as bpmn-js

• bpmn-js catches errors caused by plugins OR crashes in a controlled manner indicating the source of the error

Detect anomalies (deadlock, livelock, races, dead tasks/nodes, starvation)

See https://hal.inria.fr/hal-01256584/document "8 Anomalies"

Undo, redo, or repeat any actions do not work in Modeler when using bpmn-js extension for token simulation

Expected Behavior

Could undo, redo, or repeat any actions in Modeler

Actual Behavior

By adding simulation plugging in Modeler; undo, redo, and repeat actions would not works correctly anymore.

Steps to reproduce the Behavior

1- Add bpmn-js extension for token simulation
https://github.com/bpmn-io/bpmn-js-token-simulation

2- By adding this in to the code
additionalModules: [ tokenSimulation ]

It would disable undo, redo, and repeat actions.

Environment

Browser:
Google Chrome,
Firefox,
Opera Web Browser ,
Safari Web Browser,
etc.

OS: Linux,
Windows,
Macintosh,
Unix,
etc.

Token vanishes after parallel split

In this process model

the token vanishes after the short path is finished.

The second token on the upper path should continue to the end.

Bump svg.js version to 3.x

Due to an issue (svgdotjs/svg.js#866) in the currently used svg.js we had to use a a locally fixed version of svg.js. Now svg.js v3.x is out there which contains the fix so we can abandon the local fix if you update token-simulation to use svg.js v3.x
Can you guys do that?
Thank you!

Change play/pause button

Token count not cleared on process instance finished

Event notification when token simulation is triggered

Hi,

Is it possible to register an event listener when someone toggles the simulation button? I would like to hide certain functions when it's triggered.

Thanks

Add basic test scenarios

Add basic scenarios that should simulate as expected.

Basic test diagrams:

Diagram 1

• simulation finishes all three paths

Diagram 2:

• simulation finishes after subprocess

Token passes Associations

If a data-based exclusive gateway has at least two (valid) outgoing sequence flows and one or more associations assigned, also these associations can be selected for the token to leave the gateway.

expected: associations are not passed by the token and cannot be selected.

Support more BPMN elements

• Normal Intermediate Event (acts like task)
• Boundary Event
• Inclusive/Complex Gateway
• Collaboration (Pool, Lane, Message Flow)
• Call Activity
• Signal Event
• Event Subprocess

I can scroll inside the log using the mouse wheel

Clear log after animation reset

Open context pad for selected element when switching from simulation to modeling

Upper Pace Limit for Token Animation

To pass a sequence flow between two neighboring should not last too long.

I do not have a suggestion for a certain limit, yet. It just should be discussed.

Update context-pad/token-count only for elements that have changed

Currently context pads and token counts are updated for EVERY element when token created/consumed. This is inefficient. There should be an event tokenSimulation.elementChanged similar to how it works in bpmn-js that indicates which element actually need an update.

Add support for Boundary Events

Problem
When there are Boundary Events in the diagram, it's not possible to simulate anything:

Proposal
Support basic triggering of any boundary events based on:

• manual trigger

Optional

• pre-set timeout in ms (e.g. dropdown on click/hover over a button similar to gateways)

I can follow a token by clicking it

Should scroll canvas to keep token focussed while animation is running.

check for not yet implemented symbols is too strict

the check for unimplemented symbols should only highlight those unimplemented symbols that could have an impact to the process' semantics.

at the moment, elements like e.g. annotations and pools cause the simulator to refuse simulating.

Add support for sendEvents and receiveEvents

If the process contains sendEvents between pools the simulation stops with all sendEvents and receivingEvents being labeled as "not supported".

End Event sometimes behaves as a Terminate Event

Describe the Bug

Sometimes (but not always) an End Event behaves like a Terminate Event. In other words the End Event removes other tokens still running.

Steps to Reproduce

See also #59 (comment) for attached screen captures.

In the "ATM Transaction" example provided, it is possible to trigger the non-interrupting timer event for the "Cash Withdrawal" activity.

If the Timer Event is triggered very early and the End Event following the "Timeout" activity is reached before the "Cash Withdrawal" is completed, the process terminates:

14:22:22:160 ATM Transaction Needed
14:22:22:164 Process 1 started
14:22:23:452 Insert Card
14:22:24:735 Select Interaction
14:22:26:16 Selected Interaction? Cash Withdrawal
14:22:27:284 Select Amount
14:22:28:567 Starting Subprocess
14:22:28:571 Cash Amount Selected
14:22:28:573 Subprocess 2 started
14:22:31:66 Timeout
14:22:31:133 Prepare Cash
14:22:31:143 Charge Account
14:22:32:351 End Event
14:22:32:355 Process 1 finished

Expected Behavior

If the Timer Event is triggered later, e.g. after "Issue Money" is conducted, the End Event following the "Timeout" activity is reached after the "Cash Withdrawal" is completed. In this case, the process does not terminate and behaves as expected:

14:25:05:704 ATM Transaction Needed
14:25:05:706 Process 1 started
14:25:06:989 Insert Card
14:25:08:269 Select Interaction
14:25:09:553 Selected Interaction? Cash Withdrawal
14:25:10:836 Select Amount
14:25:12:120 Starting Subprocess
14:25:12:124 Cash Amount Selected
14:25:12:126 Subprocess 2 started
14:25:14:688 Charge Account
14:25:14:712 Prepare Cash
14:25:17:287 Issue Money
14:25:18:577 Cash Issued
14:25:18:582 Subprocess 2 finished
14:25:19:187 Timeout
14:25:20:469 End Event
14:25:22:125 Cash Withdrawn
14:25:23:403 Check For Further Interactions
14:25:26:31 No Further Interaction Requested
14:25:27:303 Return Card
14:25:28:586 ATM Transaction Finsihed
14:25:28:588 Process 1 finished

The process should only be terminated on an End Event if there are no other tokens in the system.

Environment

I used the release 0.11.1 and deployed the app on my webhost (after creating it with npm install --save-dev webpack).

bpmn:Association not supported

Simulation fails if the model contains lanes

Lanes should have no influence on the token simulation. However, if a lane is present in the model, the simulation fails with the message "Lane not supported".

Adding 'bpmn:Lane' to the list of IGNORED_ELEMENTS at line 970 solves this issue for me.

var IGNORED_ELEMENTS = [ 'bpmn:Process', 'bpmn:Collaboration', 'bpmn:Lane' ];

You may want to add this.

Add support for instances

Instances are not supported which can lead to #20.

This should be fixed before continuing with adding features. 🚦

Ensure IE compatibility

Related to #31.

Catch Event Trigger adds new overlay for every token & token count can be negative

subprocesses do not act properly when entered by multiple tokens

actual behavior

expected behavior

... see annotations in the model

subprocessinstances.bpmn.zip

typed tasks eat tokens

as soon as tasks are switched to typed tasks (e.g. user tasks) the token is consumed in such tasks and does not continue to flowing.

Simulation mode: Don't show bendpoints on hover

synchronizing parallel gateway labels count to number of incoming sequence flows

before actually opening a synchronizing parallel gateway when the last awaited token has just arrived, the "waiting tokens counter" shall show the number of all tokens.

Context pad for start event sometimes not shown on reset simulation

Simulation mode: I can click the context menu without having to click the element first

deadlocks are marked visually

tokens that felt into a deadlock state (e.g. because a parallel gateway is waiting for a lost token) shall cause a visual warning

simulation stops at intermediate link events

Description

When using intermediate link events the simulation stops at the throw-event. There is no way to continue.

Steps to Reproduce

Create a model using intermediate link events:

the links-names must be equal

then start the simulation:

the simulation stops at the throw event:

Expected Behavior

The simulation should recognise link-events and follow them. When there is no corresponding catch-event a message should be logged.

Environment

• Host: Camunda modeler 4.4.0 win-x64
• OS: Windows 10
• Library version: 0.11.0

Process instance links not reset on reset simulation