@bpmnkit/core 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/builder-reference.md +211 -0
  2. package/dist/bpmn/auto-layout.js +32 -4
  3. package/dist/bpmn/bpmn-builder.d.ts +125 -3
  4. package/dist/bpmn/bpmn-builder.js +253 -34
  5. package/dist/bpmn/bpmn-model.d.ts +2 -0
  6. package/dist/bpmn/bpmn-parser.js +8 -0
  7. package/dist/bpmn/bpmn-serializer.js +1 -1
  8. package/dist/bpmn/builder-coverage.js +4 -12
  9. package/dist/bpmn/camunda7/export.d.ts +25 -0
  10. package/dist/bpmn/camunda7/export.js +218 -0
  11. package/dist/bpmn/camunda7/migrate.d.ts +3 -0
  12. package/dist/bpmn/camunda7/migrate.js +3 -3
  13. package/dist/bpmn/compact.d.ts +21 -0
  14. package/dist/bpmn/compact.js +86 -1
  15. package/dist/bpmn/full-operations.js +336 -3
  16. package/dist/bpmn/operations.d.ts +42 -1
  17. package/dist/bpmn/operations.js +12 -2
  18. package/dist/bpmn/optimize/flow.js +2 -0
  19. package/dist/bpmn/strip-camunda8.d.ts +22 -0
  20. package/dist/bpmn/strip-camunda8.js +55 -0
  21. package/dist/bpmn/utils.js +151 -1
  22. package/dist/bpmn/zeebe-extensions.d.ts +59 -2
  23. package/dist/bpmn/zeebe-extensions.js +89 -1
  24. package/dist/connectors/apply-element.d.ts +7 -3
  25. package/dist/connectors/apply-element.js +115 -4
  26. package/dist/connectors/apply-many.d.ts +5 -1
  27. package/dist/connectors/apply-many.js +5 -2
  28. package/dist/connectors/apply.d.ts +24 -3
  29. package/dist/connectors/apply.js +103 -3
  30. package/dist/connectors/catalog.js +5 -0
  31. package/dist/connectors/index.d.ts +1 -1
  32. package/dist/connectors/template-types.d.ts +30 -0
  33. package/dist/connectors/validate.js +33 -0
  34. package/dist/index.d.ts +6 -2
  35. package/dist/index.js +2 -0
  36. package/dist/layout/annotations.d.ts +3 -1
  37. package/dist/layout/annotations.js +72 -14
  38. package/dist/layout/semantic/place.js +23 -5
  39. package/dist/layout/semantic/route.js +15 -0
  40. package/dist/layout/types.d.ts +2 -1
  41. package/package.json +2 -1
