bpmn-to-code

Type-safe constants from your BPMN model, for your compiler, your tests and your AI agents.

bpmn-to-code reads your BPMN files and generates a typed API from them. Element ids, message names and job types become constants, so renaming a task in the modeler is a compiler error instead of a silent runtime failure.

// Before: copied from the modeler, no safety net
@JobWorker(type = "miravelo.sendContract")
fun send() { ... }

// After: generated from the BPMN model
@JobWorker(type = ServiceTasks.MIRAVELO_SEND_CONTRACT)
fun send() { ... }

Around the generator:

• Validation: built-in rules run before every generation, as a build task, or as tests with bpmn-to-code-testing, where you can add your own rules.
• Agent Skills: a Claude Code plugin that sets up the build plugin, migrates hardcoded strings, and writes and tests workers, process adapters and process tests against the generated API.
• Command line: generate and validate without Gradle or Maven, also as a .NET tool and an npm package (both not yet published); the archives bring their own Java runtime, the .NET tool and the npm package need Java 21.
• Web app: try it in the browser, or self-host the Docker image.

What it helps with

A BPMN model and the code around it drift apart quietly: someone changes a name in the modeler and nothing tells the code. With the generated API, that change shows up in your build after you regenerate.

In production code

A worker that carries its topic as a string keeps compiling when the topic changes in the model, and the instance just waits. With the generated constant, the build points at the worker.

In process tests

A test with hand-typed element ids only fails when it runs. Built from the generated flow nodes with ProcessPath, it stops compiling instead.

With any engine and any test framework

The clips show Camunda 8 and Kotlin, but nothing depends on that. The generated API is plain constants and objects, without a dependency on an engine, a worker library or a test framework. A ProcessPath hands you plain element ids, so it fits whatever flow assertion your test library offers. It works the same for every supported engine and output language.

Gradle

import io.miragon.bpmn.adapter.GenerateBpmnModelsTask
import io.miragon.bpmn.domain.shared.OutputLanguage
import io.miragon.bpmn.domain.shared.ProcessEngine

plugins {
    id("io.miragon.bpmn-to-code-gradle") version "7.0.1"
}

tasks.named("generateBpmnModelApi", GenerateBpmnModelsTask::class) {
    baseDir = projectDir.toString()
    filePattern = "src/main/resources/**/*.bpmn"
    outputFolderPath = "$projectDir/src/main/kotlin"
    packagePath = "com.example.process"
    outputLanguage = OutputLanguage.KOTLIN
    processEngine = ProcessEngine.ZEEBE
}

Run it with ./gradlew generateBpmnModelApi. The plugin adds the bpmn-to-code-runtime dependency by itself. Details: Gradle guide.

Maven

The goals are not bound to a lifecycle phase by default, so bind the goal yourself, and add the runtime library the generated code refers to:

<dependencies>
    <dependency>
        <groupId>io.miragon</groupId>
        <artifactId>bpmn-to-code-runtime</artifactId>
        <version>7.0.1</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>io.miragon</groupId>
            <artifactId>bpmn-to-code-maven</artifactId>
            <version>7.0.1</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals><goal>generate-bpmn-api</goal></goals>
                </execution>
            </executions>
            <configuration>
                <baseDir>${project.basedir}</baseDir>
                <filePattern>src/main/resources/*.bpmn</filePattern>
                <outputFolderPath>${project.basedir}/src/main/java</outputFolderPath>
                <packagePath>com.example.process</packagePath>
                <outputLanguage>JAVA</outputLanguage>
                <processEngine>ZEEBE</processEngine>
            </configuration>
        </plugin>
    </plugins>
</build>

Details: Maven guide. All parameters of both plugins: Configuration.

Supported engines

Engine	processEngine
Camunda 8 / Zeebe	ZEEBE
Camunda 7, CIB seven	CAMUNDA_7
Operaton	OPERATON

Supported output languages

Language	outputLanguage	Runtime types
Kotlin	KOTLIN	io.miragon:bpmn-to-code-runtime
Java	JAVA	io.miragon:bpmn-to-code-runtime
C# (experimental)	CSHARP	Miragon.BpmnToCode.Runtime (NuGet, not yet published)
TypeScript (experimental)	TYPESCRIPT	@miragon/bpmn-to-code-runtime (npm, not yet published)

C# and TypeScript output are experimental and may change in a minor release; their NuGet and npm packages are not published yet. C# and TypeScript output are available in the Gradle and Maven plugins, the command line and the web app; C# also during dotnet build through Miragon.BpmnToCode.MSBuild.

Links

• Documentation
• Why bpmn-to-code
• Changelog and migration guides
• Contributing

Issues, pull requests and discussions are welcome on GitHub.

bpmn-to-code is built and maintained by Miragon.