bpmnlint

Validate your BPMN diagrams based on configurable lint rules.

Installation

Install the utility via npm:

1npm install -g bpmnlint

Usage

Validate your diagrams via the commandline:

1> bpmnlint invoice.bpmn
2
3/Projects/process-application/resources/invoice.bpmn
4  Flow_1    error    Sequence flow is missing condition  conditional-flows
5  Process   error    Process is missing end event        end-event-required
6  Task_13   warning  Element is missing label/name       label-required
7  Event_12  warning  Element is missing label/name       label-required
8  Event_27  warning  Element is missing label/name       label-required
9  Process   error    Process is missing start event      start-event-required
10
11✖ 6 problems (6 errors, 0 warnings)

Rules

Our documentation lists all currenty implemented rules, the ./rules folder contains each rules implementation.

Do you miss a rule that should be included? Propose a new rule.

Configuration

Create a .bpmnlintrc file in your working directory and inherit from a common configuration using the extends block:

1{
2  "extends": "bpmnlint:recommended"
3}

Add or customize rules using the rules block:

1{
2  "extends": "bpmnlint:recommended",
3  "rules": {
4    "label-required": "off"
5  }
6}

You may also extend from multiple configurations, including those provided by custom plug-ins:

1{
2  "extends": [
3    "bpmnlint:recommended",
4    "plugin:foo/recommended",
5    "plugin:@bar/bpmnlint-plugin-bar/recommended"
6  ]
7}

This will amend core recommended rules with recommended rulesets provided by bpmnlint-plugin-foo and @bar/bpmnlint-plugin-bar, respectively.

API

Invoke the tool directly from NodeJS:

1import Linter from 'bpmnlint';
2import NodeResolver from 'bpmnlint/lib/resolver/node-resolver';
3
4import BpmnModdle from 'bpmn-moddle';
5
6const moddle = new BpmnModdle();
7
8const linter = new Linter({ 
9  config: {
10    extends: 'bpmnlint:recommended'
11  },
12  resolver: new NodeResolver()
13});
14
15const xmlStr = `
16  <?xml version="1.0" encoding="UTF-8"?>
17  <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" 
18                     id="definitions" 
19                     targetNamespace="http://bpmn.io/schema/bpmn">
20    <bpmn:process id="process" />
21  </bpmn:definitions>
22`;
23
24const {
25  rootElement: definitions
26} = await moddle.fromXML(xmlStr);
27
28const reports = linter.lint(definitions);
29
30// {
31//    "end-event-required": [
32//      {
33//        "id": "process",
34//        "message": "Process is missing end event"
35//      }
36//    ],
37//    ...
38// }

Writing a Plug-in

Create your first plug-in using the plugin creator:

1npm init bpmnlint-plugin {PLUGIN_NAME}

Checkout the bpmnlint-plugin-example for details on how to define, test, and consume custom lint rules. Use the bpmnlint playground to implement new rules with quick visual feedback.

[!NOTE] Plug-ins must always follow the naming scheme bpmnlint-plugin-{NAME_OF_YOUR_PLUGIN} and may contain a namespace prefix.

When using your custom plug-in, reference its configuration or rules via the shorthand plug-in name, or the full identifier:

1{
2  "extends": [
3    "bpmnlint:recommended",
4    "plugin:foo/recommended",
5    "plugin:@bar/bpmnlint-plugin-bar/recommended"
6  ],
7  "rules": {
8    "foo/special-rule": "off",
9    "@bar/bar/other-rule": "warn"
10  }
11}

Bundling

For browser usage include your linting configuration using your favorite bundler plug-in (Rollup, Webpack).

Visual Feedback

Integrate the linter via bpmn-js-bpmnlint into bpmn-js and get direct feedback during modeling.

To try out visual validation, checkout the bpmnlint playground.

Related

• bpmnlint-plugin-example - an example plug-in
• bpmnlint-playground - a playground to implement new rules with quick visual feedback
• bpmnlint-generate-docs-images - Generate images for your bpmnlint documentation
• bpmn-js-bpmnlint - integration into bpmn-js

License

MIT