Guide / Check your work

Diagram check

The check lists everything wrong with your diagram, points at each problem on the canvas, and says why it matters and how to fix it.

Free How it runs and Code need Pro

Run it

1. Press Check on the toolbar. A card called Diagram check opens at the bottom right of the canvas, over it rather than under it.
2. Read the header. It counts the findings in words and how many are notes about readability, for example 8 errors, 1 warning, 1 readability.
3. Click a line. The canvas scrolls to that element and selects it, and its outline turns red.
4. Press Show all to open the Problems tab, where every finding is. Click a finding there and its Why and Fix lines open under it, with a link to that check's own page.
5. Fix the problem. The check runs again by itself a moment after you stop editing. Recheck forces a new pass. Close, or pressing Check again, puts the card and the outlines away.

The check starts as soon as a diagram is read and runs again as you edit, whether or not the card or the tab is open. That is why the count is always on the canvas and always the same number.

Two places to read it

You can choose the Problems tab of the sidebar directly, without the card. The Check button stays pressed while either one is showing. Opening the tab puts the card away, since the tab says everything the card does.

Clicking a finding in either place selects its element on the canvas and opens the property that fixes it: job type, form key or id, correlation key, history time to live, called element, error, escalation, message and signal references and timer definitions, and a missing job type, topic, class or delegate expression in the code. A finding with no single field still switches the sidebar to Properties and selects the element. Resting the pointer on a drawing finding in the tab shows its element on the canvas without selecting it.

What you see

While the card is open, every element that a problem is about carries an outline on the canvas. A small pill at the bottom of the canvas says the same as the header of the card, in the same words. It is green when nothing is wrong, amber for warnings and red for errors. The badge on the Problems tab carries the number of errors and warnings. The pill is hidden while the card is open, since the card says the same thing, and both count the same findings: a compatibility rule the linter reports as information counts as a warning, and a problem two checks both report is counted once.

With nothing wrong, the pill says No problems found. In the Problems tab the same words are the heading, with Nothing to report across N elements and connections. The check runs again as you edit. under it. Until the first pass is done the tab says Waiting for a diagram to check.

Every check has an id

Each check has a stable id, such as drawing/overlap, bpmnlint/label-required or form/key-clash, a line on why it matters and a line on how to fix it. The same id travels with the finding everywhere else it is reported: penstock check --format json, SARIF and GitHub annotations all carry the id and the address of its page, so a finding in a pull request leads back to the same page the editor showed.

The catalogue is generated from the rule definitions, so an id never changes meaning. Every check has its own page under Every rule, grouped by what it is about, and you can read them all without opening a diagram.

The groups

The Problems tab groups findings by what they are about, in this order. A group only appears when it has something to say.

Without Pro, the flow group is one row that says how many such problems it found and offers to buy it. The same analysis is the flow section of penstock check, or penstock check --only flow on its own.

Drawing and rules are different

The drawing checks answer "can the diagram be read?". They know nothing about the process. bpmnlint answers "is the process modelled correctly?". They never report the same thing twice.

Problems outside the editor

Where the findings appear outside the editor is up to your tool. Some put them in their own problem list, and mark the file itself.

Check the whole project

The card checks the diagram you have open. The same checks also run over every diagram, decision and form of a project at once, and their findings carry the same rule ids. Only errors make a whole-project check fail. A warning is shown as a note.

$ penstock check .
ok    src/main/resources/approve-order.form
fail  src/main/resources/order-process.bpmn
        OVERLAP: approve_order <-> charge_card
        DETACHED-EDGE: Flow_1 (order_received->approve_order)
        note bpmnlint/no-overlapping-elements: Element overlaps with other element (approve_order)
ok    src/main/resources/shipping-method.dmn

Every rule has a page with why it matters and how to fix it: https://kern0x1b.github.io/penstock-release/rules

Fix a whole diagram at once

If the list is long because the diagram drifted, Auto layout is usually faster than fixing line by line. The check measures. Auto layout draws a diagram that passes.

What it cannot see

Three measures need the file rather than the canvas: a connection declared in the XML that was never drawn, a connection with an end missing, and a comparison of what the diagram meant before an operation against after. The check leaves those out instead of reporting them as passing. A diagram that cannot be read shows a screen of its own rather than a card: what the parser objected to, the line it objected on, that the file was not changed, and buttons to open the XML in the Text tab at that line and to Reload.

Common problems

The card says "The bpmnlint rules could not run".

Your .bpmnlintrc uses rules from a plugin. The editor needs those rules in a bundle. See Validation.

I fixed a problem and it is still listed.

Press Recheck. The list refreshes a moment after you stop editing.

The count in the header is lower than the list.

The card lists only its first three findings, and Show all opens the rest. The badge on the Problems tab counts errors and warnings but not the notes about readability, which the header counts apart. A rule set to warn is a warning rather than an error.

The pill says "No problems found." but I see something wrong.

The check reads the drawing, the rules and, with Pro, the flow and the code. A wrong value in a field, or a mistake it has no rule for, is not a finding. See Validation for the rules that run.

There is no Check button.

It may have been moved off the bar. Open More and pin Check. See The toolbar and the More menu.