@bpmnkit/core 1.14.0 → 1.16.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 (44) hide show
  1. package/AGENTS.md +5 -4
  2. package/agent-cards/bpmn.md +86 -80
  3. package/builder-reference.md +27 -8
  4. package/dist/bpmn/auto-layout.js +235 -42
  5. package/dist/bpmn/bpmn-builder.d.ts +171 -17
  6. package/dist/bpmn/bpmn-builder.js +792 -135
  7. package/dist/bpmn/bpmn-model.d.ts +15 -0
  8. package/dist/bpmn/bpmn-parser.js +32 -6
  9. package/dist/bpmn/bpmn-serializer.js +9 -2
  10. package/dist/bpmn/compact-stream.d.ts +7 -0
  11. package/dist/bpmn/compact-stream.js +7 -0
  12. package/dist/bpmn/compact.d.ts +126 -9
  13. package/dist/bpmn/compact.js +305 -30
  14. package/dist/bpmn/full-operations.d.ts +19 -0
  15. package/dist/bpmn/full-operations.js +191 -7
  16. package/dist/bpmn/make-room.d.ts +26 -0
  17. package/dist/bpmn/make-room.js +151 -0
  18. package/dist/bpmn/optimize/flow.js +8 -0
  19. package/dist/bpmn/place-new-shapes.d.ts +6 -1
  20. package/dist/bpmn/place-new-shapes.js +53 -2
  21. package/dist/bpmn/preserving-writer.d.ts +1 -1
  22. package/dist/bpmn/preserving-writer.js +1 -1
  23. package/dist/bpmn/process-delta.d.ts +32 -1
  24. package/dist/bpmn/process-delta.js +62 -1
  25. package/dist/bpmn/process-text-writer.d.ts +18 -7
  26. package/dist/bpmn/process-text-writer.js +105 -22
  27. package/dist/bpmn/process-text.d.ts +34 -2
  28. package/dist/bpmn/process-text.js +410 -7
  29. package/dist/bpmn/swimlanes.d.ts +178 -0
  30. package/dist/bpmn/swimlanes.js +774 -0
  31. package/dist/form/user-task-forms.d.ts +45 -0
  32. package/dist/form/user-task-forms.js +129 -0
  33. package/dist/index.d.ts +9 -4
  34. package/dist/index.js +5 -2
  35. package/dist/layout/collaboration/message-labels.d.ts +25 -0
  36. package/dist/layout/collaboration/message-labels.js +108 -0
  37. package/dist/layout/collaboration/ordering.d.ts +5 -1
  38. package/dist/layout/collaboration/ordering.js +24 -9
  39. package/dist/layout/semantic/graph.js +3 -0
  40. package/dist/layout/semantic/place.d.ts +2 -0
  41. package/dist/layout/semantic/place.js +77 -9
  42. package/dist/xml/xml-patch.d.ts +1 -1
  43. package/llms.txt +1 -1
  44. package/package.json +2 -2
package/AGENTS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @bpmnkit/core for agents
2
2
 
3
- Do not read README.md (20 KB) or the .d.ts files first. Read the one card for your task (~1k tokens each). Each has a runnable script, the top options and the known traps.
3
+ Read this file and the one card for your task once (~2k tokens each; `casen agent-card <bpmn|dmn|form>` prints the same cards). The card is self-sufficient: do not read README.md (20 KB) and do not search `dist/*.d.ts`. BPMN: write a short spec with the Write tool and run one command, `casen build <spec> --deploy` (`@bpmnkit/cli`; `npx casen` if not on PATH); it writes the .bpmn and its forms, lints and deploys.
4
4
 
5
5
  | You write | Read |
6
6
  | --- | --- |
@@ -10,10 +10,11 @@ Do not read README.md (20 KB) or the .d.ts files first. Read the one card for yo
10
10
 
11
11
  Rules that hold for all three:
12
12
 
