Ids and comments

Use #ids when names aren't enoughCopy Anchor Link

Every node has an id. The app makes one from the kind and the name, like Task_ApproveInvoice or Gateway_Approved. Write # and an id at the end of a node line to choose it yourself.

You need one when:

• The node has no name. Merge and join gateways usually don't, so xor #merge or and #ready is how arrows find them.
• Two nodes share a name. An arrow by name can't tell them apart, so give each an id and point to the one you mean:

process Order payment

start Order received
xor Payment method?
  card -> Charge card
  invoice (default) -> #invoice_notice

service Charge card
send Notify customer #card_notice
end Order paid

send Notify customer #invoice_notice
end Invoice sent

This parses, but the checks still warn that several elements have the same name, because two steps with the same name read as one thing on the diagram.

An id starts with a letter or underscore, followed by letters, digits, _, . or -. Each id can appear once. Something that doesn't fit those rules, like #1st, isn't read as an id, and becomes part of the name instead.

How the app keeps ids stableCopy Anchor Link

Ids matter beyond the text: the BPMN XML uses them, so do the modeling checks, and the AI's edits refer to elements by id. When you edit in the Flowmark pane, the app matches each node to the diagram as it was before your edit, by kind and name with capitalization ignored, and keeps that node's id. Flows keep their ids when they still connect the same two nodes, and lanes keep theirs when the name matches.

So you can reorder lines, move a step to another lane, add steps or change how they connect, and existing ids stay the same. Two edits do give a node a new id:

• Renaming it in the text.
• Changing its kind, for example from user to service.

To rename a node and keep its id, write the old id on the line: user Check all receipts #Task_CheckReceipts. View BPMN XML… in the Export menu shows every id. Renaming a node or changing its kind on the canvas keeps the id without any of this.

The AI follows the same rule from the other side, in the assistant or a connected AI app. When it reads a diagram, it gets every node with its #id and is told to keep those ids when it rewrites the diagram. For small changes it uses edits that never touch the ids of the rest.

Leave commentsCopy Anchor Link

// at the start of a line or after a space starts a comment, and everything after it on that line is ignored.

// Draft for Tuesday's review
start Request received
user Review request   // Lea owns this step for now
end Request reviewed

A // inside a word isn't a comment, so a web address such as https://wiki.example.com/leave in a name or a doc: line is kept whole.