Exporting annotated diagrams

Stateway's differentiator is using BPMN as an auditability bridge between technical teams and business stakeholders. However, generic modelers like bpmn.io or Camunda Modeler silently ignore stateway: extensions in the XML — an auditor who opens the file sees a "clean" diagram that hides exactly the decisions that need to be audited.

The ?annotations=true parameter solves this: it derives canonical BPMN visualization elements (<bpmn:textAnnotation> linked via <bpmn:association>) from stateway: extensions and relevant canonical attributes, injecting them into the exported XML.

info

Annotations are always derived on-demand. The definition's source stored in Stateway is never altered.

Endpoint

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

Query parameters

Parameter	Type	Default	Description
`annotations`	boolean	`false`	Enables `textAnnotation`/`association` generation
`annotationTypes`	CSV string	all	Filters categories: `type,validation,datastore,assignment,service,decision,gateway,timer`
`layout`	boolean	`false`	Applies auto-layout (recommended together with `annotations`)
`version`	integer	latest active	Specific definition version

`annotations × layout` combination matrix

`annotations`	`layout`	Result
`false`	`false`	Raw XML, identical to what's stored
`false`	`true`	XML with auto-layout only
`true`	`false`	Annotations injected; annotation DI computed via heuristic offset
`true`	`true`	Elements auto-laid-out; annotations injected afterward with heuristic-offset DI

Example call

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

Annotation categories

Each category reads an extension or canonical attribute and produces a text box linked to the corresponding element.

Category	Element	Source	Example generated text
`service`	`serviceTask`	`taskDefinition type="http"` + `taskHeaders` + `ioMapping`	`HTTP GET https://credit-bureau.example.com/score` `mode: sync · timeout: 5000` `← cnpj` `→ creditReportScore`
`decision`	`businessRuleTask`	`taskDefinition type="decision"` + `decisionKey` + `ioMapping`	`DMN: credit-score-decision` `← cnpj, score` `→ creditScore, approved, creditLimit`
`assignment`	`userTask`	`assignmentDefinition`	`Assignment:` `assignee: {{variables.managerEmail}}` `groups: credit-managers, compliance`
`gateway`	`sequenceFlow`	`conditionExpression` / default flow	`if: {{variables.approved == true}}` or `else`
`timer`	events with `timerEventDefinition`	`timeDuration` / `timeDate` / `timeCycle`	`Timer: duration PT48H`
`datastore`	`dataStoreReference`	`storeAccess`	`DataStore: customerStore` `key: =variables.cnpj` `mode: snapshot` `projection: creditHistory, previousLoans`
`type`	`dataObject` / Activity with `ioSpecification`	`itemDefinition` with `stateway:schema`	`Type: Application Data` `companyName: string` `cnpj: string`
`validation`	`dataObject` / Activity with `ioSpecification`	JSON Schema constraints	`Validation:` `Application Data required: companyName, cnpj` `Application Data.companyName length: 2..∞` `Application Data.cnpj pattern: ^[0-9]{14}$`

note

For type/validation on a bpmn:DataObject, the annotation is generated on the DataObject, but the association points to the visual DataObjectReference when one exists in the same process. This avoids modeler warnings, since modelers render the reference, not the underlying object.

Filtering categories

To export only service and decision annotations:

GET /v1/definitions/:key/xml?annotations=true&layout=true&annotationTypes=service,decision

Invalid values in annotationTypes return 400 VALIDATION_ERROR.

Deterministic IDs

Generated annotations use namespaced, deterministic IDs, so that two exports of the same process produce identical XML:

textAnnotation: sw_ann_<elementId>_<category>
association: sw_assoc_<elementId>_<category>
DI shapes/edges: _di suffix

Common errors

Code	Condition
`404 NOT_FOUND`	Definition not found in the tenant
`422 PROCESS_ERROR`	The definition is not of type BPMN (JSON/YAML don't export XML)
`400 VALIDATION_ERROR`	`annotationTypes` contains an invalid value
`401 UNAUTHORIZED`	API key missing or invalid

Endpoint​

Query parameters​

annotations × layout combination matrix​

Example call​

Annotation categories​

Filtering categories​

Deterministic IDs​

Common errors​