Part 10: Turning the DSL into a maintainable workflow authoring library

The last nine parts built a working pipeline. This one answers the question that matters for a real library: how to package it so the next ten BPMN elements slot in without breaking the API, and what was deliberately left out.

Recommended module layout

The seams in the code already suggest Gradle modules — each one is independently testable and independently replaceable:

1
rootProject.name = "bpmn-dsl"
2
include("bpmn-model", "bpmn-dsl", "bpmn-validation", "bpmn-xml", "bpmn-layout", "bpmn-flowable", "bpmn-example")

Module	Contents	Depends on
`bpmn-model`	AST: `CollaborationDefinition`, `FlowNode` hierarchy, `DiagramLayout` types	nothing
`bpmn-dsl`	`bpmnCollaboration`, `@BpmnDsl` builders	`bpmn-model`
`bpmn-validation`	`BpmnValidator`, `Diagnostic`	`bpmn-model`
`bpmn-layout`	`DiagramLayoutEngine`, `LayeredLayoutEngine`	`bpmn-model`
`bpmn-xml`	`BpmnXmlWriter`, `EngineExtensionSerializer`, `BpmnNs`	`bpmn-model` (+ `bpmn-layout` types)
`bpmn-flowable`	`FlowableExtensionSerializer`	`bpmn-xml`
`bpmn-example`	`enterpriseProcurementCollaboration()`, `Main.kt`	all

Dependencies that actually matter: the JDK’s javax.xml.stream (no external dep for XML), kotlin("test") + JUnit 5 for tests, flowable-spring-boot-starter-process only in the Part 9 deployment demo. The library proper needs no third-party runtime dependency.

1
plugins {
2
    kotlin("jvm") version "2.3.21"
3
    application
4
}
5

6
repositories { mavenCentral() }
7

8
kotlin { jvmToolchain(21) }
9

10
dependencies {
11
    testImplementation(kotlin("test"))
12
    testImplementation("org.junit.jupiter:junit-jupiter:5.12.2")
13
    testRuntimeOnly("org.junit.platform:junit-platform-launcher:1.12.2")
14
}
15

16
application { mainClass.set("in.o612.eng.bpmn.MainKt") }
17
tasks.test { useJUnitPlatform() }

The assembled pipeline

Main.kt is the series’ deliverable in miniature — build, validate, lay out, write:

1
fun main() {
2
    val collaboration = enterpriseProcurementCollaboration()
3

4
    val validator = BpmnValidator()
5
    val diagnostics = validator.validate(collaboration)
6
    diagnostics.forEach { println("[${it.severity}] ${it.code} ${it.elementId ?: "-"}: ${it.message}") }
7
    check(diagnostics.none { it.severity == Severity.ERROR }) {
8
        "Validation failed — see diagnostics above"
9
    }
10

11
    val layout = LayeredLayoutEngine().layout(collaboration)
12
    val diDiags = validator.validateDiagram(collaboration, layout)
13
    check(diDiags.none { it.severity == Severity.ERROR })
14

15
    val xml = BpmnXmlWriter(FlowableExtensionSerializer).writeToString(collaboration, layout)
16
    File("build/procurement.bpmn").apply { parentFile.mkdirs(); writeText(xml) }
17
}

Validation gates generation: no XML is written unless both semantic and diagram validation pass. The series’ full source is the Model.kt, Dsl.kt, Validation.kt, BpmnXmlWriter.kt, Layout.kt, Flowable.kt, Procurement.kt, Main.kt, and BpmnDslTest.kt excerpts across Parts 2–9 — each block compiles as written.

API stability and DSL versioning

Two surfaces carry different contracts:

The AST is the stable layer. Adding a new BPMN element means a new data class under FlowNode plus a builder plus a when branch in the writer — all additive, all source-compatible for readers. Removing or renaming a type is the breaking change; don’t do it without a major version.
The DSL is the ergonomic layer. Renaming userTask or changing its builder’s signature breaks every consumer’s compile — treat it as public API. New builder functions are additive; changing existing overloads is not.

Stable identifiers deserve the same discipline. IDs are referenced by defaultFlow, attachedToRef, sourceRef, targetRef, processRef, messageRef, and by DI bpmnElements — renaming a node id is a schema change, not a refactor. Version-generated workflows should carry the definition id (enterpriseProcurement) through generations; a v2 is a new collaboration id or a compatibility migration, not a silent rebake.