@@ -0,0 +1,211 @@
1
+ # @bpmnkit/core builder reference
2
+
3
+ Generated from `bpmn-builder.ts`; do not edit.
4
+
5
+ ## Rules
6
+
7
+ - Start with `Bpmn.createProcess(id)`, end with `.build()`, then `Bpmn.export(definitions)` for the XML. Call `.withAutoLayout()` before `.build()`, or the diagram has no shapes.
8
+ - Element ids are unique. Each element connects to the previous one automatically; there are no manual flows.
9
+ - `subProcess`, `transaction`, `eventSubProcess` and `adHocSubProcess` take the callback as the SECOND argument and options THIRD: `.subProcess(id, (sub) => sub.startEvent()..., { name })`. Swapped order is tolerated.
10
+ - Gateways fork with `.branch(name, (b) => b...)`. Inside, `b.condition(feelExpr)` sets the flow condition and `b.defaultFlow()` marks the default flow. To merge, end a branch with `.connectTo(targetId)` and declare that target after the last branch.
11
+ - Event definitions are named options, not nested objects: `timerDuration`, `timerDate`, `timerCycle`, `messageName` + `correlationKey`, `signalName`, `errorCode`, `escalationCode`, `linkName`. Unknown options are silently dropped: `timer: { duration }` does nothing.
12
+ - `withBoundary(id, options, (b) => ...)` attaches a boundary event to the PRECEDING activity; the callback builds the path leaving it, and the main chain continues from the activity.
13
+ - FEEL expressions start with `=`. Options without `?` are required.
14
+
15
+ ## Methods
16
+
17
+ `ProcessBuilder` methods (all return `this`; callback builders have the element methods too). `?` = optional.
18
+
19
+ Events:
20
+ - startEvent(id?: string, options?: StartEventOptions)
21
+ - endEvent(id?: string, options?: EndEventOptions)
22
+ - intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions)
23
+ - intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions)
24
+ - boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">)
25
+ - withBoundary(id: string, options: Omit<BoundaryEventOptions, "attachedTo">, handler: (b: ProcessBuilder) => void)
26
+ Tasks and connectors:
27
+ - serviceTask(id: string, options: ServiceTaskOptions)
28
+ - restConnector(id: string, config: RestConnectorConfig)
29
+ - scriptTask(id: string, options: ScriptTaskOptions)
30
+ - userTask(id: string, options?: UserTaskOptions)
31
+ - sendTask(id: string, options?: MessageTaskOptions)
32
+ - receiveTask(id: string, options?: MessageTaskOptions)
33
+ - businessRuleTask(id: string, options?: BusinessRuleTaskOptions)
34
+ - callActivity(id: string, options: CallActivityOptions)
35
+ - manualTask(id: string, options?: ElementOptions)
36
+ - task(id: string, options?: ElementOptions)
37
+ Gateways:
38
+ - exclusiveGateway(id: string, options?: GatewayOptions)
39
+ - parallelGateway(id: string, options?: ElementOptions)
40
+ - inclusiveGateway(id: string, options?: GatewayOptions)
41
+ - eventBasedGateway(id: string, options?: ElementOptions)
42
+ - complexGateway(id: string, options?: GatewayOptions)
43
+ Containers (sub-processes):
44
+ - adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions)
45
+ - subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions)
46
+ - transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions)
47
+ - eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions)
48
+ Flow control:
49
+ - at(nodeId: string)
50
+ - insertAfter(nodeId: string)
51
+ - branch(name: string, callback: (b: BranchBuilder) => void)
52
+ - connectTo(targetId: string)
53
+ - element(elementId: string)
54
+ Process settings and misc:
55
+ - withAutoLayout()
56
+ - executionPlatformVersion(version: string)
57
+ - defaults(options: {serviceTask?: {retries?: string}})
58
+ - name(name: string)
59
+ - executable(value: boolean)
60
+ - versionTag(tag: string)
61
+ - message(id: string, options: {name: string})
62
+ - error(id: string, options: {code: string; name?: string})
63
+ - signal(id: string, options: {name: string})
64
+ - escalation(id: string, options: {code: string; name?: string})
65
+ - textAnnotation(text: string)
66
+ - annotate(elementId: string, text: string, options?: AnnotateOptions)
67
+ - build(options?: BuildOptions)
68
+ Other:
69
+ - dataObject(id: string, options?: DataElementOptions)
70
+ - dataObjectReference(id: string, dataObjectRef: string, options?: DataElementOptions)
71
+ - dataStoreReference(id: string, dataStoreRef: string, options?: Pick<DataElementOptions, "name">)
72
+ - dataAssociation(activityId: string, dataRefId: string, direction: "input" | "output")
73
+
74
+ Only inside `.branch()` callbacks (BranchBuilder), applied to the flow leaving the gateway:
75
+ - condition(expression: string)
76
+ - label(text: string)
77
+ - flowId(id: string)
78
+ - defaultFlow()
79
+
80
+ Not available inside callbacks (top-level only): at, insertAfter, withAutoLayout, executionPlatformVersion, defaults, name, executable, versionTag, message, error, signal, escalation, restConnector, build.
81
+
82
+ ## Options
83
+
84
+ `+El` = also accepts the ElementOptions fields.
85
+
86
+ - ElementOptions: name?: string; documentation?: string (Free-text documentation…)
87
+ - StartEventOptions +El: condition?: string (FEEL condition); timerDuration?: string (Timer duration (ISO 8601)); timerDate?: string (Timer date (ISO 8601)); timerCycle?: string (Timer cycle (ISO 8601)); messageName?: string (Message name); formId?: string (Form to show when the process is…); isInterrupting?: boolean (Non-interrupting flag)
88
+ - EndEventOptions +El: errorCode?: string (Error code); messageName?: string; signalName?: string (Signal name); escalationCode?: string (Escalation code)
89
+ - IntermediateThrowEventOptions +El: messageName?: string; signalName?: string; escalationCode?: string; compensation?: boolean (Emit a compensateEventDefinition); linkName?: string (Link name)
90
+ - IntermediateCatchEventOptions +El: timerDuration?: string; timerDate?: string; timerCycle?: string; messageName?: string; correlationKey?: string (FEEL expression correlating this…); signalName?: string; linkName?: string; condition?: string
91
+ - BoundaryEventOptions +El: attachedTo: string (ID of the activity this boundary…); cancelActivity?: boolean (Whether the host activity is…); errorCode?: string; timerDuration?: string; timerDate?: string; timerCycle?: string; messageName?: string; correlationKey?: string; signalName?: string; compensation?: boolean; condition?: string
92
+ - ServiceTaskOptions: multiInstance?: MultiInstanceOptions (Runs the activity once per item…); name: string; taskType: string (Zeebe job type for this task); retries?: string (Number of retries…); ioMapping?: ioMapping shape (Input/output variable mappings); taskHeaders?: Record<string, string> (Task header key-value pairs); linkedResources?: ZeebeLinkedResource[] (Resources the task runs, e.g. an…); documentation?: string
93
+ - MultiInstanceOptions: isSequential?: boolean; collection?: string; elementVariable?: string; outputCollection?: string (Variable that collects each…); outputElement?: string (FEEL expression evaluated per…); completionCondition?: string
94
+ - RestConnectorConfig: name?: string; method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" (HTTP method…); url: string (Target URL); authentication?: {type: "noAuth"} | {type: "bearer"; token: string} (Authentication configuration); headers?: Record<string, string> | string (HTTP headers as key-value pairs…); body?: string (Request body); retries?: string; resultVariable?: string (Variable name to store the full…); resultExpression?: string (FEEL expression to extract values…)
95
+ - ScriptTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; expression: string (FEEL expression for the script); resultVariable: string; documentation?: string
96
+ - UserTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; formId?: string; externalReference?: string (External form URL…); embeddedForm?: {id: string; schema: string} (Embeds a Camunda Form: writes a…); ioMapping?: ioMapping shape; taskHeaders?: Record<string, string>; documentation?: string; assignee?: string (Static assignee…); candidateGroups?: string (Candidate groups, comma-separated…); candidateUsers?: string (Candidate users, comma-separated…); dueDate?: string (Due date); followUpDate?: string (Follow-up date); priority?: number (Task priority 0-100, default 50…)
97
+ - MessageTaskOptions +El: multiInstance?: MultiInstanceOptions; messageName?: string; correlationKey?: string
98
+ - BusinessRuleTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; taskType?: string; decisionId?: string (DMN decision ID to evaluate); resultVariable?: string; documentation?: string
99
+ - CallActivityOptions: multiInstance?: MultiInstanceOptions; name?: string; processId: string (Process ID to call); propagateAllChildVariables?: boolean (Whether to propagate all child…); propagateAllParentVariables?: boolean (Whether the child process…); bindingType?: "latest" | "deployment" | "versionTag" (How the called process version is…); versionTag?: string (Version tag of the called…); ioMapping?: ioMapping shape; documentation?: string
100
+ - GatewayOptions +El: defaultFlow?: string (ID of the default sequence flow…)
101
+ - AdHocSubProcessOptions +El: activeElementsCollection?: string (FEEL expression for determining…); outputCollection?: string; outputElement?: string; taskDefinition?: {type: string; retries?: string} (Zeebe task definition…); ioMapping?: ioMapping shape; taskHeaders?: Record<string, string>; multiInstance?: MultiInstanceOptions; completionCondition?: string
102
+ - SubProcessOptions +El: multiInstance?: MultiInstanceOptions
103
+ - DataElementOptions: name?: string; isCollection?: boolean (Draws the collection…)
104
+ - AnnotateOptions: side?: "above" | "below" | "left" | "right" (Which side of the element…)
105
+ - BuildOptions: explicitJoins?: boolean (Refuse to infer join gateways, so…)
106
+ - ioMapping shape = {inputs?: Array<{source: string; target: string}>; outputs?: Array<{source: string; target: string}>}
107
+
108
+ ## Examples
109
+
110
+ ```typescript
111
+ import { Bpmn } from "@bpmnkit/core"
112
+
113
+ const definitions = Bpmn.createProcess("order")
114
+ .withAutoLayout()
115
+ .startEvent("start")
116
+ .serviceTask("charge", { name: "Charge card", taskType: "payments", retries: "3" })
117
+ .userTask("review", { name: "Review", assignee: "=reviewer" })
118
+ .scriptTask("total", { expression: "=price * qty", resultVariable: "total" })
119
+ .endEvent("end")
120
+ .build()
121
+ const xml = Bpmn.export(definitions)
122
+ ```
123
+
124
+ ```typescript
125
+ import { Bpmn } from "@bpmnkit/core"
126
+
127
+ const definitions = Bpmn.createProcess("approval")
128
+ .withAutoLayout()
129
+ .startEvent("start")
130
+ .exclusiveGateway("ok", { name: "Approved?" })
131
+ .branch("yes", (b) =>
132
+ b.condition("=approved").serviceTask("ship", { name: "Ship", taskType: "shipping" }).connectTo("end"),
133
+ )
134
+ .branch("no", (b) => b.defaultFlow().label("Rejected").endEvent("rejected"))
135
+ .endEvent("end")
136
+ .build()
137
+ const xml = Bpmn.export(definitions)
138
+ ```
139
+
140
+ ```typescript
141
+ import { Bpmn } from "@bpmnkit/core"
142
+
143
+ const definitions = Bpmn.createProcess("batch")
144
+ .withAutoLayout()
145
+ .startEvent("start")
146
+ .subProcess(
147
+ "each",
148
+ (sub) =>
149
+ sub
150
+ .startEvent("subStart")
151
+ .serviceTask("handle", { name: "Handle item", taskType: "handler" })
152
+ .endEvent("subEnd"),
153
+ { name: "Per item", multiInstance: { collection: "=items", elementVariable: "item" } },
154
+ )
155
+ .endEvent("end")
156
+ .build()
157
+ const xml = Bpmn.export(definitions)
158
+ ```
159
+
160
+ ```typescript
161
+ import { Bpmn } from "@bpmnkit/core"
162
+
163
+ const definitions = Bpmn.createProcess("sla")
164
+ .withAutoLayout()
165
+ .startEvent("start")
166
+ .serviceTask("work", { name: "Work", taskType: "worker" })
167
+ .withBoundary("late", { timerDuration: "PT1H", cancelActivity: false }, (b) =>
168
+ b.serviceTask("remind", { name: "Remind", taskType: "mailer" }).endEvent("reminded"),
169
+ )
170
+ .withBoundary("failed", { errorCode: "WORK_FAILED" }, (b) => b.endEvent("aborted"))
171
+ .endEvent("end")
172
+ .build()
173
+ const xml = Bpmn.export(definitions)
174
+ ```
175
+
176
+ ```typescript
177
+ import { Bpmn } from "@bpmnkit/core"
178
+
179
+ const definitions = Bpmn.createProcess("payment")
180
+ .withAutoLayout()
181
+ .startEvent("start", { messageName: "order-placed" })
182
+ .eventBasedGateway("wait")
183
+ .branch("paid", (b) =>
184
+ b
185
+ .intermediateCatchEvent("gotPayment", { messageName: "payment", correlationKey: "=orderId" })
186
+ .endEvent("done"),
187
+ )
188
+ .branch("late", (b) =>
189
+ b.intermediateCatchEvent("expired", { timerDuration: "P3D" }).endEvent("cancelled"),
190
+ )
191
+ .build()
192
+ const xml = Bpmn.export(definitions)
193
+ ```
194
+
195
+ ```typescript
196
+ import { Bpmn } from "@bpmnkit/core"
197
+
198
+ const definitions = Bpmn.createProcess("onboarding")
199
+ .withAutoLayout()
200
+ .startEvent("start")
201
+ .restConnector("lookup", {
202
+ name: "Look up customer",
203
+ method: "GET",
204
+ url: '="https://api.example.com/customers/" + customerId',
205
+ resultVariable: "customer",
206
+ })
207
+ .callActivity("kyc", { name: "KYC check", processId: "kyc-check", propagateAllChildVariables: true })
208
+ .endEvent("end")
209
+ .build()
210
+ const xml = Bpmn.export(definitions)
211
+ ```
@@ -148,6 +148,33 @@ function buildLaneShapes(lanes, nodes, dx, dy, poolY, poolHeaderWidth, laneConte
148
148
  return shape;
149
149
  });
