Part 3 of 1030% complete

2026-09-15•5 min read

Part 3: Designing a type-safe Kotlin DSL for BPMN

The AST from Part 2 is correct but unusable as an authoring surface — nobody wants to nest ProcessDefinition(nodes = listOf(UserTask(...))) by hand. This part builds the fluent layer: bpmnCollaboration("enterpriseProcurement") { participant(...) { process(...) { lane(...) { ... } } } }. All of it compiles to the same immutable CollaborationDefinition.

Lambdas with receivers — the whole trick

The mechanism is one Kotlin feature: a function type T.() -> Unit where the lambda runs with T as its receiver, so this inside the block is the builder:

1
fun bpmnCollaboration(id: String, block: CollaborationBuilder.() -> Unit): CollaborationDefinition =
2
    CollaborationBuilder(id).apply(block).build()

Three lines, three responsibilities: create the mutable builder, run the author’s block against it, freeze it into the immutable AST. build() is internal — the DSL’s public surface is the block, not the builder.

@DslMarker: preventing scope leakage

Without a marker, every receiver in the lexical nesting is visible inside every block. Inside lane { }, the author could call participant { } — which resolves against the enclosing CollaborationBuilder and silently adds a participant while the author thought they were in a lane:

1
@DslMarker
2
annotation class BpmnDsl

Annotating every builder class with @BpmnDsl tells the compiler: inside a lambda whose receiver is @BpmnDsl-annotated, only the innermost @BpmnDsl receiver’s members resolve implicitly. Calling messageFlow(...) inside lane { } is now a compile error — the collaboration builder’s members are no longer in scope. This is the difference between a DSL that reads well in examples and one that doesn’t corrupt real models when a block is mis-nested.

Two scope interfaces, not one builder hierarchy

Two different “can contain things” relationships exist in BPMN, and they should not merge:

Node scope — a process, a lane, or a subprocess can own flow nodes.
Flow scope — a process or a subprocess can own sequence flows. A lane cannot.

If lane { } offered sequenceFlow(...), the DSL would be teaching a BPMN falsehood (sequence flows belong to the process; lanes only group nodes). So the capabilities are two separate supertypes:

1
/** A scope that can own flow nodes: a process, a lane, or a subprocess. */
2
@BpmnDsl
3
sealed class FlowNodeContainer {
4
    internal abstract fun register(node: FlowNode)
5

6
    fun startEvent(id: String, block: StartEventBuilder.() -> Unit = {}) =
7
        register(StartEventBuilder(id).apply(block).build())
8

9
    fun userTask(id: String, block: UserTaskBuilder.() -> Unit = {}) =
10
        register(UserTaskBuilder(id, this).apply(block).build())
11

12
    fun serviceTask(id: String, block: ServiceTaskBuilder.() -> Unit = {}) =
13
        register(ServiceTaskBuilder(id, this).apply(block).build())
14

15
    fun receiveTask(id: String, block: ReceiveTaskBuilder.() -> Unit = {}) =
16
        register(ReceiveTaskBuilder(id, this).apply(block).build())
17

18
    fun sendTask(id: String, block: SendTaskBuilder.() -> Unit = {}) =
19
        register(SendTaskBuilder(id, this).apply(block).build())
20

21
    fun exclusiveGateway(id: String, block: ExclusiveGatewayBuilder.() -> Unit = {}) =
22
        register(ExclusiveGatewayBuilder(id).apply(block).build())
23

24
    fun parallelGateway(id: String, block: ParallelGatewayBuilder.() -> Unit = {}) =
25
        register(ParallelGatewayBuilder(id).apply(block).build())
26

27
    fun inclusiveGateway(id: String, block: InclusiveGatewayBuilder.() -> Unit = {}) =
28
        register(InclusiveGatewayBuilder(id).apply(block).build())
29

30
    fun eventBasedGateway(id: String, block: EventBasedGatewayBuilder.() -> Unit = {}) =
31
        register(EventBasedGatewayBuilder(id).apply(block).build())
32

33
    fun intermediateCatchMessageEvent(id: String, block: CatchMessageEventBuilder.() -> Unit = {}) =
34
        register(CatchMessageEventBuilder(id).apply(block).build())
35

36
    fun embeddedSubprocess(id: String, block: SubprocessBuilder.() -> Unit = {}) =
37
        register(SubprocessBuilder(id, this).apply(block).build())
38
}
39

40
/** A scope that can own sequence flows: a process or a subprocess, never a lane. */
41
@BpmnDsl
42
interface SequenceFlowContainer {
43
    fun registerFlow(flow: SequenceFlow)
44

45
    fun sequenceFlow(id: String, from: String, to: String, name: String? = null) =
46
        registerFlow(SequenceFlow(id = id, name = name, sourceRef = from, targetRef = to))
47

48
    fun conditionalFlow(id: String, from: String, to: String, condition: String, name: String? = null) =
49
        registerFlow(
50
            SequenceFlow(
51
                id = id, name = name, sourceRef = from, targetRef = to,
52
                condition = Expression(condition),
53
            ),
54
        )
55
}

