@bpmnkit/core 1.6.1 → 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 (40) 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 +83 -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/strip-camunda8.d.ts +22 -0
  19. package/dist/bpmn/strip-camunda8.js +55 -0
  20. package/dist/bpmn/utils.js +151 -1
  21. package/dist/bpmn/zeebe-extensions.d.ts +59 -2
  22. package/dist/bpmn/zeebe-extensions.js +89 -1
  23. package/dist/connectors/apply-element.d.ts +7 -3
  24. package/dist/connectors/apply-element.js +115 -4
  25. package/dist/connectors/apply-many.d.ts +5 -1
  26. package/dist/connectors/apply-many.js +5 -2
  27. package/dist/connectors/apply.d.ts +24 -3
  28. package/dist/connectors/apply.js +103 -3
  29. package/dist/connectors/catalog.js +5 -0
  30. package/dist/connectors/index.d.ts +1 -1
  31. package/dist/connectors/template-types.d.ts +30 -0
  32. package/dist/connectors/validate.js +33 -0
  33. package/dist/index.d.ts +6 -2
  34. package/dist/index.js +2 -0
  35. package/dist/layout/annotations.d.ts +3 -1
  36. package/dist/layout/annotations.js +72 -14
  37. package/dist/layout/semantic/place.js +23 -5
  38. package/dist/layout/semantic/route.js +15 -0
  39. package/dist/layout/types.d.ts +2 -1
  40. package/package.json +2 -1