Where arbitrary expressions are a security boundary

conditionalFlow and metadata accept free-form strings that land in executable XML. conditionalFlow("f", "g", "t", "${ctx.eval()}") ships an EL expression to an engine — and EL injection in a process definition is a real risk if the DSL input is not trusted:

1
// If user input reaches a condition string, you have an injection sink.
2
conditionalFlow("f1", "gw", "task", userSuppliedString)

The mitigation is the same as for SQL: the DSL consumes programs written by the team, not end-user input. If end users must author workflows, build a UI that produces a constrained JSON schema and a second, validated compilation step into the AST — never let arbitrary strings become Expression bodies unscreened.

Extending the model — the Part-10 shopping list

The architecture is built to grow along specific seams:

Extension	What it touches
Error/compensation/message start events	`EventNode` subclass + event-definition writer + tests
Call activities, reusable subprocesses	`ActivityNode` subclass + `calledElement` + validator rule
Event subprocesses	`EmbeddedSubprocess` with `triggeredByEvent` + a subprocess-level boundary rule
Signal/escalation events	New event definitions + `bpmn:signal`/`bpmn:escalation` top-level elements
Multi-instance tasks	`LoopCharacteristics`/`MultiInstanceLoopCharacteristics` on `ActivityNode`
Form schemas for user tasks	`formKey` → structured `formDefinition` extension element
Timer cycles/cron	already supported — `TimerDefinition(cycle=…)`
A web-based BPMN editor	New frontend that compiles its own model into this AST, or a JSON serializer of the AST itself
BPMN import (XML → AST)	A parser producing `CollaborationDefinition` — the inverse of Part 6
ELK/Graphviz/Sugiyama layout	A second `DiagramLayoutEngine` implementation
Layout overrides per node	`layout.shapes` merged with a persisted override map keyed by id
Camunda output	A `CamundaExtensionSerializer` implementing the same SPI

The recurring pattern: a new BPMN element is a FlowNode subtype, a builder function on FlowNodeContainer, a when arm in writeFlowNode, a nodeSize case in the layout engine, and a validator rule if it has semantics. Nothing else.

Testing strategy for a long-lived library

Three tiers, in increasing cost:

Unit tests on the AST/validator — cheap, fast, and already in place: every diagnostic code gets a purpose-built broken model.
Golden tests — the generated procurement.bpmn committed as a fixture; any behavioral change to serialization or layout requires a deliberate diff review.
Integration tests — the Part 8 pipeline: moddle-parse + headless bpmn-js import + (optionally) a Testcontainers Flowable deployment, run in CI.

The split matters because they catch different things: unit tests catch wrong rules; golden tests catch wrong changes; integration tests catch wrong assumptions about what a viewer accepts.

The generated artifact

One trimmed excerpt of the real procurement.bpmn output — every element class the pipeline produces appears (abridged with … where the file repeats):

1
<?xml version="1.0" encoding="UTF-8"?>
2
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
3
    xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
4
    xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
5
    xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
6
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
7
    xmlns:bpmndsl="https://o612.in/bpmn/dsl"
8
    xmlns:flowable="http://flowable.org/bpmn"
9
    id="enterpriseProcurement_definitions"
10
    name="Enterprise Procurement and Supplier Onboarding"
11
    targetNamespace="https://o612.in/bpmn/definitions"
12
    exporter="o612-bpmn-dsl" exporterVersion="1.0">
13

14
  <bpmn:message id="rfqRequested"/>
15
  <bpmn:message id="supplierQuotationReceived"/>
16
  <!-- … five more <bpmn:message> … -->
17

18
  <bpmn:collaboration id="enterpriseProcurement" name="Enterprise Procurement and Supplier Onboarding">
19
    <bpmn:participant id="buyerOrganization" name="Buyer Organization" processRef="buyerProcurementProcess"/>
20
    <bpmn:participant id="supplier" name="Supplier" processRef="supplierInteractionProcess"/>
21
    <bpmn:messageFlow id="msgRfqToSupplier" sourceRef="sendRfq" targetRef="receiveRfq" messageRef="rfqRequested"/>
22
    <!-- … six more <bpmn:messageFlow> … -->
23
  </bpmn:collaboration>
24