13
- - Build with the builders (`Bpmn`, `Dmn`, `Form`). Never write XML or form JSON by hand.
14
- - Edit an existing file with `Bpmn.parse` and the `export*Preserving` writers, so layout and formatting stay.
13
+ - New BPMN: a `casen build` text spec (one pool, or `## Pool` sections with lanes, message flows, data). DMN and forms: the builders (`Dmn`, `Form`). Never write a whole file by hand.
14
+ - Edit an existing BPMN file: an edit module, `casen build edit.mjs --edit order.bpmn` (layout kept). DMN/forms: the `export*Preserving` writers.
15
15
  - `formId` and `decisionId` must equal the deployed form id and decision id exactly.
16
- - Validate before you finish: `npx @bpmnkit/cli check order.bpmn risk.dmn review.form --deploy` (`casen check` if the CLI is installed). Fix every error.
16
+ - One gate: `casen build` lints like c8ctl (bpmnlint + camunda-compat) and prints the rule's `.bpmnlintrc` key; a task-named command is the final word. Fix every error.
17
+ - Done = gate clean + deploy succeeds. Stop there and answer in one line: never hand-route DI or render images.
17
18
  - Builder errors and check findings end with `agent-cards/<type>.md#traps`. Read that section.
18
19
 
19
20
  The full API reference is `builder-reference.md` in this folder. Open it only when a card does not cover an option.
@@ -1,94 +1,100 @@
1
1
  # BPMN agent card
2
2
 
3
- Write a Camunda 8 BPMN process with `@bpmnkit/core` in one script: create, export, edit, validate. Run it with `node --experimental-strip-types build.ts` (Node 22.6+) or `npx tsx build.ts`. Never write BPMN XML by hand.
4
-
5
- <!-- docspack: tags=agent-card,cheat-sheet,build-script,bpmn,process,create,write,script,builder -->
6
-
7
- ## Minimal BPMN build script: create, export, edit, validate
8
-
9
- ```ts
10
- import { readFileSync, writeFileSync } from "node:fs"
11
- import { Bpmn, exportPreserving, lintDiagram, placeNewShapes } from "@bpmnkit/core"
12
-
13
- // 1. Create. The process id is the deploy key: same id = new version of that process.
14
- const definitions = Bpmn.createProcess("order")
15
- .name("Order")
16
- .withAutoLayout()
17
- .startEvent("received", { name: "Order received" })
18
- .businessRuleTask("score", { name: "Score risk", decisionId: "risk", resultVariable: "risk" })
19
- .exclusiveGateway("check", { name: "Risky?" })
20
- .branch("yes", (b) =>
21
- b
22
- .condition('=risk = "high"')
23
- .label("Yes")
24
- .userTask("review", { name: "Review order", formId: "review-order", zeebeUserTask: true })
25
- .connectTo("ship"),
26
- )
27
- .branch("no", (b) => b.defaultFlow().label("No").connectTo("ship"))
28
- .serviceTask("ship", { name: "Ship order", taskType: "ship-order", retries: "3" })
29
- .endEvent("done", { name: "Order shipped" })
30
- .build()
31
-
32
- // 2. Export.
33
- writeFileSync("order.bpmn", Bpmn.export(definitions))
34
-
35
- // 3. Edit an existing file: change the model, draw only the new elements, write with
36
- // exportPreserving. Existing shapes keep their positions and the file its formatting.
37
- const original = readFileSync("order.bpmn", "utf8")
38
- const edited = Bpmn.continueProcess(Bpmn.parse(original), "order")
39
- .insertAfter("ship")
40
- .serviceTask("notify", { name: "Notify customer", taskType: "notify-customer" })
41
- .build()
42
- const ship = edited.processes[0]?.flowElements.find((e) => e.id === "ship")
43
- if (ship) ship.name = "Ship parcel"
44
- const { definitions: drawn, unplaced } = placeNewShapes(edited)
45
- if (unplaced.length > 0) console.log("not drawn:", unplaced)
46
- writeFileSync("order.bpmn", exportPreserving(original, drawn))
47
-
48
- // 4. Validate: Camunda 8 deployability and modelling rules.
49
- const report = lintDiagram(Bpmn.parse(readFileSync("order.bpmn", "utf8")))
50
- for (const d of report.diagnostics.filter((d) => d.severity !== "info"))
51
- console.log(`${d.severity} ${d.elementIds.join(",")}: ${d.message}`)
52
- if (report.counts.error > 0) process.exit(1)
53
- ```
3
+ Self-sufficient (no `dist/*.d.ts` search). Do not plan in prose or read other docs: write the spec directly with the Write tool from the template that fits, run `casen build <spec>` once, fix what it reports.
54
4
 
