@bpmnkit/core 1.10.1 → 1.11.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.
- package/agent-cards/bpmn.md +12 -6
- package/dist/bpmn/bpmn-builder.d.ts +3 -2
- package/dist/bpmn/bpmn-builder.js +3 -2
- package/dist/bpmn/index.d.ts +2 -0
- package/dist/bpmn/index.js +2 -0
- package/dist/bpmn/optimize/bpmnlint-rules.js +1 -1
- package/dist/bpmn/place-new-shapes.d.ts +51 -0
- package/dist/bpmn/place-new-shapes.js +1265 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/package.json +1 -1
package/agent-cards/bpmn.md
CHANGED
|
@@ -8,7 +8,7 @@ Write a Camunda 8 BPMN process with `@bpmnkit/core` in one script: create, expor
|
|
|
8
8
|
|
|
9
9
|
```ts
|
|
10
10
|
import { readFileSync, writeFileSync } from "node:fs"
|
|
11
|
-
import { Bpmn, exportPreserving, lintDiagram } from "@bpmnkit/core"
|
|
11
|
+
import { Bpmn, exportPreserving, lintDiagram, placeNewShapes } from "@bpmnkit/core"
|
|
12
12
|
|
|
13
13
|
// 1. Create. The process id is the deploy key: same id = new version of that process.
|
|
14
14
|
const definitions = Bpmn.createProcess("order")
|
|
@@ -32,12 +32,18 @@ const definitions = Bpmn.createProcess("order")
|
|
|
32
32
|
// 2. Export.
|
|
33
33
|
writeFileSync("order.bpmn", Bpmn.export(definitions))
|
|
34
34
|
|
|
35
|
-
// 3. Edit an existing file:
|
|
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.
|
|
36
37
|
const original = readFileSync("order.bpmn", "utf8")
|
|
37
|
-
const edited = Bpmn.parse(original)
|
|
38
|
+
const edited = Bpmn.continueProcess(Bpmn.parse(original), "order")
|
|
39
|
+
.insertAfter("ship")
|
|
40
|
+
.serviceTask("notify", { name: "Notify customer", taskType: "notify-customer" })
|
|
41
|
+
.build()
|
|
38
42
|
const ship = edited.processes[0]?.flowElements.find((e) => e.id === "ship")
|
|
39
43
|
if (ship) ship.name = "Ship parcel"
|
|
40
|
-
|
|
44
|
+
const { definitions: drawn, unplaced } = placeNewShapes(edited)
|
|
45
|
+
if (unplaced.length > 0) console.log("not drawn:", unplaced)
|
|
46
|
+
writeFileSync("order.bpmn", exportPreserving(original, drawn))
|
|
41
47
|
|
|
42
48
|
// 4. Validate: Camunda 8 deployability and modelling rules.
|
|
43
49
|
const report = lintDiagram(Bpmn.parse(readFileSync("order.bpmn", "utf8")))
|
|
@@ -46,7 +52,7 @@ for (const d of report.diagnostics.filter((d) => d.severity !== "info"))
|
|
|
46
52
|
if (report.counts.error > 0) process.exit(1)
|
|
47
53
|
```
|
|
48
54
|
|
|
49
|
-
`npm i @bpmnkit/core`. The script writes `order.bpmn`, re-opens it,
|
|
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.
|
|
50
56
|
|
|
51
57
|
## Top builder options
|
|
52
58
|
|
|
@@ -67,7 +73,7 @@ if (report.counts.error > 0) process.exit(1)
|
|
|
67
73
|
- **User tasks default to job-worker tasks**, which 8.10 deprecates. Pass `zeebeUserTask: true` for a Camunda user task.
|
|
68
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.
|
|
69
75
|
- **Reference a DMN decision by its decision id**, not the DMN `definitions` id, the file name or the decision name.
|
|
70
|
-
- **Edit with the preserving writer.** For an existing file, `Bpmn.parse` it, change the model, and write `exportPreserving(original,
|
|
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`.
|
|
71
77
|
- FEEL in the builder starts with `=` (`"=amount > 1000"`); a value without `=` is a literal string.
|
|
72
78
|
- Unknown option names are silently dropped: `timer: { duration }` does nothing; use `timerDuration`.
|
|
73
79
|
|
|
@@ -1137,8 +1137,9 @@ export declare class ProcessBuilder {
|
|
|
1137
1137
|
* continuing rather than regenerating.
|
|
1138
1138
|
*
|
|
1139
1139
|
* Diagram interchange is *not* regenerated: existing shapes keep their
|
|
1140
|
-
* positions, and elements added here have none until `
|
|
1141
|
-
*
|
|
1140
|
+
* positions, and elements added here have none until `placeNewShapes()` draws
|
|
1141
|
+
* just those (existing shapes never move), or `withAutoLayout()` /
|
|
1142
|
+
* `applyAutoLayout()` redraws everything.
|
|
1142
1143
|
*/
|
|
1143
1144
|
private buildOntoSource;
|
|
1144
1145
|
/**
|
|
@@ -2882,8 +2882,9 @@ export class ProcessBuilder {
|
|
|
2882
2882
|
* continuing rather than regenerating.
|
|
2883
2883
|
*
|
|
2884
2884
|
* Diagram interchange is *not* regenerated: existing shapes keep their
|
|
2885
|
-
* positions, and elements added here have none until `
|
|
2886
|
-
*
|
|
2885
|
+
* positions, and elements added here have none until `placeNewShapes()` draws
|
|
2886
|
+
* just those (existing shapes never move), or `withAutoLayout()` /
|
|
2887
|
+
* `applyAutoLayout()` redraws everything.
|
|
2887
2888
|
*/
|
|
2888
2889
|
buildOntoSource(source, elements, flows) {
|
|
2889
2890
|
const definitions = structuredClone(source.definitions);
|
package/dist/bpmn/index.d.ts
CHANGED
|
@@ -62,6 +62,8 @@ export declare const Bpmn: {
|
|
|
62
62
|
* `build()` returns that document with the named process's contents replaced,
|
|
63
63
|
* so other processes, the collaboration, lanes, diagram interchange, root
|
|
64
64
|
* elements and unmodelled content all survive. The input is not mutated.
|
|
65
|
+
* Added elements have no shapes; call `placeNewShapes()` on the result to
|
|
66
|
+
* draw only those without moving existing ones.
|
|
65
67
|
*
|
|
66
68
|
* @param definitions - The parsed model to continue.
|
|
67
69
|
* @param processId - Which process to continue, named explicitly.
|
package/dist/bpmn/index.js
CHANGED
|
@@ -73,6 +73,8 @@ export const Bpmn = {
|
|
|
73
73
|
* `build()` returns that document with the named process's contents replaced,
|
|
74
74
|
* so other processes, the collaboration, lanes, diagram interchange, root
|
|
75
75
|
* elements and unmodelled content all survive. The input is not mutated.
|
|
76
|
+
* Added elements have no shapes; call `placeNewShapes()` on the result to
|
|
77
|
+
* draw only those without moving existing ones.
|
|
76
78
|
*
|
|
77
79
|
* @param definitions - The parsed model to continue.
|
|
78
80
|
* @param processId - Which process to continue, named explicitly.
|
|
@@ -382,7 +382,7 @@ const RULES = {
|
|
|
382
382
|
const missing = (id, processId) => {
|
|
383
383
|
if (drawn.has(id))
|
|
384
384
|
return;
|
|
385
|
-
report("pattern/missing-di", `Element "${id}" has no diagram information (BPMNDI).`, "
|
|
385
|
+
report("pattern/missing-di", `Element "${id}" has no diagram information (BPMNDI).`, "In a script, call `placeNewShapes(definitions)` before `exportPreserving` to draw only the new elements; redraw everything only for a new file.", processId, [id]);
|
|
386
386
|
};
|
|
387
387
|
const lanes = (list, processId) => {
|
|
388
388
|
for (const lane of list) {
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import type { BpmnDefinitions } from "./bpmn-model.js";
|
|
2
|
+
export interface PlaceNewShapesOptions {
|
|
3
|
+
/**
|
|
4
|
+
* Re-route existing edges whose ends no longer touch their shapes, such as a
|
|
5
|
+
* flow the edit re-pointed at a new element. Default `true`.
|
|
6
|
+
*/
|
|
7
|
+
rerouteStale?: boolean;
|
|
8
|
+
/**
|
|
9
|
+
* Add a new flow node to the lane it is drawn in when no lane lists it, as a
|
|
10
|
+
* modeller does when a shape is dropped into a lane. Default `true`.
|
|
11
|
+
*/
|
|
12
|
+
assignLanes?: boolean;
|
|
13
|
+
}
|
|
14
|
+
export interface PlaceNewShapesResult {
|
|
15
|
+
/** A copy of the input with the new shapes and edges; the input is not changed. */
|
|
16
|
+
definitions: BpmnDefinitions;
|
|
17
|
+
/** Elements that got a shape: flow nodes, pools, annotations. */
|
|
18
|
+
placed: string[];
|
|
19
|
+
/** Connections that got an edge: sequence flows, message flows, associations. */
|
|
20
|
+
routed: string[];
|
|
21
|
+
/** Existing edges that got a new route because their ends no longer met their shapes. */
|
|
22
|
+
rerouted: string[];
|
|
23
|
+
/** Pools, lanes and sub-processes made larger so the new shapes fit. */
|
|
24
|
+
resized: string[];
|
|
25
|
+
/** Flow nodes added to a lane's `flowNodeRefs`. */
|
|
26
|
+
laneAssigned: string[];
|
|
27
|
+
/** What could not be placed, and why. */
|
|
28
|
+
unplaced: Array<{
|
|
29
|
+
id: string;
|
|
30
|
+
reason: string;
|
|
31
|
+
}>;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Gives every element that has no shape a place next to what it connects to,
|
|
35
|
+
* and every connection that has no edge a route, without moving existing shapes.
|
|
36
|
+
*
|
|
37
|
+
* Use it after editing a parsed file and before {@link exportPreserving}:
|
|
38
|
+
*
|
|
39
|
+
* ```ts
|
|
40
|
+
* const original = readFileSync("order.bpmn", "utf8")
|
|
41
|
+
* const defs = Bpmn.parse(original)
|
|
42
|
+
* // … add elements and flows to defs …
|
|
43
|
+
* const { definitions, unplaced } = placeNewShapes(defs)
|
|
44
|
+
* writeFileSync("order.bpmn", exportPreserving(original, definitions))
|
|
45
|
+
* ```
|
|
46
|
+
*
|
|
47
|
+
* New lanes are not placed: they need room inside a pool, which means moving
|
|
48
|
+
* the lanes below. They are reported in `unplaced`.
|
|
49
|
+
*/
|
|
50
|
+
export declare function placeNewShapes(input: BpmnDefinitions, options?: PlaceNewShapesOptions): PlaceNewShapesResult;
|
|
51
|
+
//# sourceMappingURL=place-new-shapes.d.ts.map
|