bpmnlint

bpmnlint

Validate your BPMN diagrams based on configurable lint rules.

Installation

Install the utility via npm:

npm install -g bpmnlint

Usage

Validate your diagrams via the commandline:

> bpmnlint invoice.bpmn

/Projects/process-application/resources/invoice.bpmn
  Flow_1    error    Sequence flow is missing condition  conditional-flows
  Process   error    Process is missing end event        end-event-required
  Task_13   warning  Element is missing label/name       label-required
  Event_12  warning  Element is missing label/name       label-required
  Event_27  warning  Element is missing label/name       label-required
  Process   error    Process is missing start event      start-event-required

✖ 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:

{
  "extends": "bpmnlint:recommended"
}

Add or customize rules using the rules block:

{
  "extends": "bpmnlint:recommended",
  "rules": {
    "label-required": "off"
  }
}

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

{
  "extends": [
    "bpmnlint:recommended",
    "plugin:foo/recommended",
    "plugin:@bar/bpmnlint-plugin-bar/recommended"
  ]
}

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

Plug-ins will be resolved relative to the configuration file location, using node module resolution.

Available Configurations

• bpmnlint:all - all rules as errors
• bpmnlint:recommended - opinionated rules ("best practices") and rules enforcing BPMN compliance
• bpmnlint:correctness - rules enforcing BPMN compliance

Moddle extensions

To validate your diagrams with custom moddle extensions, add moddleExtensions to the root configuration file:

{
  "extends": [
    "bpmnlint:recommended",
    "plugin:custom/recommended"
  ],
  "moddleExtensions": {
    "custom": "custom-bpmn-moddle/resources/custom.json"
  }
}

The extension will be resolved relative to the configuration file location, using node module resolution.

API

Invoke the tool directly from NodeJS:

import Linter from 'bpmnlint';
import NodeResolver from 'bpmnlint/lib/resolver/node-resolver';

import BpmnModdle from 'bpmn-moddle';

const moddle = new BpmnModdle();

const linter = new Linter({ 
  config: {
    extends: 'bpmnlint:recommended'
  },
  resolver: new NodeResolver()
});

const xmlStr = `
  <?xml version="1.0" encoding="UTF-8"?>
  <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" 
                     id="definitions" 
                     targetNamespace="http://bpmn.io/schema/bpmn">
    <bpmn:process id="process" />
  </bpmn:definitions>
`;

const {
  rootElement: definitions
} = await moddle.fromXML(xmlStr);

const reports = linter.lint(definitions);

// {
//    "end-event-required": [
//      {
//        "id": "process",
//        "message": "Process is missing end event"
//      }
//    ],
//    ...
// }

Writing a Plug-in

Create your first plug-in using the plugin creator:

npm 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:

{
  "extends": [
    "bpmnlint:recommended",
    "plugin:foo/recommended",
    "plugin:@bar/bpmnlint-plugin-bar/recommended"
  ],
  "rules": {
    "foo/special-rule": "off",
    "@bar/bar/other-rule": "warn"
  }
}

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

Changelog

11.6.1

• FIX: remove ad-hoc flow check
• FIX: correct documentationUrl for no-gateway-join-fork