150
150
  }
151
+ /**
152
+ * A view of `process` whose annotations and associations include those declared
153
+ * inside (nested) sub-processes. The builder stores them on the sub-process
154
+ * element, so packing only the process-level lists left them without a shape
155
+ * or edge. Layout nodes are already flat in diagram space, so one pass suffices.
156
+ */
157
+ function withNestedAnnotations(process) {
158
+ const textAnnotations = [...process.textAnnotations];
159
+ const associations = [...process.associations];
160
+ const walk = (elements) => {
161
+ for (const el of elements) {
162
+ const scope = el;
163
+ if (scope.textAnnotations)
164
+ textAnnotations.push(...scope.textAnnotations);
165
+ if (scope.associations)
166
+ associations.push(...scope.associations);
167
+ if (scope.flowElements)
168
+ walk(scope.flowElements);
169
+ }
170
+ };
171
+ walk(process.flowElements);
172
+ if (textAnnotations.length === process.textAnnotations.length &&
173
+ associations.length === process.associations.length) {
174
+ return process;
175
+ }
176
+ return { ...process, textAnnotations, associations };
177
+ }
151
178
  /** Also used by `expand`, which lays out one process without the pool handling above. */
152
179
  export function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, allEdges, dx, dy) {
153
180
  if (process.textAnnotations.length === 0 && process.associations.length === 0)
@@ -699,8 +726,9 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
699
726
  // they replace the proportional tiling below.
700
727
  const engineLanes = result.lanes;
701
728
  // Pre-compute annotation positions in layout space so they're included in the bbox
702
- const annBounds = process
703
- ? packAnnotations(process, result.nodes, result.edges, hints?.annotationSides)
729
+ const annProcess = process ? withNestedAnnotations(process) : undefined;
730
+ const annBounds = annProcess
731
+ ? packAnnotations(annProcess, result.nodes, result.edges, hints?.annotationSides)
704
732
  : new Map();
705
733
  const { minX, minY, maxX, maxY } = contentBbox(result.nodes, annBounds.values());
706
734
  const contentW = maxX - minX;
@@ -735,7 +763,7 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
735
763
  shapes.push(nodeToShape(node, dx, dy));
736
764
  for (const edge of result.edges)
737
765
  edges.push(edgeToShape(edge, dx, dy));
738
- addAnnotationShapes(process, result.nodes, annBounds, shapes, edges, dx, dy);
766
+ addAnnotationShapes(annProcess ?? process, result.nodes, annBounds, shapes, edges, dx, dy);
739
767
  rootPlanes.push({ elementId: process.id, shapes, edges });
740
768
  continue;
741
769
  }