55
- `npm i @bpmnkit/core`. The script writes `order.bpmn`, re-opens it, adds a task and renames one without moving a shape, and exits 1 on a lint error.
5
+ `casen build` writes the laid-out `.bpmn` and a `.form` per user task, lints like c8ctl and, with `--deploy`, deploys them.
56
6
 
57
- ## Top builder options
7
+ <!-- docspack: tags=agent-card,cheat-sheet,build,build-script,bpmn,process,create,write,script,builder,edit,casen-build,sub-process,annotation,conditional,text-spec,collaboration,pools,lanes,message-flow,data-object,form -->
58
8
 
59
- - `Bpmn.createProcess(id)` … `.build()`; `.withAutoLayout()` before `.build()`, or the file has no shapes.
60
- - Every element takes `(id, options)`; ids are unique and each element connects to the previous one.
61
- - `serviceTask(id, { name, taskType, retries, ioMapping: { inputs, outputs }, taskHeaders })`: `taskType` is the job type a worker subscribes to.
62
- - `userTask(id, { name, zeebeUserTask: true, formId, assignee, candidateGroups, dueDate })`.
63
- - `businessRuleTask(id, { decisionId, resultVariable })`: both are required to deploy.
64
- - `scriptTask(id, { expression: "=a + b", resultVariable })`; `callActivity(id, { processId })`.
65
- - Gateways: `.exclusiveGateway(id)` then `.branch(name, (b) => b.condition("=x > 1")...)`, one branch `b.defaultFlow()`; `.label(text)` sets the flow label. Merge with `.connectTo(id)` and declare that id after the last branch.
66
- - Events take named options: `timerDuration: "PT1H"`, `messageName` + `correlationKey`, `errorCode`, `signalName`. `.withBoundary(id, { errorCode }, (b) => ...)` hangs a boundary on the previous task.
67
- - `multiInstance: { collection: "=items", elementVariable: "item" }` on any task.
68
- - Full method list: `packages/core/builder-reference.md` in `@bpmnkit/core`, or `npx bpmnkit-docs ask "<option>"`.
9
+ | Task | Write | Run |
10
+ | --- | --- | --- |
11
+ | New process, one pool | `order.txt` (template 1) | `casen build order.txt --deploy` |
12
+ | Pools, lanes, message flows, data | `shop.txt` (template 2) | `casen build shop.txt --deploy` |
13
+ | Change an existing `.bpmn` | `edit.mjs` (template 3) | `casen build edit.mjs --edit order.bpmn --deploy` |
69
14
 
70
- ## Traps
15
+ - Success is one line: `✓ order.bpmn + 2 forms (…) · lint clean · process order, tasks 4, gateways 2, forms 2 · Camunda 8.10.0`. It is the proof: do not inspect the XML. Otherwise one `✖` line per problem: fix the spec, run again.
16
+ - After ✓: run the task's gate commands as given (one per Bash call), deploy the `.bpmn` plus the listed `.form` files, answer in one line. The layout is final: never move DI by hand or render images.
17
+ - Write files with the Write tool, not heredocs. `-o out.bpmn` sets the output. `.dmn`/`.form` files after the spec are linted and deployed with it.
18
+ - `--deploy` goes to `ZEEBE_REST_ADDRESS` (+ the `CAMUNDA_*` client variables), else the casen profile, else local Reebe. No `casen` on PATH? `npm i -D @bpmnkit/cli`, then `npx casen …`.
71
19
 