@@ -0,0 +1,218 @@
1
+ import { CAMUNDA7_NS, MODELER_NS, ZEEBE_NS, } from "./migrate.js";
2
+ const isFeel = (value) => value?.trimStart().startsWith("=") === true;
3
+ function isOwner(value) {
4
+ if (typeof value !== "object" || value === null)
5
+ return false;
6
+ const o = value;
7
+ return typeof o.id === "string" && Array.isArray(o.extensionElements);
8
+ }
9
+ const isForeign = (name) => /^(zeebe|modeler)(:|$)/.test(name.replace(/^xmlns:/, ""));
10
+ /**
11
+ * Best-effort Camunda 8 → Camunda 7 / Operaton export. The input is not modified.
12
+ *
13
+ * Maps job types, I/O mappings, assignment, form keys, call activities and
14
+ * version tags to `camunda:` equivalents and removes every `zeebe:` and
15
+ * `modeler:` construct and namespace. FEEL is not translated to JUEL: it is
16
+ * kept raw with a `manual` finding. Connectors and Zeebe-only features are
17
+ * dropped with an `unsupported` finding.
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * const { definitions, findings } = convertCamunda8To7(Bpmn.parse(xml))
22
+ * const c7Xml = Bpmn.export(definitions)
23
+ * ```
24
+ */
25
+ export function convertCamunda8To7(definitions) {
26
+ const draft = structuredClone(definitions);
27
+ const findings = [];
28
+ let processId = "";
29
+ /** Type for owners the model does not tag, i.e. messages. */
30
+ let hint;
31
+ const add = (owner, construct, severity, message, suggestion, applied) => {
32
+ findings.push({
33
+ elementId: owner.id,
34
+ elementType: owner.type ?? hint ?? (owner.id === processId ? "process" : "element"),
35
+ processId,
36
+ construct,
37
+ severity,
38
+ message,
39
+ suggestion,
40
+ applied,
41
+ });
42
+ };
43
+ /** Writes `camunda:<name>`; a FEEL value is kept raw because Camunda 7 expects JUEL. */
44
+ const setAttr = (owner, name, value, from) => {
45
+ owner.unknownAttributes[`camunda:${name}`] = value;
46
+ if (isFeel(value)) {
47
+ add(owner, from, "manual", `FEEL expression "${value}" kept as-is; Camunda 7 evaluates JUEL.`, `Rewrite camunda:${name} as a JUEL expression such as \${...}.`, true);
48
+ }
49
+ };
50
+ const convertOwner = (owner) => {
51
+ const kept = [];
52
+ const inputOutput = [];
53
+ const camundaExt = [];
54
+ const take = (name) => owner.extensionElements.find((e) => e.name === `zeebe:${name}`);
55
+ const task = take("taskDefinition");
56
+ if (task) {
57
+ const type = task.attributes.type;
58
+ if (type !== undefined) {
59
+ owner.unknownAttributes["camunda:type"] = "external";
60
+ setAttr(owner, "topic", type, "zeebe:taskDefinition");
61
+ if (type.startsWith("io.camunda:") || owner.unknownAttributes["zeebe:modelerTemplate"]) {
62
+ add(owner, "connector", "unsupported", `Connector "${type}" has no Camunda 7 runtime; it becomes a plain external task.`, "Implement an external task worker for this topic.", false);
63
+ }
64
+ }
65
+ if (task.attributes.retries !== undefined) {
66
+ add(owner, "zeebe:taskDefinition retries", "manual", "Job retries are not exported.", "Set camunda:failedJobRetryTimeCycle if needed.", false);
67
+ }
68
+ }
69
+ const assignment = take("assignmentDefinition");
70
+ if (assignment) {
71
+ for (const key of ["assignee", "candidateUsers", "candidateGroups"]) {
72
+ const value = assignment.attributes[key];
73
+ if (value !== undefined)
74
+ setAttr(owner, key, value, "zeebe:assignmentDefinition");
75
+ }
76
+ }
77
+ const form = take("formDefinition");
78
+ if (form) {
79
+ if (form.attributes.formKey !== undefined) {
80
+ setAttr(owner, "formKey", form.attributes.formKey, "zeebe:formDefinition");
81
+ }
82
+ else {
83
+ add(owner, "zeebe:formDefinition", "unsupported", "Only formKey forms exist in Camunda 7; formId and external references are dropped.", "Link an embedded or generated form by camunda:formKey.", false);
84
+ }
85
+ }
86
+ const tag = take("versionTag");
87
+ if (tag?.attributes.value !== undefined) {
88
+ setAttr(owner, "versionTag", tag.attributes.value, "zeebe:versionTag");
89
+ }
90
+ const called = take("calledElement");
91
+ if (called) {
92
+ const target = called.attributes.processId;
93
+ if (target !== undefined) {
94
+ owner.unknownAttributes.calledElement = target;
95
+ if (isFeel(target)) {
96
+ add(owner, "zeebe:calledElement", "manual", `FEEL expression "${target}" kept as-is; Camunda 7 evaluates JUEL.`, "Rewrite calledElement as a JUEL expression.", true);
97
+ }
98
+ }
99
+ const binding = called.attributes.bindingType;
100
+ if (binding !== undefined) {
101
+ owner.unknownAttributes["camunda:calledElementBinding"] = binding;
102
+ }
103
+ if (called.attributes.versionTag !== undefined) {
104
+ owner.unknownAttributes["camunda:calledElementVersionTag"] = called.attributes.versionTag;
105
+ }
106
+ // Zeebe propagates both ways unless told not to.
107
+ if (called.attributes.propagateAllParentVariables !== "false") {
108
+ camundaExt.push({ name: "camunda:in", attributes: { variables: "all" }, children: [] });
109
+ }
110
+ if (called.attributes.propagateAllChildVariables !== "false") {
111
+ camundaExt.push({ name: "camunda:out", attributes: { variables: "all" }, children: [] });
112
+ }
113
+ }
114
+ const io = take("ioMapping");
115
+ if (io) {
116
+ for (const child of io.children) {
117
+ const source = child.attributes.source;
118
+ const target = child.attributes.target;
119
+ if (source === undefined || target === undefined)
120
+ continue;
121
+ const direction = child.name === "zeebe:output" ? "outputParameter" : "inputParameter";
122
+ inputOutput.push({
123
+ name: `camunda:${direction}`,
124
+ attributes: { name: target },
125
+ children: [],
126
+ text: source,
127
+ });
128
+ if (isFeel(source)) {
129
+ add(owner, `zeebe:${child.name.slice(6)}`, "manual", `FEEL expression "${source}" (to "${target}") kept as-is; Camunda 7 evaluates JUEL.`, "Rewrite the parameter as a JUEL expression.", true);
130
+ }
131
+ }
132
+ }
133
+ const subscription = take("subscription");
134
+ if (subscription) {
135
+ add(owner, "zeebe:subscription", "manual", "Camunda 7 does not subscribe messages by correlationKey; the key is dropped.", "Correlate with a business key or correlation variables when sending the message.", false);
136
+ }
137
+ for (const ext of owner.extensionElements) {
138
+ if (!ext.name.startsWith("zeebe:") && !ext.name.startsWith("modeler:")) {
139
+ kept.push(ext);
140
+ continue;
141
+ }
142
+ const handled = [
143
+ "taskDefinition",
144
+ "assignmentDefinition",
145
+ "formDefinition",
146
+ "versionTag",
147
+ "calledElement",
148
+ "ioMapping",
149
+ "subscription",
150
+ ];
151
+ if (handled.includes(ext.name.slice(ext.name.indexOf(":") + 1)))
152
+ continue;
153
+ add(owner, ext.name, "unsupported", `${ext.name} has no Camunda 7 equivalent and was dropped.`, "Reimplement the behavior in Camunda 7 or accept the difference.", false);
154
+ }
155
+ if (inputOutput.length > 0) {
156
+ camundaExt.push({ name: "camunda:inputOutput", attributes: {}, children: inputOutput });
157
+ }
158
+ owner.extensionElements = [...kept, ...camundaExt];
159
+ stripForeignAttrs(owner.unknownAttributes);
160
+ if (owner.unknownChildren) {
161
+ owner.unknownChildren = owner.unknownChildren.filter((c) => !isForeign(c.name));
162
+ }
163
+ };
164
+ const stripForeignAttrs = (attrs) => {
165
+ for (const key of Object.keys(attrs))
166
+ if (isForeign(key))
167
+ delete attrs[key];
168
+ };
169
+ const walk = (value) => {
170
+ if (Array.isArray(value)) {
171
+ for (const item of value)
172
+ walk(item);
173
+ return;
174
+ }
175
+ if (typeof value !== "object" || value === null)
176
+ return;
177
+ const record = value;
178
+ if (isOwner(record))
179
+ convertOwner(record);
180
+ else if (typeof record.unknownAttributes === "object" && record.unknownAttributes !== null) {
181
+ stripForeignAttrs(record.unknownAttributes);
182
+ }
183
+ const condition = record.conditionExpression;
184
+ if (isFeel(condition?.text)) {
185
+ add(record, "conditionExpression", "manual", `FEEL condition "${condition.text}" kept as-is; Camunda 7 evaluates JUEL.`, "Rewrite the condition as a JUEL expression.", true);
186
+ }
187
+ for (const [key, child] of Object.entries(record)) {
188
+ if (key !== "diagrams")
189
+ walk(child);
190
+ }
191
+ };
192
+ for (const message of draft.messages) {
193
+ processId = "";
194
+ const owner = message;
195
+ hint = "message";
196
+ owner.extensionElements ??= [];
197
+ convertOwner(owner);
198
+ hint = undefined;
199
+ }
200
+ for (const process of draft.processes) {
201
+ processId = process.id;
202
+ walk(process);
203
+ }
204
+ return { definitions: finish(draft), findings };
205
+ function finish(d) {
206
+ processId = "";
207
+ for (const [prefix, uri] of Object.entries(d.namespaces)) {
208
+ if (isForeign(prefix) || uri === ZEEBE_NS || uri === MODELER_NS)
209
+ delete d.namespaces[prefix];
210
+ }
211
+ stripForeignAttrs(d.unknownAttributes);
212
+ if (d.unknownChildren)
213
+ d.unknownChildren = d.unknownChildren.filter((c) => !isForeign(c.name));
214
+ d.namespaces.camunda ??= CAMUNDA7_NS;
215
+ return d;
216
+ }
217
+ }
218
+ //# sourceMappingURL=export.js.map
@@ -49,6 +49,9 @@ export interface Camunda7Conversion {
49
49
  definitions: BpmnDefinitions;
50
50
  report: Camunda7Report;
51
51
  }
