Annotations & Data

bpmn:textAnnotation + association for human-readable notes not processed during execution; bpmn:dataStoreReference to document where data is read from or written to; bpmn:group categories for visual grouping.

Three side-channel elements annotate the flow without being part of the typed element vocabulary: text annotations, data stores, and categories. They carry human-readable context (and can be useful to an AI too, when connected meaningfully) but they are not steps and do not affect execution order.

Text Annotation

A free-text note for human readers, attached to any element via a bpmn:association. Rendered as an open bracket with text next to the element; not processed during execution.

<bpmn:textAnnotation id="Annotation_1">
  <bpmn:text>Rejection must complete within the same transaction — no partial states.</bpmn:text>
</bpmn:textAnnotation>

<bpmn:association id="Association_1" sourceRef="Task_reject" targetRef="Annotation_1" />

The annotation’s content lives in the bpmn:text child element. In DAI Studio it is edited on the canvas or through the Properties panel’s Text field. In the editor this is the Annotation type.

Data Store

bpmn:dataStoreReference documents where data is read from or written to — a database, an object store, or any persistent store the process touches — without describing the connection mechanics (use the more specific Database type, or a cloud or open-source database type, when you want engine, host, and access pattern detail).

<bpmn:dataStoreReference id="DataStore_1" name="Orders DB"
  dai:notes="Long-term record of confirmed orders; retained for seven years." />

Category

A visual boundary for categorising related elements, drawn as a dashed frame on canvas. Categories colour-label regions of a large diagram — for example, “owned by team X” or “v2 scope” — without affecting execution or nesting semantics (unlike a container, elements visually inside a category are not its children in the tree). BPMN’s bpmn:group has no name attribute, so DAI Studio stores the category’s label as a field:

<bpmn:group id="Group_cat_1"
  dai:notes="Everything inside this boundary is planned for the v2 release.">
  <bpmn:extensionElements>
    <dai:fields>
      <dai:field key="name">v2 scope</dai:field>
    </dai:fields>
  </bpmn:extensionElements>
</bpmn:group>

Like other flow elements, Data Stores and Categories accept a dai:notes description.