72
- - **Camunda 8.10 is the default target.** To target an older cluster, call `.executionPlatformVersion("8.8.0")` so lint checks that version.
73
- - **User tasks default to job-worker tasks**, which 8.10 deprecates. Pass `zeebeUserTask: true` for a Camunda user task.
74
- - **Deploy ids.** The engine keys a process by its process id (`createProcess("order")`), a decision by its `<decision id>`, a form by its JSON `id`. File names and display names do not count. `formId` and `decisionId` must equal those ids exactly; by default they bind to the latest deployed version, so deploy the `.dmn` and `.form` before an instance reaches the task. Redeploying the same id makes a new version.
75
- - **Reference a DMN decision by its decision id**, not the DMN `definitions` id, the file name or the decision name.
76
- - **Edit with the preserving writer.** For an existing file, `Bpmn.parse` it (or `Bpmn.continueProcess(parsed, processId)`), change the model, run `placeNewShapes(edited)` so the new elements get shapes next to what they connect to, and write `exportPreserving(original, drawn)`. Existing shapes stay put; a pool, lane or sub-process only grows when the new shapes do not fit. Rebuilding with `withAutoLayout()`, `applyAutoLayout`, or `Bpmn.export` alone moves every shape and reformats the diff. `placeNewShapes` does not draw new lanes; it lists them in `unplaced`.
77
- - FEEL in the builder starts with `=` (`"=amount > 1000"`); a value without `=` is a literal string.
78
- - Unknown option names are silently dropped: `timer: { duration }` does nothing; use `timerDuration`.
20
+ ## 1. One pool
79
21
 
80
- - **`build()`, `expand()` and `Bpmn.export` refuse what Camunda 8 cannot deploy**: a gateway branch without `condition`/`defaultFlow`, a task or message throw/end event without `taskType`, a message without name or `correlationKey`, a timer without a time, anything after an end event. The `DeployabilityError` message has one line per problem, `- <id>: <message> (zeebe/<rule>)`: fix each. `{ placeholders: true }` fills documented values to replace before deploying; `{ validate: false }` only for a draft.
22
+ ```text
23
+ # Expense approval | id=expense
24
+ [start Expense submitted] > [user Review expense] > [xor Approved?]
25
+ Approved? >(Yes: approved = true) [service Pay expense] > [end Expense paid]
26
+ Approved? >(No: default) [user Rework expense] > Review expense
27
+ [boundary:error Payment failed | on=payExpense error=PAY_FAILED] > [send Notify submitter] > [end Submitter notified]
28
+ ```
81
29
 
82
- ## Lint before you deploy or test
30
+ - `# Name | id=<process id>`: the process id is the deploy key. `camunda=8.8` for an older cluster (default 8.10).
31
+ - `a > b > c` is a path. Declare a node once: `[kind Name | attrs]`; its id is the name in camelCase (`[user Review expense]` is `reviewExpense`), or write `id[kind Name]`. Later write its id or its exact name. A path that stops gets an end event.
32
+ - Kinds: `start end task user service rule send receive script manual call sub xor and or eventgw catch throw boundary adhoc`. Triggers: `<event kind>:message|timer|condition|error|signal|escalation|terminate`, e.g. `start:timer`, `boundary:error`, `end:message`.
33
+ - Decision: `gw >(Label: FEEL condition) x` per branch, exactly one `gw >(Label: default) y`. Branches that meet are joined for you; parallel work: `and` split, `and` join.
34
+ - Forms: a user task without `fields=` gets a field per variable the next decisions read (`approved = true` → checkbox, `amount > 1000` → number, `risk = "low"` → select). `fields=key[:number|checkbox|textarea|date|select(a|b)],…` sets them; `form=<id>` links your own.
35
+ - Defaults: `job=` (service, send, message end) is the id kebab-cased (`pay-expense`); `msg=` is the name kebab-cased. Other attributes: `key=<FEEL>` (every message caught after the start) · `after=PT1H`, `every=R/PT1H`, `at=2026-01-31T09:00:00Z` (a timer start takes only a literal date; `catch:timer at==<FEEL>` a variable) · `cond=<FEEL>` (last) · `error=`, `signal=`, `escalation=` · `on=<task id>`, `nonint` (boundary) · `result=<var>` · `called=<process id>` · `each=<list var>` · `in.x=`, `out.x=` · `feel=<FEEL>` (script, last) · `retries=3`, `header.k=v` · `assignee=` `groups=a;b` `users=` `due=P2D` `priority=0-100`.
36
+ - A rule task calls `decision=<id>`, default its name kebab-cased (`[rule Assess risk]` calls `assess-risk`). Pass the `.dmn` too: `casen build order.txt risk.dmn --deploy`.
37
+
38
+ ## 2. Pools, lanes, message flows, data
39
+
40
+ ```text
41
+ # Order fulfilment
42
+ [annotation Orders ship within two days]
43
+ ## Shop | id=shop
44
+ ### Sales
45
+ [start:message Order placed] > [service Check stock] > [send Request payment]
46
+ Request payment > [catch Payment received | key=orderId] > [sub Pack order]
47
+ Pack order {
48
+ [start Packing started] > [user Pick item | each=items] > [user Box items] > [end Packed]
49
+ }
50
+ ### Warehouse
51
+ Pack order > [user Ship order] > [end Order shipped]
52
+ Check stock ..> [store Stock DB]
53
+ Ship order ..> [object Packing slip]
54
+ [annotation Fragile items get extra padding] ..> Pack order
55
+ ## Restock | id=restock
56
+ [start:condition Stock low | cond=stock < 10] > [service Reorder stock] > [end Stock reordered]
57
+ ## Bank | blackbox
58
+ ## Customer | blackbox
59
+ Customer ~> Order placed: Order
60
+ Request payment ~> Bank: Payment request
61
+ Bank ~> Payment received: Payment confirmed
62
+ ```
83
63
 