@@ -744,7 +772,7 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
744
772
  for (const edge of result.edges)
745
773
  allEdges.push(edgeToShape(edge, dx, dy));
746
774
  if (process) {
747
- addAnnotationShapes(process, result.nodes, annBounds, allShapes, allEdges, dx, dy);
775
+ addAnnotationShapes(annProcess ?? process, result.nodes, annBounds, allShapes, allEdges, dx, dy);
748
776
  }
749
777
  if (participantId) {
750
778
  const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING + alignDx;
@@ -1,22 +1,33 @@
1
1
  import type { GridHint, LayoutHints } from "../layout/types.js";
2
2
  import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
3
3
  import type { RestConnectorConfig } from "./rest-connector.js";
4
+ import { type ZeebeLinkedResource, type ZeebeListener } from "./zeebe-extensions.js";
4
5
  /** Options shared by all element methods. */
5
6
  export interface ElementOptions {
6
7
  name?: string;
7
8
  isForCompensation?: boolean;
8
9
  /** Free-text documentation (`<bpmn:documentation>`). Used by the AI Agent connector as a tool description. */
9
10
  documentation?: string;
11
+ /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
12
+ executionListeners?: ZeebeListener[];
10
13
  }
11
14
  /** Options for send/receive task elements. */
12
15
  export interface MessageTaskOptions extends ElementOptions {
16
+ /** Runs the activity once per item of a list. */
17
+ multiInstance?: MultiInstanceOptions;
13
18
  /** Message name — generates or reuses a root <bpmn:message> and sets messageRef. */
14
19
  messageName?: string;
15
20
  /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). */
16
21
  correlationKey?: string;
17
22
  }