sequenceFlow and conditionalFlow are deliberately separate functions rather than an optional condition parameter — a conditional edge is a different authoring act, and keeping them distinct makes the call site self-documenting.

The lane trick: declaring nodes inside a lane block

BPMN XML puts nodes in the process and references them from lanes via flowNodeRef. The pleasant DSL ordering is the reverse: declare the node inside the lane block and let membership be derived:

1
@BpmnDsl
2
class LaneBuilder internal constructor(
3
    private val id: String,
4
    private val nodeScope: FlowNodeContainer,
5
) : FlowNodeContainer() {
6
    var name: String? = null
7
    private val refs = mutableListOf<String>()
8

9
    /** Nodes declared inside a lane block register in the enclosing scope. */
10
    override fun register(node: FlowNode) {
11
        nodeScope.register(node)   // the node belongs to the process…
12
        refs += node.id            // …and the lane only records the reference
13
    }
14

15
    /** Membership by reference, for nodes declared outside the lane block. */
16
    fun contains(vararg nodeIds: String) {
17
        refs += nodeIds
18
    }
19

20
    internal fun build() = LaneDefinition(
21
        id = id, name = name,
22
        flowNodeRefs = refs.toList(),
23
    )
24
}

This is the delegation pattern that makes the AST honest: the lane’s block looks like it owns nodes, but register forwards each node to the enclosing process scope and only keeps the id. What you write matches what a lane means — a rendering partition, not a container.

Boundary events: nested syntax, flat registration

The DSL wants boundaryTimer declared inside the activity it guards — that reads correctly and mirrors the diagram. But the AST stores the boundary event as a sibling flow node in the same scope (with attachedToRef pointing at the host). The bridge: every activity builder receives the enclosing FlowNodeContainer and boundary functions append into it:

1
@BpmnDsl
2
sealed class ActivityBuilder(private val nodeId: String, private val scope: FlowNodeContainer) :
3
    ElementBuilder() {
4

5
    fun boundaryTimer(id: String, block: BoundaryTimerBuilder.() -> Unit) {
6
        scope.register(BoundaryTimerBuilder(id, nodeId).apply(block).build())
7
    }
8

9
    fun boundaryMessage(id: String, message: String, block: BoundaryEventBuilder.() -> Unit = {}) {
10
        scope.register(BoundaryEventBuilder(id, nodeId).apply(block).buildMessage(message))
11
    }
12

13
    fun boundaryError(id: String, errorRef: String? = null, block: BoundaryEventBuilder.() -> Unit = {}) {
14
        scope.register(BoundaryEventBuilder(id, nodeId).apply(block).buildError(errorRef))
15
    }
16
}

So this declaration:

1
receiveTask("waitForQuotation") {
2
    name = "Wait for Supplier Quotation"
3
    messageRef = "supplierQuotationReceived"
4
    boundaryTimer("quotationSlaExceeded") {
5
        name = "72h supplier SLA"
6
        duration = "PT72H"
7
        cancelActivity = true   // interrupting: cancel the wait on SLA breach
8
    }
9
}

produces a ReceiveTask and a BoundaryTimerEvent(attachedToRef = "waitForQuotation") in the process’s flat node list — exactly the shape BPMN serializes as a <bpmn:boundaryEvent> sibling element.

Because boundaryTimer only exists on ActivityBuilder (which only task/subprocess builders extend), intermediateCatchMessageEvent("x") { boundaryTimer("y") {} } is a compile error. Part 4 shows why this matters: the intuitive sketch of this example attaches a timer to a catch event, which is invalid BPMN — boundary events attach to activities.

Element and gateway builders

One shared base for id/name/documentation/extensions; specific subclasses for what each element type may express:

1
@BpmnDsl
2
sealed class ElementBuilder {
3
    var name: String? = null
4
    var documentation: String? = null
5
    private val extensions = mutableListOf<ExtensionElement>()
6

7
    fun extension(prefix: String? = null, name: String, vararg attributes: Pair<String, String>) {
8
        extensions += ExtensionElement(prefix = prefix, name = name, attributes = attributes.toMap())
9
    }
10

11
    internal fun collectExtensions(): List<ExtensionElement> = extensions.toList()
12
    internal fun doc(): Documentation? = documentation?.let(::Documentation)
13
}