25
  <bpmn:process id="buyerProcurementProcess" name="Buyer Procurement Process" isExecutable="true">
26
    <bpmn:extensionElements>
27
      <bpmndsl:processVariables>
28
        <bpmndsl:variable name="requisitionId" type="string" required="true"/>
29
        <!-- … nineteen more variables … -->
30
      </bpmndsl:processVariables>
31
    </bpmn:extensionElements>
32
    <bpmn:laneSet id="buyerProcurementProcess_laneSet">
33
      <bpmn:lane id="requestingDepartment" name="Requesting Department">
34
        <bpmn:flowNodeRef>requisitionCreated</bpmn:flowNodeRef>
35
        <bpmn:flowNodeRef>submitRequisition</bpmn:flowNodeRef>
36
        <bpmn:flowNodeRef>correctRequisition</bpmn:flowNodeRef>
37
      </bpmn:lane>
38
      <!-- … five more lanes … -->
39
    </bpmn:laneSet>
40

41
    <bpmn:startEvent id="requisitionCreated" name="Requisition created">
42
      <bpmn:outgoing>flowStartToSubmit</bpmn:outgoing>
43
    </bpmn:startEvent>
44
    <bpmn:serviceTask id="validateRequisition" name="Validate Requisition and Supplier"
45
        flowable:delegateExpression="${requisitionValidationDelegate}">
46
      <bpmn:incoming>flowSubmitToValidate</bpmn:incoming>
47
      <bpmn:incoming>flowCorrectToValidate</bpmn:incoming>
48
      <bpmn:outgoing>flowValidateToDecision</bpmn:outgoing>
49
    </bpmn:serviceTask>
50
    <bpmn:inclusiveGateway id="approvalsSplit" name="Required approvals" default="flowApprovalsBypass">
51
      <bpmn:incoming>flowValidToApprovals</bpmn:incoming>
52
      <bpmn:outgoing>flowBudgetBranch</bpmn:outgoing>
53
      <bpmn:outgoing>flowLegalBranch</bpmn:outgoing>
54
      <bpmn:outgoing>flowApprovalsBypass</bpmn:outgoing>
55
    </bpmn:inclusiveGateway>
56
    <bpmn:receiveTask id="waitForQuotation" name="Wait for Supplier Quotation"
57
        messageRef="supplierQuotationReceived">
58
      <bpmn:incoming>flowRfqToWait</bpmn:incoming>
59
      <bpmn:incoming>flowRetryWait</bpmn:incoming>
60
      <bpmn:incoming>flowRenegotiationToWait</bpmn:incoming>
61
      <bpmn:outgoing>flowQuotationToEval</bpmn:outgoing>
62
    </bpmn:receiveTask>
63
    <bpmn:boundaryEvent id="quotationSlaExceeded" name="72h supplier SLA" attachedToRef="waitForQuotation">
64
      <bpmn:outgoing>flowSlaToReminder</bpmn:outgoing>
65
      <bpmn:timerEventDefinition id="quotationSlaExceeded_timer">
66
        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">PT72H</bpmn:timeDuration>
67
      </bpmn:timerEventDefinition>
68
    </bpmn:boundaryEvent>
69
    <bpmn:subProcess id="invoiceExceptionHandling" name="Invoice Exception Handling">
70
      <bpmn:incoming>flowMatchToException</bpmn:incoming>
71
      <bpmn:outgoing>flowExceptionToRematch</bpmn:outgoing>
72
      <bpmn:startEvent id="exceptionStart"><bpmn:outgoing>flowExceptionStart</bpmn:outgoing></bpmn:startEvent>
73
      <!-- … interior nodes and flows … -->
74
    </bpmn:subProcess>
75
    <bpmn:sequenceFlow id="flowBudgetBranch" name="budget approval"
76
        sourceRef="approvalsSplit" targetRef="approveBudget">
77
      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">${budgetApprovalRequired}</bpmn:conditionExpression>
78
    </bpmn:sequenceFlow>
79
    <!-- … all remaining flow elements … -->
80
  </bpmn:process>
81

82
  <bpmn:process id="supplierInteractionProcess" name="Supplier Interaction Process" isExecutable="false">
83
    <!-- … supplier lanes, tasks, event-based gateway … -->
84
  </bpmn:process>
85

86
  <bpmndi:BPMNDiagram id="diagram_enterpriseProcurement">