52
+ export declare const CAMUNDA7_NS = "http://camunda.org/schema/1.0/bpmn";
53
+ export declare const ZEEBE_NS = "http://camunda.org/schema/zeebe/1.0";
54
+ export declare const MODELER_NS = "http://camunda.org/schema/modeler/1.0";
52
55
  /**
53
56
  * Converts a Camunda 7 model to Camunda 8, as far as that can be done
54
57
  * mechanically, and reports what it could not do. The input is not modified.
@@ -3,9 +3,9 @@ import { ValidationError } from "../../errors.js";
3
3
  import { detectExecutionPlatform } from "../lint.js";
4
4
  import { bpmnElementName, isZeebePlacementAllowed } from "../zeebe-extensions.js";
5
5
  import { containsJuel, feelString, isFeelName, translateJuelToFeel } from "./juel.js";
6
- const CAMUNDA7_NS = "http://camunda.org/schema/1.0/bpmn";
7
- const ZEEBE_NS = "http://camunda.org/schema/zeebe/1.0";
8
- const MODELER_NS = "http://camunda.org/schema/modeler/1.0";
6
+ export const CAMUNDA7_NS = "http://camunda.org/schema/1.0/bpmn";
7
+ export const ZEEBE_NS = "http://camunda.org/schema/zeebe/1.0";
8
+ export const MODELER_NS = "http://camunda.org/schema/modeler/1.0";
9
9
  const DEFAULT_PLATFORM_VERSION = "8.8.0";
10
10
  /** The event definitions and loop of a flow element, which carry attributes of their own. */