84
- ```sh
85
- casen check order.bpmn risk.dmn review-order.form --deploy # one gate: BPMN + DMN + forms, and the ids that link them
86
- casen lint lint order.bpmn --profile deploy # BPMN only, errors only
87
- casen deploy deploy order.bpmn # gated first; local Reebe, --target camunda8 for a cluster
64
+ - `## Name | id=<process id>` starts a pool with its own process; `## Name | blackbox` a partner pool (id: `id=` or the name kebab-cased).
65
+ - `### Lane`: nodes declared after it go in that lane; repeat a header to switch back.
66
+ - `a ~> b: label` is a message flow between nodes or pools (ids or names) of different pools. A plain `start` it reaches becomes a message start. A same-name `store` in several pools is one data store.
67
+ - `[object Name] ..> task`: the task reads it; `task ..> [store Name]`: it writes it. `objects` marks a collection.
68
+ - `[sub Name]`, then `Name {`, its paths (own start and end), `}`: an expanded sub-process. Bodies nest.
69
+ - `[annotation Text]`: on the collaboration before the first `##`; `[annotation Text] ..> task` links it. Ids are global across pools.
70
+
71
+ ## 3. Edit an existing file
72
+
73
+ ```js
74
+ // Insert a step after "reviewExpense" with an error path that loops back to it.
75
+ export default (kit, model) =>
76
+ kit.Bpmn.continueProcess(model, "expense")
77
+ .insertAfter("reviewExpense")
78
+ .serviceTask("validate", { name: "Validate receipt", taskType: "validate-receipt" })
79
+ .withBoundary("invalid", { name: "Receipt invalid", errorCode: "INVALID" }, (b) =>
80
+ b.userTask("fix", { name: "Fix receipt" }).connectTo("validate"),
81
+ )
88
82
  ```
89
83
 
90
- In code, `lintDiagram(definitions)` returns `{ diagnostics, counts }`; fail on `counts.error > 0`. Warnings (no timer boundary, no output mapping) are advice.
84
+ `--edit order.bpmn` rewrites it in place: existing shapes and forms stay, shapes right of the insertion move only as needed, new user tasks get forms. `--camunda 8.10` sets `executionPlatformVersion`. `kit` is `@bpmnkit/core`, `model` the parsed file.
91
85
 
