To see bpmn-visualization in action, give a try to the [forward] examples live environment.
You will quickly have an overview of the bpmn-visualization capabilities.
bpmn-visualization is an open source library.
You can find the source code on GitHub.
We will be more than happy to exchange ideas and more with you on the subject.
Because who knows, if you feel like contributing (feature, bug, doc, etc), you are very welcome to do so! 🙂
bpmn-visualization can be directly used in HTML pages or integrated in Javascript and TypeScript applications. It is distributed as a npm package
in various bundle formats.
The API documentation is provided directly in the package thanks to the TypeScript declaration files that can be used in IDE for code assist.
For more technical details and how-to, go to the bpmn-visualization-examples repository.
Here are a list of terms and concepts we are using in the bpmn-visualization documentation, issues, examples…
| Term or concept | Description |
|---|---|
BPMN rendering |
The part of the rendering that concerns purely the BPMN model according to the specification |
Customization |
The library user changes the rendering / behavior using their own code by extending the library |
Configuration |
The library user changes the rendering / behavior using existing features |
Custom behavior |
Any behavior that causes changes in the BPMN rendering (adding popup, changing elements color or thickness…) |
Diagram navigation |
Set of user interactions, that permits pan and zoom, to achieve desired visibility on diagram elements or diagram as a whole |
Options |
Configuration elements used at the library initialization and by the APIs at runtime |
Library integration |
Something about how an app can integrate the library |
Process data |
Execution data + derived data |
Execution data |
Data that is generated during the natural process instance flow: state, logs, … |
Derived data |
Data that by any means derives from the execution data and/or other contextual data |
BPMN diagrams are at the foundation of the bpmn-visualization capabilities.
Go to Supported BPMN Elements section to better now what is the current BPMN support.
The first goal of bpmn-visualization is to render BPMN diagrams but this is up to the integration (i.e. the application that uses it) to provide the BPMN diagram
content.
For instance, it can be retrieved from a local file, by pulling a REST API, made available after a push from websockets or SSE, …
Once the integration gets the BPMN diagram input source, it just has to pass it to bpmn-visualization which is then in charge of rendering the diagram.
By default, the rendering uses the following settings:
-
fill color:
white -
stroke color:
black -
font:
-
family:
Arial, Helvetica, sans-serif -
color:
black -
size:
11
-
The default colors are deliberately neutral. They make it easy to highlight process data with specific colors.
If the defaults don’t fit your needs, please read how to customize the BPMN Theme.
Default BPMN Theme
It is possible to change the default theme by extending bpmn-visualization or by using CSS in the page displaying the diagram.
-
Extending gives the full control on the theme customization, including colors, size, icons, and more.
-
CSS is the fastest to implement but provides fewer features. For instance, you cannot change the icons or precisely control the size of the strokes.
|
Important
|
The current extension mechanism is experimental and subject to change. |
For more details, see the [forward] Custom BPMN Theme examples.
Custom BPMN Theme
As of version 0.35.0, bpmn-visualization supports the BPMN in Color Specification with a fallback to the
bpmn.io specific BPMN extensions for colors (a.k.a bioc).
This support is disabled by default, and it can be enabled at the library initialization.
miwg-test-suite C.1.0 reference diagram using "BPMN in Color"
In addition to BPMN rendering, bpmn-visualization provides several ways to explore and navigate through the BPMN diagrams.
This is made available at load time or at runtime, through user interactions or API calls.
The navigation features are:
-
zoom: change the diagram scale to show details or have an overview of the diagram.
-
fit: reset/set the zoom level and eventually translate the diagram (for instance, center the diagram).
-
pan: drag the diagram and move/translate it, to hidden parts or change the position in the view.
Navigation is particularly useful for large diagrams. Fitting the view to the screen provides a good overview of a large diagram, but it can be hard to see details.
You can zoom to highlight specific parts, then pan to view different diagram portions.
After navigating around, you may want to reset the zoom level and go back to a full diagram overview.
Navigation with the miwg-test-suite C.2.0 BPMN diagram
bpmn-visualization gives you the opportunity to visualize the Process Data on top of the BPMN diagrams.
The purpose of the library is to gain the visibility on what happens in your processes.
Process Data consists of two main data sets:
-
Execution Data - data that accompanies the process instance (case) through the execution flow. All the events occurring along this workflow, contractual data and every other bits of information related to this particular instance from start to the end.
-
Derived Data - data that derives from the execution data: predictions, analysis, statistics. The other data that can be associated with the process instance can also be a part of this set.
The example of Process Data for different tasks can be as follows.
user task:
-
time of the execution
-
percentage of the time spent in this task in the scope of whole time to finish the process instance
-
data related to list of activities done to complete this task:
-
SAP data manipulations
-
messaging system data
-
Microsoft Excel entries (reporting)
-
other proprietary systems data
-
service task:
-
time of the execution
-
data related to list of activities done to complete this task:
-
RPA robot data
-
external API call
-
…
-
bpmn-visualization provides API to interact with the BPMN elements and their representation as DOM Element.
Fore more examples about Custom Behavior, see the [forward] examples live environment
A BPMN element contains BPMN semantic information that can be matched with Process data. The DOM Element let you manipulate the representation and allow enriching its behavior by adding event listeners for instance.
The following example demonstrates how to let users interact with a BPMN diagram when clicking on a task, passing the mouse over another task or a transition between two elements.
Here, it displays BPMN information only, but it could use this feature to display execution data related to the current BPMN element: execution time and details, pending user
of an activity, current error at this stage of the process, and more.
Display popovers on over or click
The style of BPMN elements can be modified at runtime allowing to mark, hide, change appearance of one or several specific elements. For instance, this feature can be used to mark a task as in error, warn that an activity has been started for a while and seems stuck, …
This example shows how to see which path in a process is the current running activity.
Path highlighting with the miwg-test-suite C.1.1 BPMN diagram
bpmn-visualization provides API to add overlays on top of BPMN elements. This additional overlays layer permits you to show whatever data you want and enrich your diagrams.
There are various use cases concerning overlays. For example the aforementioned Process data can be easily displayed in rectangular shapes on top of the edges and tasks. Whether you would like to show a path frequency or probability for the next step, the overlays are here to help you achieve this.
To see overlays simple examples, go to the [forward] Simple examples - live demo You will find out how to add overlays to BPMN elements and how to apply style to them.
Simple overlay example.
For the more complete example, please go to [forward] Monitoring of all process instances - live demo. This demo shows how to add execution time and frequency data on diagram elements.
Monitoring of all process instances demo, execution time and frequency displayed on BPMN elements.