BPMN 2.0 processes written in Java: the annotated code is the single source of truth.
bpmncode is a library for Spring Boot applications that turns annotated Java methods into BPMN 2.0 processes. There
are no hand-maintained .bpmn files and no process engine: the diagram is derived from the code, the model is
validated at compile time and at startup, and at runtime it checks that the code follows the declared flow and stores
the evidence of each step.
@Process(id = "PER-REGISTRATION", name = "Person registration", version = 1)
public class PersonRegistration {
@StartEvent(id = "REQUEST-RECEIVED", name = "Request received",
outgoing = @SequenceFlow(targetRef = "ELIGIBILITY"))
public Result register(Request request) { … }
@ExclusiveGateway(id = "ELIGIBILITY", name = "Meets the rules?", businessRuleRefs = "R-PER-001",
outgoing = { @SequenceFlow(when = "ELIGIBLE", targetRef = "CREATE-PERSON", name = "Yes"),
@SequenceFlow(when = "NOT_ELIGIBLE", targetRef = "REJECTED", name = "No") })
Eligibility assess(…) { … }
@ServiceTask(id = "CREATE-PERSON", name = "Register person", outgoing = @SequenceFlow(targetRef = "COMPLETED"))
Person create(…) { … }
@EndEvent(id = "COMPLETED", name = "Registration completed")
Result complete(…) { … }
@EndEvent(id = "REJECTED", name = "Registration rejected")
Result reject(…) { … }
}- Annotations with the BPMN 2.0.2 vocabulary:
@Process,@StartEvent,@MessageStartEvent,@TimerStartEvent,@ServiceTask,@UserTask,@BusinessRuleTask,@SendTask,@ExclusiveGateway,@SequenceFlow,@EndEvent,@MessageEndEvent,@ErrorEndEvent,@Message,@ProcessError,@ProcessResource,@PotentialOwner,@HumanPerformer,@BusinessRule… - Validation at two moments: an annotation processor makes
javacfail with the errors local to each element, and at startup the full model is validated (reachability, cycles with no way out, references, unique ids…). An invalid model prevents the application from starting. - Execution with conformance, without an engine:
ProcessJournalrecords each step and rejects those that do not follow a declared sequence flow. Instances and their history are kept in memory, without a database, or in the application's database, with JPA or with JDBC, if it has one. - Versions: of processes (several coexist; each instance follows its own), of business rules and of the messages between processes, with contracts frozen by the fingerprint of their JSON schema.
- BPMN 2.0 XML export (semantic model and BPMN DI with automatic layout), valid against the OMG XSDs, ready for bpmn.io.
- Traceability Process → Flow node → Rule → Code → Message, with catalogs of where each rule is used and of the message contracts, and internationalization of every text in the model.
- Execution statistics: heatmap of each version of a process, path followed by each instance, instances waiting per node and counts per version.
- Optional web module, off by default: bpmn-js viewer with the card of each element, the path of an instance and the heatmap, plus a read-only API.
- Checks for your tests (
ProcessAssertions, in the test jar): BPMN valid against the OMG XSDs, every drawn element described and the path of an instance.
| Version | |
|---|---|
| Java | 21 or later (compiled for 21; also tested on 25) |
| Spring Boot | 4.1 |
| Database | optional: without one, instances are kept in memory; with JPA, or with a DataSource and spring-jdbc, in two tables |
<dependency>
<groupId>io.github.eldiegos</groupId>
<artifactId>bpmncode</artifactId>
<version>0.1.0</version>
</dependency>And, for the compile-time checks, the annotation processor in the maven-compiler-plugin:
<annotationProcessors>
<annotationProcessor>io.github.eldiegos.bpmncode.processor.ProcessAnnotationProcessor</annotationProcessor>
</annotationProcessors>The library configures itself through Spring Boot auto-configuration: it discovers the processes in the application's
packages and provides ProcessDefinitionRegistry, ProcessJournal, ProcessInstanceHistory, TraceabilityReport,
MessageContractCatalog, ProcessExecutionStatistics and BpmnDiagramService as beans. It only depends on spring-boot-autoconfigure and slf4j-api: it works in an
application without a database, without JPA and without Spring Modulith. If the application already has JPA, or
spring-jdbc and a DataSource, it stores the instances in its database (Storage). If it
uses Spring Modulith, it can verify that it only uses the library's public API
(Configuration).
Starting from scratch? Follow the step-by-step course, which builds a complete application.
| Guide | Content |
|---|---|
| Getting started | dependencies, annotation processor and a complete process step by step |
| Annotations | each annotation, its BPMN element, its attributes and the rules that bind it to the code |
| Model validation | compile-time and startup checks, and every error kind |
| Execution and conformance | ProcessJournal, instances, evidence, loops, history, transactions and idempotency |
| Storage | in memory, in a database (JPA or JDBC) or custom; tables, schema, transactions and how to test a custom store |
| Messages between processes | sealed versions, frozen contracts and the message header |
| Versions | process and business rule versions |
| BPMN, traceability and i18n | BPMN 2.0 export, pac: extensions, traceability report and text translation |
| Statistics and web module | heatmap, path of an instance and counts; optional bpmn-js viewer and read-only API |
| Configuration and integration | beans and how to replace them, properties, optional dependencies, Spring Modulith and application tests |
| Internal architecture | packages, public and internal API, how the model is read |
| Publishing | how a version is published to Maven Central |
| Code quality | coverage with JaCoCo and analysis with SonarQube in a container |
./mvnw verify # compiles and runs the tests
./mvnw -Prelease verify -Dgpg.skip # also sources and Javadoc jars
./mvnw -Psonar verify # also SonarQube analysis (needs Docker)Version 0.x: the API may change between minor versions until 1.0.
Distributed under the Apache License 2.0. You may use, modify and redistribute bpmncode, also in
commercial products, as long as you keep the copyright notice and the NOTICE file, which attributes the
original project. Both are also inside the jar, in META-INF/. If you cite it in a work, use the data in
CITATION.cff (GitHub offers it under "Cite this repository").