92
- ## Writing a process as text instead
86
+ - `continueProcess(model, processId)`: `.insertAfter(id)` splices in after `id`; `.at(id)` continues from a node without outgoing flow.
87
+ - Steps: `serviceTask(id, { name, taskType })` · `userTask(id, { name, formId, assignee, candidateGroups })` · `intermediateCatchEvent(id, { name, messageName, correlationKey: "=orderId" })` or `{ timerDuration: "PT1H" }` · `endEvent(id, { name })` · `.connectTo(id)`.
88
+ - Decision: `.exclusiveGateway(id, { name }).branch("yes", (b) => b.condition("=x > 1").label("Yes")…).branch("no", (b) => b.defaultFlow().label("No")…)`. Boundary: `.withBoundary(id, { errorCode } | { timerDuration } | { messageName, correlationKey }, (b) => …)`.
89
+ - One attribute: change `model` and return it. Builder FEEL starts with `=`; text-spec conditions do not.
90
+
91
+ ## Not in the text spec
92
+
93
+ Event sub-processes, transactions, compensation, groups, nested lanes: write `flow.mjs`, `export default (kit) => kit.Bpmn.createProcess("id")…` (pools: `createDiagram`; `.eventSubProcess(id, (b) => …)`, `.transaction(…)`), run `casen build flow.mjs`.
94
+
95
+ ## Traps
93
96
 
94
- A model writing the diagram itself can use the line format: `parseProcessText(text)` then `expand(result.diagram)` from `@bpmnkit/core`; `expand` throws the same gate message, naming what to add (`msg=`, `key=`, `every=`, …). `casen agent-card bpmn --text` prints its guide. Related cards: `casen agent-card dmn`, `casen agent-card form`.
97
+ - A finding reads `✖ order.bpmn pay: <message> [<rule id>, .bpmnlintrc "<key>"]`: the key is c8ctl's rule name. Fix the model; do not silence rules unless the task says so.
98
+ - `formId` and decision ids must equal the deployed form's and decision's ids. Generated forms already do; a hand-written `.form` next to the output is used instead.
99
+ - A message caught after the start needs `key=`; a message start does not. An `eventgw` is followed only by catch events.
100
+ - `casen build` refuses what Camunda 8 cannot deploy, one line per problem, `- <id>: <message> (zeebe/<rule>)`, and writes nothing.
@@ -71,6 +71,7 @@ Other:
71
71
  - dataObjectReference(id: string, dataObjectRef: string, options?: DataElementOptions)
72
72
  - dataStoreReference(id: string, dataStoreRef: string, options?: Pick<DataElementOptions, "name">)
73
73
  - dataAssociation(activityId: string, dataRefId: string, direction: "input" | "output")
74
+ - inLane(id: string, options?: LaneOptions)
74
75
 
75
76
  Only inside `.branch()` callbacks (BranchBuilder), applied to the flow leaving the gateway:
76
77
  - condition(expression: string)
@@ -84,29 +85,47 @@ Not available inside callbacks (top-level only): at, insertAfter, withAutoLayout
84
85
 
85
86
  `+El` = also accepts the ElementOptions fields; `+X` = also accepts X's fields.
86
87
 
87
- - ElementOptions: name?: string; documentation?: string (Free-text documentation…)
88
+ - ElementOptions: name?: string; lane?: string (Lane of this node only,…); documentation?: string (Free-text documentation…)
88
89
  - 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); correlationKey?: string (FEEL expression correlating the…); formId?: string (Form to show when the process is…); isInterrupting?: boolean (Non-interrupting flag)
89
- - EndEventOptions +El: errorCode?: string (Error code); messageName?: string; signalName?: string (Signal name); escalationCode?: string (Escalation code); taskType?: string (Job type of the worker that…)
90
- - IntermediateThrowEventOptions +El: messageName?: string; signalName?: string; escalationCode?: string; compensation?: boolean (Emit a compensateEventDefinition); linkName?: string (Link name); taskType?: string
90
+ - EndEventOptions +El: errorCode?: string (Error code); messageName?: string; correlationKey?: string; signalName?: string (Signal name); escalationCode?: string (Escalation code); taskType?: string (Job type of the worker that…)
91
+ - IntermediateThrowEventOptions +El: messageName?: string; correlationKey?: string; signalName?: string; escalationCode?: string; compensation?: boolean (Emit a compensateEventDefinition); linkName?: string (Link name); taskType?: string
91
92
  - IntermediateCatchEventOptions +El: timerDuration?: string; timerDate?: string; timerCycle?: string; messageName?: string; correlationKey?: string; signalName?: string; linkName?: string; condition?: string
