Markdown BPMN diagram maker

Model a business process with BPMN. Lay out tasks, gateways and flows to document how work moves through your organisation.

BPMN format

A BPMN diagram is written as plain text: one node or flow per line, laid out on a whole-number grid. The editor above reads and writes this same text, so you can type it by hand or build it on the canvas. This format is unique to this tool, so everything it understands is documented here.

The first line

Every diagram starts with the word bpmn on its own line. You may follow it with an optional grid line to set how many pixels each grid cell is worth. The default is 48.

You write

bpmn
grid 48
start s1 1 1 "Begin"

You get

Nodes

Each node has a keyword, an id, its grid x and y, then an optional quoted label. Coordinates count grid cells, so 4 3 means four cells across and three down. The id is how flows refer to the node, so give each node a short unique id. A task always needs a label.

You write

bpmn
start s1 1 2 "Order in"
task t1 4 2 "Pick items"
end e1 7 2 "Shipped"

You get

Events

A circle marks something that happens. A start event opens the process with a thin circle, an end event closes it with a thick circle, and an event is an intermediate event drawn as a double circle for something that happens partway through.

You write

bpmn
start s1 1 2 "Start"
event ev 4 2 "Wait"
end e1 7 2 "End"
flow s1 ev
flow ev e1

You get

Tasks

A task is a unit of work, drawn as a rounded rectangle with its label centred inside. Use usertask for work a person does (it adds a small person glyph in the corner) or servicetask for work a system does (it adds a small gear).

You write

bpmn
task t1 2 1 "Review"
usertask t2 2 3 "Approve"
servicetask t3 2 5 "Charge card"

You get

Gateways

A diamond splits the flow into paths or merges them back. A gateway is an exclusive gateway (one path is taken) drawn with an X, and a parallel gateway (every path is taken) is drawn with a +.

You write

bpmn
gateway g1 2 1 "In stock?"
parallel g2 2 4 "Fork"

You get

Flows

Write flow and two node ids to draw a sequence flow from the first node to the second. The arrow is routed orthogonally between the two nodes' nearest edges. Add a quoted label to name the branch, which is handy on the paths out of a gateway.

You write

bpmn
start s1 1 3 "In"
gateway g1 4 3 "OK?"
task t1 7 1 "Accept"
task t2 7 5 "Reject"
flow s1 g1
flow g1 t1 "yes"
flow g1 t2 "no"

You get

Comments

Anything after a # on a line is ignored, so you can annotate the source.

You write

bpmn
# happy path only
start s1 1 2 "In"
task t1 4 2 "Handle"    # the work
end e1 7 2 "Out"
flow s1 t1
flow t1 e1

You get

A full process

Putting it together: a start event, tasks, an exclusive gateway that branches, and an end event that both branches reach.

You write

bpmn
start s1 1 3 "Order in"
task t1 4 3 "Receive order"
gateway g1 7 3 "In stock?"
task t2 10 1 "Ship order"
usertask t3 10 5 "Contact buyer"
end e1 13 3 "Done"
flow s1 t1
flow t1 g1
flow g1 t2 "yes"
flow g1 t3 "no"
flow t2 e1
flow t3 e1

You get

Cheat sheet

Write this	You get
`bpmn`	Start a diagram (required first line)
`grid 48`	Set pixels per grid cell (default 48)
`start id x y "text"`	Start event (thin circle)
`end id x y "text"`	End event (thick circle)
`event id x y "text"`	Intermediate event (double circle)
`task id x y "text"`	Task (rounded rectangle, label required)
`usertask id x y "text"`	Task with a person glyph
`servicetask id x y "text"`	Task with a gear glyph
`gateway id x y "text"`	Exclusive gateway (diamond with X)
`parallel id x y "text"`	Parallel gateway (diamond with +)
`flow fromId toId`	Sequence flow arrow between two nodes
`flow fromId toId "text"`	Flow with a branch label
`# note`	A comment, ignored to the end of the line