87
    <bpmndi:BPMNPlane id="plane_enterpriseProcurement" bpmnElement="enterpriseProcurement">
88
      <bpmndi:BPMNShape id="shape_buyerOrganization" bpmnElement="buyerOrganization" isHorizontal="true">
89
        <dc:Bounds x="60" y="60" width="4410" height="974"/>
90
      </bpmndi:BPMNShape>
91
      <bpmndi:BPMNShape id="shape_requestingDepartment" bpmnElement="requestingDepartment" isHorizontal="true">
92
        <dc:Bounds x="90" y="72" width="4368" height="140"/>
93
      </bpmndi:BPMNShape>
94
      <bpmndi:BPMNShape id="shape_waitForQuotation" bpmnElement="waitForQuotation">
95
        <dc:Bounds x="1794" y="242" width="120" height="80"/>
96
      </bpmndi:BPMNShape>
97
      <bpmndi:BPMNShape id="shape_quotationSlaExceeded" bpmnElement="quotationSlaExceeded">
98
        <dc:Bounds x="1899" y="307" width="30" height="30"/>
99
      </bpmndi:BPMNShape>
100
      <bpmndi:BPMNEdge id="edge_flowSlaToReminder" bpmnElement="flowSlaToReminder">
101
        <di:waypoint x="1929" y="322"/>
102
        <di:waypoint x="2911.5" y="322"/>
103
        <di:waypoint x="2911.5" y="282"/>
104
        <di:waypoint x="3894" y="282"/>
105
      </bpmndi:BPMNEdge>
106
      <!-- … all remaining shapes and edges … -->
107
    </bpmndi:BPMNPlane>
108
  </bpmndi:BPMNDiagram>
109
</bpmn:definitions>

The full file is ~51 KB, two processes (68 + 25 flow elements), 7 message flows, 57 shapes and 60 edges — generated verbatim by the pipeline above, parse-verified by bpmn-moddle and render-verified by bpmn-js.

Known simplifications — stated, not hidden

Layout is a baseline. Longest-path columns, lane-index rows, one shared return channel per pool. Loop-back edges that span lanes cross lower lanes vertically; message flows don’t avoid nodes. It’s deterministic and correct; it is not ELK.
No BPMN import. This library writes BPMN; it does not parse it. Round-trip editing is a separate (significant) project.
No pools-in-pools or nested lanes. Lanes are flat partitions; BPMN’s childLaneSet is unmodeled.
No data objects, data stores, associations, or group/annotation artifacts. The collaboration is flow-and-message only — enough for the running example, not the whole spec.
Process variables are metadata. They serialize to a bpmndsl extension block; engines ignore it unless an adapter consumes it.
The supplier process is illustrative. Non-executable pools exist for the diagram; whether poAccepted matches a real supplier system is integration, not modeling.
No token-semantics verification. The validator checks structure, references, scope, direction, and lane/containment invariants — not whether an arbitrary process can deadlock. That is a model-checking problem beyond a structural validator.

What the series actually shipped

One runnable Gradle build — published as pcnixsys/bpmn-dsl-kotlin — organized as the seven modules this chapter described: bpmn-model, bpmn-dsl, bpmn-validation, bpmn-xml, bpmn-layout, bpmn-flowable, bpmn-example. ./gradlew :bpmn-example:run produces a 55 KB .bpmn file that bpmn-moddle parses with zero warnings and bpmn-js renders as a two-pool collaboration. Nineteen tests cover the validator, the DI invariants, the Flowable adapter, determinism, and the golden layout.

The library is not a toy and it is not a product. It is exactly what the series set out to build: a Kotlin internal DSL where the compiler, the validator, and the viewer each enforce a different layer of correctness — and where every stage after the AST is a pure, replaceable, testable pass over immutable data.

Reference implementation

The split itself lives in the repo’s Gradle files: settings.gradle.kts plus one build.gradle.kts per module (for example bpmn-flowable/build.gradle.kts). The API stability contract and the security boundary from this chapter are written down in the README.

If you take one thing

An internal DSL’s value isn’t the fluent syntax — it’s the seam between authoring and output. Mutable builders that compile to an immutable AST, a validator that treats structure as a first-class citizen, and a serializer that never touches the builder layer: that separation is what makes the whole thing worth the indirection.

KotlinBPMN