11
11
  function nestedHolders(owner) {
@@ -44,6 +44,20 @@ export interface CompactElement {
44
44
  calledProcess?: string;
45
45
  /** Linked form ID (userTask: zeebe:formDefinition.formId) */
46
46
  formId?: string;
47
+ /** userTask: who the task is assigned to (`zeebe:assignmentDefinition`); FEEL with `=`. */
48
+ assignee?: string;
49
+ /** userTask: comma-separated candidate groups, or a FEEL list expression. */
50
+ candidateGroups?: string;
51
+ /** userTask: comma-separated candidate users, or a FEEL list expression. */
52
+ candidateUsers?: string;
53
+ /** userTask: due date (`zeebe:taskSchedule`), ISO 8601 or FEEL. */
54
+ dueDate?: string;
55
+ /** userTask: follow-up date (`zeebe:taskSchedule`), ISO 8601 or FEEL. */
56
+ followUpDate?: string;
57
+ /** userTask: priority 0–100 (`zeebe:priorityDefinition`), or a FEEL expression. */
58
+ priority?: number | string;
59
+ /** Zeebe extension properties (`zeebe:properties`, name→value). */
60
+ properties?: Record<string, string>;
47
61
  /** Linked decision ID (businessRuleTask: zeebe:calledDecision.decisionId) */
48
62
  decisionId?: string;
49
63
  /**
@@ -80,9 +94,16 @@ export interface CompactElement {
80
94
  collection: string;
81
95
  element?: string;
82
96
  sequential?: boolean;
97
+ /** Variable collecting each instance's `outputElement`. */
98
+ outputCollection?: string;
99
+ outputElement?: string;
100
+ /** FEEL expression that ends the loop early. */
101
+ completionCondition?: string;
83
102
  };
84
103
  /** A timer event's ISO 8601 duration (`PT5M`): how long it waits once reached. */
85
104
  timerDuration?: string;
105
+ /** A conditional event's FEEL condition (Camunda 8.9+). */
106
+ condition?: string;
86
107
  }
