Skip to content

Validation ​

bpmn-to-code checks your BPMN models against a set of rules. The same rules run in three places:

WhereRulesFails onCan be tuned
Generation: generateBpmnModelApi, the Maven goal generate-bpmn-api, the web appall built-in rulesany ERRORno
Validate task: validateBpmnModels / validate-bpmn (experimental)the same rulesany ERROR, with failOnWarning also any WARNfailOnWarning, disabledRules
Testing library: bpmn-to-code-testingthe built-in rules, opt-in rules and your ownwhatever your test assertsany rule but a mandatory one can be selected or disabled

Generation always validates first and writes nothing when a rule reports an ERROR: a service task without implementation, a timer without definition or a model built for another engine stops the run. Warnings are logged. There is no setting to relax this during generation: fix the model.

The validate task checks exactly what the generation of the Process API checks, without generating anything, so you can run it earlier in the build or with stricter settings. It fails as well when two files would be generated under one name.

Two details:

  • A process marked isExecutable="false" gets no Process API, so neither the API generation nor the validate task validates it.
  • Rules that compare processes with each other run only once every process is free of errors on its own.

Built-in rules ​

Rule IDSeverityWhat it reports
missing-service-task-implementationERRORService task with no implementation (Zeebe: no zeebe:taskDefinition type; Camunda 7 / Operaton: no topic, class or delegate expression)
missing-message-nameERRORMessage event, send task or receive task whose message has no name
missing-error-definitionERRORError event that references an error without a name or an error code. A catch-all error event that references no error passes
missing-signal-nameERRORSignal without a name
missing-timer-definitionERRORTimer event without a type (date, duration, cycle) or a value
missing-called-elementERRORCall activity that names no process to call
missing-element-idERRORFlow node without an id · mandatory
missing-process-idERRORProcess without an id · mandatory
empty-processWARNProcess without flow nodes
collision-detectionERRORWithin one process: two element IDs that would be generated under the same name (task_ship and task-ship), the same ID declared in two scopes, or two mapping targets of one call activity that normalize to the same constant · mandatory
reserved-element-nameERRORElement ID that would be generated as a name the Process API reserves (FlowNodes, All, Next, Instance, runtime types, shared definitions, C# node members like Id or Message, …) · mandatory
shared-definition-collisionERRORAcross all processes of the run: two different job types, messages, signals, errors, escalations or variables that normalize to the same constant name (order.created and order-created) · mandatory
engine-mismatchERROR / WARNERROR when the engine detected from the model's namespaces differs from the selected one; WARN when no engine can be detected

Mandatory rules guarantee that the generated code compiles under unique names. disabledRules cannot turn them off, in the testing library neither; listing one logs a warning and keeps it active.

The testing library adds unreferenced-root-element (WARN: a message, signal, error or escalation that no element references). Its opt-in rules are listed on the Testing Module page.

Validate task ​

Experimental

validateBpmnModels and validate-bpmn are experimental and may change in a minor release.

kotlin
import io.miragon.bpmn.adapter.ValidateBpmnModelsTask
import io.miragon.bpmn.domain.shared.ProcessEngine

tasks.named("validateBpmnModels", ValidateBpmnModelsTask::class) {
    baseDir = "."
    filePattern = "src/main/resources/**/*.bpmn"
    processEngine = ProcessEngine.ZEEBE
    failOnWarning = true
    disabledRules = setOf("empty-process")
}
xml
<plugin>
    <groupId>io.miragon</groupId>
    <artifactId>bpmn-to-code-maven</artifactId>
    <version>7.0.1</version>
    <executions>
        <execution>
            <id>validate-bpmn</id>
            <phase>verify</phase>
            <goals><goal>validate-bpmn</goal></goals>
            <configuration>
                <filePattern>src/main/resources/**/*.bpmn</filePattern>
                <processEngine>ZEEBE</processEngine>
                <failOnWarning>true</failOnWarning>
                <disabledRules>
                    <disabledRule>empty-process</disabledRule>
                </disabledRules>
            </configuration>
        </execution>
    </executions>
</plugin>

failOnWarning (default false) and disabledRules (default empty) are optional. All parameters and their defaults are listed in Configuration.

Run it:

bash
# Gradle: the task is registered by the plugin
./gradlew validateBpmnModels

# Maven: through the phase the execution is bound to
mvn verify

# Maven: the execution alone
mvn bpmn-to-code:validate-bpmn@validate-bpmn

The Maven goal is bound to no phase by default, so the execution needs a <phase>. @validate-bpmn names the execution whose configuration applies; without it Maven runs the goal with its defaults.

The task fails the way the generation fails: warnings are logged one per line, and a failing build names a summary followed by one line per finding:

> Task :validateBpmnModels FAILED
[EXPERIMENTAL] The 'validateBpmnModels' task is experimental and may change in future releases.

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':validateBpmnModels'.
> BPMN validation failed: 2 error(s), 0 warning(s)
  [BPMN VALIDATION ERROR] bikeLeasing/serviceTask_sendContract: Service task has no implementation. Add a zeebe:taskDefinition with a type attribute. (rule: missing-service-task-implementation)
  [BPMN VALIDATION ERROR] bikeLeasing/timer_signatureReminder: Timer event definition has no valid type (Date, Duration, or Cycle). (rule: missing-timer-definition)

Project-specific rules ​

The built-in rules cover what breaks generation or the engine. For your own conventions, write custom rules and run them with the testing library.