Text Annotation
A bracket with free-form text attached to a node: notes the diagram itself would not otherwise capture.
What a text annotation is
A text annotation is a small open rectangle with an angled bracket on one side, containing free-form text. It attaches to any node or flow via a dashed association line. Annotations have no execution semantics. They do not change what the process does, they just attach human commentary that the formal BPMN shapes cannot carry.
Annotations are how you capture the "why" when the "what" is the flow itself. "This step takes 48 hours because the external partner’s SLA is 2 business days." "We do this manually today because the vendor API rate limits at 100/hour." "If this fails twice, legal requires escalation to the general counsel." None of that belongs in a task label, but a reader who does not know it cannot judge the process.
When annotations help and when they are clutter
- Help when the rationale behind a design choice is not obvious from the shapes: "we keep this manual because volumes are < 5/month".
- Help when a regulatory or compliance constraint drives a step: "SOX requires dual approval at this point".
- Help when there is an SLA, a rate limit, or a performance consideration attached to a specific node.
- Clutter when the annotation is just restating the activity label or explaining a concept the reader can be expected to know.
Text annotations in LucidFlow
LucidFlow generates annotations when the source document includes rationale language: "because", "due to", "as required by". Generated annotations are attached to the specific activity they pertain to and survive BPMN export. Annotations are also how the AI Copilot surfaces warnings during optimisation: "this task cannot be automated without a signed vendor agreement" appears as an annotation on the relevant node before any structural change is proposed.
Frequently asked questions
Are text annotations part of BPMN 2.0 or tool-specific?
They are part of BPMN 2.0. `textAnnotation` is a canonical element. They round-trip through XML correctly, so a diagram annotated in LucidFlow will show its annotations unchanged when opened in Camunda, Visio, or any compliant tool.
Can an annotation be attached to multiple nodes?
Yes, a single annotation can have association lines to several nodes, useful when the note applies to a stretch of the process rather than a single step.
Should I put timing or cost information in annotations?
Timing and cost belong in the activity metadata (duration, cost, frequency attributes) not in prose annotations. Engines and dashboards can use structured values, not free text. Annotations are for reasoning that has no structured slot.