Auto-Layout for BPMN

BPMN files imported without positioning information (DI — Diagram Interchange) are executable by Stateway, but can't be opened visually in modelers like bpmn.io or Camunda Modeler.

The ?layout=true parameter on the GET /v1/definitions/:key/xml endpoint solves this: it applies the bpmn-auto-layout (dagre) layout algorithm and injects <bpmndi:BPMNDiagram> blocks with coordinates for each element and flow.

BPMN definitions only

GET /v1/definitions/:key/xml (with or without layout=true) is only available for definitions with sourceType: 'bpmn'. Definitions created via JSON or YAML return 422 PROCESS_ERROR — supporting layout for them would require converting them to BPMN first, which was out of scope for the MVP. If you need a visualizable version, create the definition directly as BPMN.

When to use it

Scenario	Recommendation
BPMN imported without DI	Use ?layout=true to reposition everything automatically
BPMN already drawn in a modeler	Don't use ?layout=true — the original positioning will be overwritten
Definition created via JSON/YAML	Not supported — GET /xml returns 422 PROCESS_ERROR for any non-BPMN definition
Want to export visual annotations	Combine ?annotations=true&layout=true (see Exporting annotated diagrams)

Endpoint

GET /v1/definitions/:key/xml?layout=true
GET /v1/definitions/:key/xml?layout=true&version=2

Example

curl -G https://api.stateway.io/v1/definitions/expense-approval/xml \
  -H "X-API-Key: sw_live_your_key" \
  --data-urlencode "layout=true" \
  --output expense-approval.bpmn

The expense-approval.bpmn file can be opened directly in bpmn.io or Camunda Modeler.

Combining with annotations

When used together with ?annotations=true, layout is applied before annotations are injected. bpmn-auto-layout positions the process elements — it ignores textAnnotation/association (which live in bpmn:artifacts, outside of what the algorithm traverses) and, when it runs, discards any pre-existing DI in the XML. That's why auto-layout has to be the first step: if it ran afterward, it would erase the positions already computed for the annotations. Next, the text boxes (textAnnotation) and their links (association) receive DI coordinates via heuristic offset, calculated relative to the elements already positioned in the plane:

GET /v1/definitions/:key/xml?annotations=true&layout=true

See Exporting annotated diagrams for the full combination matrix.

Original behavior preserved

Without the layout parameter, the endpoint returns the XML exactly as stored — byte-identical to the source sent on upload.