23
+ /** Variable change that re-evaluates a conditional event's condition. */
24
+ export type ConditionVariableEvent = "create" | "update";
18
25
  /** Options for creating a start event. */
19
26
  export interface StartEventOptions extends ElementOptions {
27
+ /** FEEL condition — creates a conditional start event (Camunda 8.9+). */
28
+ condition?: string;
29
+ /** Variable events that re-evaluate `condition` (`zeebe:conditionalFilter`); default is both. */
30
+ conditionVariableEvents?: ConditionVariableEvent[];
20
31
  /** Timer duration (ISO 8601) — creates a timer start event. */
21
32
  timerDuration?: string;
22
33
  /** Timer date (ISO 8601) — creates a timer start event. */
@@ -50,6 +61,10 @@ export interface StartEventOptions extends ElementOptions {
50
61
  }
51
62
  /** Options for creating a service task. */
52
63
  export interface ServiceTaskOptions {
64
+ /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
65
+ executionListeners?: ZeebeListener[];
66
+ /** Runs the activity once per item of a list. */
67
+ multiInstance?: MultiInstanceOptions;
53
68
  /** Display name (required for BPMN canvas visibility). */
54
69
  name: string;
55
70
  /** Zeebe job type for this task. */
@@ -78,6 +93,8 @@ export interface ServiceTaskOptions {
78
93
  agentDefinition?: {
79
94
  agentType: string;
80
95
  };
96
+ /** Resources the task runs, e.g. an RPA script (`zeebe:linkedResources`). */
97
+ linkedResources?: ZeebeLinkedResource[];
81
98
  /** Zeebe modeler template ID. */
82
99
  modelerTemplate?: string;
83
100
  /** Zeebe modeler template version. */
@@ -91,6 +108,10 @@ export interface ServiceTaskOptions {
91
108
  }
92
109
  /** Options for creating a script task. */
93
110
  export interface ScriptTaskOptions {
111
+ /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
112
+ executionListeners?: ZeebeListener[];
113
+ /** Runs the activity once per item of a list. */
114
+ multiInstance?: MultiInstanceOptions;
94
115
  /** Display name. */
95
116
  name?: string;
96
117
  /** FEEL expression for the script. */
@@ -104,10 +125,32 @@ export interface ScriptTaskOptions {
104
125
  }
105
126
  /** Options for creating a user task. */
106
127
  export interface UserTaskOptions {
128
+ /** Listeners on the user task's own lifecycle (`zeebe:taskListeners`); needs `zeebeUserTask`. */
129
+ taskListeners?: ZeebeListener[];
130
+ /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
131
+ executionListeners?: ZeebeListener[];
132
+ /** Runs the activity once per item of a list. */
133
+ multiInstance?: MultiInstanceOptions;
107
134
  /** Display name. */
108
135
  name?: string;
109
136
  /** Form key or form reference. */
110
137
  formId?: string;
138
+ /** Legacy form key (`zeebe:formDefinition formKey`), e.g. `camunda-forms:bpmn:<id>`. */
139
+ formKey?: string;
140
+ /** External form URL (`zeebe:formDefinition externalReference`); for a `zeebeUserTask`. */
141
+ externalReference?: string;
142
+ /** What `formId` resolves against; anything but `latest` needs Camunda 8.6+. */
143
+ formBindingType?: "latest" | "deployment" | "versionTag";
144
+ /** Version tag of the form; use with `formBindingType: "versionTag"`. */
145
+ formVersionTag?: string;
146
+ /**
147
+ * Embeds a Camunda Form: writes a process-level `zeebe:userTaskForm` holding `schema`
148
+ * (the form's JSON) and links it with `formKey="camunda-forms:bpmn:<id>"`.
149
+ */
150
+ embeddedForm?: {
151
+ id: string;
152
+ schema: string;
153
+ };
111
154
  /** Emit <zeebe:userTask /> to mark as a Camunda 8 native user task. */
112
155
  zeebeUserTask?: boolean;
113
156
  /** Input/output variable mappings. */
@@ -153,12 +196,44 @@ export interface UserTaskOptions {
153
196
  }
154
197
  /** Options for creating a call activity. */
155
198
  export interface CallActivityOptions {
199
+ /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
200
+ executionListeners?: ZeebeListener[];
201
+ /** Runs the activity once per item of a list. */
202
+ multiInstance?: MultiInstanceOptions;
156
203
  /** Display name. */
157
204
  name?: string;
158
205
  /** Process ID to call. */
159
206
  processId: string;
160
- /** Whether to propagate all child variables. */
207
+ /** Whether to propagate all child variables back to the parent on completion. */
161
208
  propagateAllChildVariables?: boolean;
209
+ /**
210
+ * Whether the child process receives all parent variables (default true in the engine).
211
+ * Set `false` to pass only `ioMapping` inputs; `false` needs Camunda 8.2+.
212
+ */
213
+ propagateAllParentVariables?: boolean;
214
+ /**
215
+ * How the called process version is resolved: the `latest` deployed version, the version
216
+ * deployed together with this process (`deployment`), or by `versionTag`. Needs Camunda 8.6+.
217
+ */
218
+ bindingType?: "latest" | "deployment" | "versionTag";
219
+ /** Version tag of the called process; only meaningful with `bindingType: "versionTag"`. */
220
+ versionTag?: string;
221
+ /** Input/output variable mappings between parent and child scope. */
222
+ ioMapping?: {
223
+ inputs?: Array<{
224
+ source: string;
225
+ target: string;
226
+ }>;
227
+ outputs?: Array<{
228
+ source: string;
229
+ target: string;
230
+ }>;
231
+ };
232
+ /** Zeebe property key-value pairs (`zeebe:properties`/`zeebe:property`). */
233
+ zeebeProperties?: Array<{
234
+ name: string;
235
+ value: string;
236
+ }>;
162
237
  /** Mark this activity as a compensation handler. */
163
238
  isForCompensation?: boolean;
164
239
  /** Free-text documentation (`<bpmn:documentation>`). */
@@ -166,6 +241,10 @@ export interface CallActivityOptions {
166
241
  }
167
242
  /** Options for creating a business rule task. */
168
243
  export interface BusinessRuleTaskOptions {
244
+ /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
245
+ executionListeners?: ZeebeListener[];
246
+ /** Runs the activity once per item of a list. */
247
+ multiInstance?: MultiInstanceOptions;
169
248
  /** Display name. */
170
249
  name?: string;
171
250
  /** Zeebe job type. */
@@ -240,6 +319,10 @@ export interface IntermediateCatchEventOptions extends ElementOptions {
240
319
  * connected from the current position.
241
320
  */
242
321
  linkName?: string;
322
+ /** FEEL condition — creates a conditional catch event (Camunda 8.9+). */
323
+ condition?: string;
324
+ /** Variable events that re-evaluate `condition` (`zeebe:conditionalFilter`); default is both. */
325
+ conditionVariableEvents?: ConditionVariableEvent[];
243
326
  }
244
327
  /** Options for an intermediate throw event. */
245
328
  export interface IntermediateThrowEventOptions extends ElementOptions {
@@ -297,12 +380,20 @@ export interface BoundaryEventOptions extends ElementOptions {
297
380
  signalName?: string;
298
381
  /** Creates a compensation boundary event. */
299
382
  compensation?: boolean;
383
+ /** FEEL condition — creates a conditional boundary event (Camunda 8.9+). */
384
+ condition?: string;
385
+ /** Variable events that re-evaluate `condition` (`zeebe:conditionalFilter`); default is both. */
386
+ conditionVariableEvents?: ConditionVariableEvent[];
300
387
  }
301
388
  /** Multi-instance loop configuration. */
302
389
  export interface MultiInstanceOptions {
303
390
  isSequential?: boolean;
304
391
  collection?: string;
305
392
  elementVariable?: string;
393
+ /** Variable that collects each instance's output element (`zeebe:loopCharacteristics`). */
394
+ outputCollection?: string;
395
+ /** FEEL expression evaluated per instance and appended to `outputCollection`. */
396
+ outputElement?: string;
306
397
  completionCondition?: string;
307
398
  }
308
399
  /** Options for sub-process elements. */
@@ -372,13 +463,20 @@ export interface AdHocSubProcessOptions extends ElementOptions {
372
463
  */
373
464
  toolGrid?: GridHint;
374
465
  }
466
+ /** Options for `dataObject()` / `dataObjectReference()`. */
467
+ export interface DataElementOptions {
468
+ name?: string;
469
+ /** Draws the collection (parallel-bars) marker. */
470
+ isCollection?: boolean;
471
+ }
375
472
  /** Options for `annotate()`. */
376
473
  export interface AnnotateOptions {
377
474
  /**
378
475
  * Which side of the element `withAutoLayout()` puts the annotation on,
379
- * instead of the side it would choose. Layout only; not written to the XML.
476
+ * instead of the side it would choose. `"left"` / `"right"` put it beside
477
+ * the element, preferably level with its centre. Layout only; not written to the XML.
380
478
  */
381
- side?: "above" | "below";
479
+ side?: "above" | "below" | "left" | "right";
382
480
  }
383
481
  /**
384
482
  * The root-level messages, errors, signals and escalations of one process.
@@ -461,6 +559,14 @@ export declare class BranchBuilder {
461
559
  get _lastNodeId(): string | undefined;
462
560
  /** @internal – Open ends of nested branches that have not yet been connected. */
463
561
  get _openBranchEnds(): string[];
562
+ /** Declares a data object. Link it to an activity via a `dataObjectReference()`. */
563
+ dataObject(id: string, options?: DataElementOptions): this;
564
+ /** Draws a reference to the data object `dataObjectRef`. */
565
+ dataObjectReference(id: string, dataObjectRef: string, options?: DataElementOptions): this;
566
+ /** Draws a reference to the data store `dataStoreRef`. */
567
+ dataStoreReference(id: string, dataStoreRef: string, options?: Pick<DataElementOptions, "name">): this;
568
+ /** Links an activity to a data reference: `input` reads it, `output` writes it. */
569
+ dataAssociation(activityId: string, dataRefId: string, direction: "input" | "output"): this;
464
570
  /** Attach a text annotation to the element at the current cursor position. */
465
571
  textAnnotation(text: string): this;
466
572
  /** Attach a text annotation to an element by explicit ID. */
@@ -593,6 +699,14 @@ export declare class SubProcessContentBuilder {
593
699
  inclusiveGateway(id: string, options?: GatewayOptions): this;
594
700
  eventBasedGateway(id: string, options?: ElementOptions): this;
595
701
  complexGateway(id: string, options?: GatewayOptions): this;
702
+ /** Declares a data object. Link it to an activity via a `dataObjectReference()`. */
703
+ dataObject(id: string, options?: DataElementOptions): this;
704
+ /** Draws a reference to the data object `dataObjectRef`. */
705
+ dataObjectReference(id: string, dataObjectRef: string, options?: DataElementOptions): this;
706
+ /** Draws a reference to the data store `dataStoreRef`. */
707
+ dataStoreReference(id: string, dataStoreRef: string, options?: Pick<DataElementOptions, "name">): this;
708
+ /** Links an activity to a data reference: `input` reads it, `output` writes it. */
709
+ dataAssociation(activityId: string, dataRefId: string, direction: "input" | "output"): this;
596
710
  /** Attach a text annotation to the element at the current cursor position. */
597
711
  textAnnotation(text: string): this;
598
712
  /** Attach a text annotation to an element by explicit ID. */
@@ -906,6 +1020,14 @@ export declare class ProcessBuilder {
906
1020
  transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
907
1021
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
908
1022
  eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
1023
+ /** Declares a data object. Link it to an activity via a `dataObjectReference()`. */
1024
+ dataObject(id: string, options?: DataElementOptions): this;
1025
+ /** Draws a reference to the data object `dataObjectRef`. */
1026
+ dataObjectReference(id: string, dataObjectRef: string, options?: DataElementOptions): this;
1027
+ /** Draws a reference to the data store `dataStoreRef`. */
1028
+ dataStoreReference(id: string, dataStoreRef: string, options?: Pick<DataElementOptions, "name">): this;
1029
+ /** Links an activity to a data reference: `input` reads it, `output` writes it. */
1030
+ dataAssociation(activityId: string, dataRefId: string, direction: "input" | "output"): this;
909
1031
  /** Attach a text annotation to the element at the current cursor position. */
910
1032
  textAnnotation(text: string): this;
911
1033
  /** Attach a text annotation to any flow element by explicit ID. */