87
108
  /** A sequence flow in compact form. */
88
109
  export interface CompactFlow {
@@ -3,6 +3,7 @@ import { layoutProcess } from "../layout/index.js";
3
3
  import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
4
4
  import { addAnnotationShapes } from "./auto-layout.js";
5
5
  import { restConnectorTaskType } from "./rest-connector.js";
6
+ import { makeConditionalDefinition } from "./zeebe-extensions.js";
6
7
  // ── Default flows ────────────────────────────────────────────────────────────
7
8
  /**
8
9
  * The gateway types that carry a `bpmn:default`. No other element in this model
@@ -78,6 +79,29 @@ function compactifyElement(el) {
78
79
  const formId = findAttr(ext, "zeebe:formDefinition", "formId");
79
80
  if (formId)
80
81
  result.formId = formId;
82
+ for (const key of ["assignee", "candidateGroups", "candidateUsers"]) {
83
+ const value = findAttr(ext, "zeebe:assignmentDefinition", key);
84
+ if (value)
85
+ result[key] = value;
86
+ }
87
+ for (const key of ["dueDate", "followUpDate"]) {
88
+ const value = findAttr(ext, "zeebe:taskSchedule", key);
89
+ if (value)
90
+ result[key] = value;
91
+ }
92
+ const priority = findAttr(ext, "zeebe:priorityDefinition", "priority");
93
+ if (priority)
94
+ result.priority = /^\d+$/.test(priority) ? Number(priority) : priority;
95
+ const propertiesEl = ext.find((e) => e.name === "zeebe:properties");
96
+ if (propertiesEl && propertiesEl.children.length > 0) {
97
+ const properties = {};
98
+ for (const child of propertiesEl.children) {
99
+ const { name, value } = child.attributes;
100
+ if (name !== undefined)
101
+ properties[name] = value ?? "";
102
+ }
103
+ result.properties = properties;
104
+ }
81
105
  const decisionId = findAttr(ext, "zeebe:calledDecision", "decisionId");
82
106
  const script = findAttr(ext, "zeebe:script", "expression");
83
107
  if (decisionId) {
@@ -139,6 +163,8 @@ function compactifyElement(el) {
139
163
  result.eventType = def?.type;
140
164
  if (def?.type === "timer" && def.timeDuration)
141
165
  result.timerDuration = def.timeDuration;
166
+ if (def?.type === "conditional" && def.condition !== undefined)
167
+ result.condition = def.condition;
142
168
  }
143
169
  const loop = "loopCharacteristics" in el ? el.loopCharacteristics : undefined;
144
170
  const zeebeLoop = loop?.extensionElements.find((x) => x.name === "zeebe:loopCharacteristics");
@@ -149,6 +175,12 @@ function compactifyElement(el) {
149
175
  result.multiInstance.element = zeebeLoop.attributes.inputElement;
150
176
  if (loop.isSequential)
151
177
  result.multiInstance.sequential = true;
178
+ if (zeebeLoop.attributes.outputCollection)
179
+ result.multiInstance.outputCollection = zeebeLoop.attributes.outputCollection;
180
+ if (zeebeLoop.attributes.outputElement)
181
+ result.multiInstance.outputElement = zeebeLoop.attributes.outputElement;
182
+ if (loop.completionCondition?.text)
183
+ result.multiInstance.completionCondition = loop.completionCondition.text;
152
184
  }
153
185
  if (el.type === "boundaryEvent") {
154
186
  result.attachedTo = el.attachedToRef;
@@ -373,6 +405,11 @@ function zeebeConfig(el) {
373
405
  }
374
406
  return { inputs, headers };
375
407
  }
408
+ /** The given attributes without the unset ones, or `undefined` if none is set. */
409
+ function definedAttributes(attributes) {
410
+ const set = Object.entries(attributes).filter((entry) => entry[1] !== undefined);
411
+ return set.length > 0 ? Object.fromEntries(set) : undefined;
412
+ }
376
413
  export function makeExtensions(el) {
377
414
  const ext = [];
378
415
  const { inputs, headers } = zeebeConfig(el);
@@ -403,6 +440,35 @@ export function makeExtensions(el) {
403
440
  if (el.formId) {
404
441
  ext.push({ name: "zeebe:formDefinition", attributes: { formId: el.formId }, children: [] });
405
442
  }
443
+ const assignment = definedAttributes({
444
+ assignee: el.assignee,
445
+ candidateGroups: el.candidateGroups,
446
+ candidateUsers: el.candidateUsers,
447
+ });
448
+ if (assignment) {
449
+ ext.push({ name: "zeebe:assignmentDefinition", attributes: assignment, children: [] });
450
+ }
451
+ const schedule = definedAttributes({ dueDate: el.dueDate, followUpDate: el.followUpDate });
452
+ if (schedule)
453
+ ext.push({ name: "zeebe:taskSchedule", attributes: schedule, children: [] });
454
+ if (el.priority !== undefined) {
455
+ ext.push({
456
+ name: "zeebe:priorityDefinition",
457
+ attributes: { priority: String(el.priority) },
458
+ children: [],
459
+ });
460
+ }
461
+ if (el.properties && Object.keys(el.properties).length > 0) {
462
+ ext.push({
463
+ name: "zeebe:properties",
464
+ attributes: {},
465
+ children: Object.entries(el.properties).map(([name, value]) => ({
466
+ name: "zeebe:property",
467
+ attributes: { name, value },
468
+ children: [],
469
+ })),
470
+ });
471
+ }
406
472
  if (el.decisionId) {
407
473
  ext.push({
408
474
  name: "zeebe:calledDecision",
@@ -503,18 +569,34 @@ defaultFlow) {
503
569
  unknownAttributes: templateAttributes(el),
504
570
  };
505
571
  const made = el.eventType ? makeEventDef(el.eventType) : undefined;
506
- const eventDef = made?.type === "timer" && el.timerDuration ? { ...made, timeDuration: el.timerDuration } : made;
572
+ const eventDef = made?.type === "timer" && el.timerDuration
573
+ ? { ...made, timeDuration: el.timerDuration }
574
+ : made?.type === "conditional" && el.condition !== undefined
575
+ ? makeConditionalDefinition(el.condition)
576
+ : made;
507
577
  const eventDefs = eventDef ? [eventDef] : [];
508
578
  const subContent = buildSubContent(el.children);
509
579
  const loop = el.multiInstance && {
510
580
  loopCharacteristics: {
511
581
  isSequential: el.multiInstance.sequential || undefined,
582
+ completionCondition: el.multiInstance.completionCondition
583
+ ? {
584
+ text: el.multiInstance.completionCondition,
585
+ attributes: { "xsi:type": "bpmn:tFormalExpression" },
586
+ }
587
+ : undefined,
512
588
  extensionElements: [
513
589
  {
514
590
  name: "zeebe:loopCharacteristics",
515
591
  attributes: {
516
592
  inputCollection: el.multiInstance.collection,
517
593
  ...(el.multiInstance.element ? { inputElement: el.multiInstance.element } : {}),
594
+ ...(el.multiInstance.outputCollection
595
+ ? { outputCollection: el.multiInstance.outputCollection }
596
+ : {}),
597
+ ...(el.multiInstance.outputElement
598
+ ? { outputElement: el.multiInstance.outputElement }
599
+ : {}),
518
600
  },
519
601
  children: [],
520
602
  },