1
class ServiceTaskBuilder internal constructor(private val id: String, scope: FlowNodeContainer) :
2
    ActivityBuilder(id, scope) {
3
    /** Logical delegate name; the engine adapter decides how to serialize it. */
4
    var delegate: String? = null
5
    var delegateClass: String? = null
6
    var expression: String? = null
7

8
    internal fun build() = ServiceTask(
9
        id, name, doc(),
10
        metadata = buildMap {
11
            delegate?.let { put("delegate", it) }
12
            delegateClass?.let { put("class", it) }
13
            expression?.let { put("expression", it) }
14
        },
15
        extensions = collectExtensions(),
16
    )
17
}
18

19
class ExclusiveGatewayBuilder internal constructor(private val id: String) : ElementBuilder() {
20
    /** Id of the sequence flow taken when every condition evaluates false. */
21
    var defaultFlow: String? = null
22
    internal fun build() = ExclusiveGateway(id, name, doc(), defaultFlow, collectExtensions())
23
}

delegate = "requisitionValidationDelegate" lands in the metadata map — not a BPMN attribute — and Part 9’s Flowable adapter turns it into flowable:delegateExpression. Same for formKey, assignee, candidateGroup on UserTaskBuilder.

TimerDefinition itself enforces exclusivity at construction:

1
data class TimerDefinition(
2
    val duration: String? = null,
3
    val cycle: String? = null,
4
    val date: String? = null,
5
) {
6
    init {
7
        require(listOfNotNull(duration, cycle, date).size == 1) {
8
            "TimerDefinition requires exactly one of duration, cycle, or date"
9
        }
10
    }
11
}

Setting both duration and date throws at DSL evaluation time — before the AST even exists.

The container builders

CollaborationBuilder and ParticipantBuilder are flat collectors; participant { } produces two AST objects — the ParticipantDefinition and the ProcessDefinition it references:

1
@BpmnDsl
2
class ParticipantBuilder internal constructor(private val id: String) {
3
    var name: String? = null
4
    var executable: Boolean = false
5
    var documentation: String? = null
6

7
    private var process: ProcessDefinition? = null
8

9
    fun process(id: String, block: ProcessBuilder.() -> Unit) {
10
        check(process == null) { "participant '$id' already declares a process" }
11
        process = ProcessBuilder(id).apply(block).build(isExecutable = executable)
12
    }
13

14
    internal fun build(): Pair<ParticipantDefinition, ProcessDefinition?> =
15
        ParticipantDefinition(id = id, name = name,
16
            documentation = documentation?.let(::Documentation),
17
            processRef = process?.id) to process
18
}

Note the direction of the executable flag: participant { executable = true } is what the author writes, but isExecutable is a property of the process element in BPMN XML — the builder translates authoring intent into the correct placement.

Mutable builders, immutable product

The asymmetry is the design. Builders are unashamedly mutable (var name, mutableListOf) because authoring order is imperative — you declare things in sequence. The AST is rigidly immutable (val, List, data classes) because everything downstream — validation, layout, serialization — must be deterministic and shareable. The boundary between them is each builder’s build(), called exactly once when the lambda returns.

Verification

kotlinc is the first test. Beyond that, one test proves the plumbing does what the syntax claims:

1
@Test
2
fun `dsl compiles to an immutable ast`() {
3
    val c = bpmnCollaboration("tiny") {
4
        participant("pool") {
5
            executable = true
6
            process("proc") {
7
                lane("work") {
8
                    startEvent("start")
9
                    serviceTask("doWork") { delegate = "worker" }
10
                    endEvent("done")
11
                }
12
                sequenceFlow("f1", "start", "doWork")
13
                sequenceFlow("f2", "doWork", "done")
14
            }
15
        }
16
    }
17
    val proc = c.processes.single()
18
    assertEquals(3, proc.nodes.size)                                   // lane-owned nodes landed in the process
19
    assertTrue(proc.nodes[0] is StartEvent)
20
    assertEquals("worker", (proc.nodes[1] as ServiceTask).metadata["delegate"])
21
}

Common pitfalls

Forgetting @DslMarker, then discovering scope collisions in review: documentation = "..." inside a nested block mutates the inner receiver when you meant the outer — with a marker, the outer receiver is unreachable.
Exposing the same function on every builder. A messageFlow on a lane scope would silently accept cross-pool edges; restrict functions to the scopes where the construct is legal.
build() in the public API. Once authors can call build() and re-use a builder, mutable builders leak. Keep it internal.
Optional parameters for semantic distinctions. sequenceFlow(id, from, to, condition = null) invites accidental conditional flows; separate names keep call sites honest.

Reference implementation

The full builder layer is Dsl.kt in the bpmn-dsl module of pcnixsys/bpmn-dsl-kotlin — the @BpmnDsl marker, the FlowNodeContainer/SequenceFlowContainer scope split, BoundaryAttachable, and every builder this chapter introduced.

Part 4 uses this DSL to write the entire procurement collaboration end-to-end — and hits the chapter’s real BPMN problem: how to model “budget approval sometimes required, legal review sometimes required” without building a parallel gateway that deadlocks.

KotlinBPMN