92
93
  - 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
93
- - ServiceTaskOptions: multiInstance?: MultiInstanceOptions (Runs the activity once per item…); name: string; taskType: string; 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
94
+ - ServiceTaskOptions: lane?: string; multiInstance?: MultiInstanceOptions (Runs the activity once per item…); name: string; taskType: string; 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
94
95
  - MultiInstanceOptions: isSequential?: boolean; collection?: string; elementVariable?: string; outputCollection?: string (Variable that collects each…); outputElement?: string (FEEL expression evaluated per…); completionCondition?: string
95
96
  - 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…)
96
- - ScriptTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; expression: string (FEEL expression for the script); resultVariable: string; documentation?: string
97
- - 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
+ - ScriptTaskOptions: lane?: string; multiInstance?: MultiInstanceOptions; name?: string; expression: string (FEEL expression for the script); resultVariable: string; documentation?: string
98
+ - UserTaskOptions: lane?: string; 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…)
98
99
  - SendTaskOptions +MessageTaskOptions: taskType?: string
99
100
  - MessageTaskOptions +El: multiInstance?: MultiInstanceOptions; messageName?: string; correlationKey?: string
100
- - BusinessRuleTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; taskType?: string; decisionId?: string (DMN decision ID to evaluate); resultVariable?: string; documentation?: string
101
- - 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
101
+ - BusinessRuleTaskOptions: lane?: string; multiInstance?: MultiInstanceOptions; name?: string; taskType?: string; decisionId?: string (DMN decision ID to evaluate); resultVariable?: string; documentation?: string
102
+ - CallActivityOptions: lane?: string; 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
102
103
  - GatewayOptions +El: defaultFlow?: string (ID of the default sequence flow…)
103
104
  - 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
104
105
  - SubProcessOptions +El: multiInstance?: MultiInstanceOptions
105
106
  - DataElementOptions: name?: string; isCollection?: boolean (Draws the collection…)
106
107
  - AnnotateOptions: side?: "above" | "below" | "left" | "right" (Which side of the element…)
107
108
  - BuildOptions: validate?: boolean (Refuse a Camunda 8 model Zeebe…); explicitJoins?: boolean (Refuse to infer join gateways, so…)
109
+ - LaneOptions: name?: string
108
110
  - ioMapping shape = {inputs?: Array<{source: string; target: string}>; outputs?: Array<{source: string; target: string}>}
109
111
 
112
+ ## DiagramBuilder (pools, message flows)
113
+
114
+ `Bpmn.createDiagram(id?)`: several processes in one file. Call `.withAutoLayout()` before `.build()` to draw shapes. Omit `processId` on `participant` for a black-box pool. Lanes go on each process (`inLane()`).
115
+
116
+ - executionPlatformVersion(version: string)
117
+ - process(id: string, callback: (b: ProcessBuilder) => void)
118
+ - collaborationId(id: string)
119
+ - participant(id: string, options: ParticipantOptions)
120
+ - message(id: string, options: DiagramMessageOptions)
121
+ - messageFlow(id: string, options: MessageFlowOptions)
122
+ - withAutoLayout()
123
+ - build(options?: BuildGateOptions)
124
+
125
+ - ParticipantOptions: name?: string (Pool label); processId?: string (Id of the process this pool…)
126
+ - DiagramMessageOptions: name?: string; correlationKey?: string (FEEL expression Camunda 8…)
127
+ - MessageFlowOptions: source: string (Id of the participant, or of a…); target: string (Id of the participant, or of a…); name?: string; messageRef?: string (Id of a message declared with…)
128
+
110
129
  ## Examples
111
130
 
112
131
  ```typescript