v7 Migration Guide
Am I affected?
| Surface | Affected |
|---|---|
Gradle task generateBpmnModelJson (GenerateBpmnJsonTask) | yes, removed: a build that configures or calls it fails, see Process JSON |
Maven goal generate-bpmn-json | yes, removed: an execution of it fails, see Process JSON |
Web endpoint POST /api/generate-json | yes, removed: it answers 404, see Process JSON |
"Process JSON" tab of the web app, /static/json.html and ?tab=json | yes, removed: see Process JSON |
Build plugins as a source of kotlinx-serialization | yes if your build logic relied on it: the plugins no longer bring it onto the build classpath |
| Maven goals | yes if you rely on a default or on a relative path: see Maven parameters |
| Validate task (experimental) | yes: it checks what the generation checks, see Validation |
| Testing library, custom rules | yes: mandatory rules always run, BpmnValidationService changed, see Validation |
| Code that catches core's exceptions | yes: see Rejected models |
Code that uses BpmnModelApi, SharedDefinitionsApi, CollisionDetectionService or CollisionDetail from core's domain | yes, removed: see Domain types |
| Generated C# (experimental) | yes if a name used to get a trailing underscore: see C# names |
Maven parameters
Every parameter of the Maven goals is required, as in Gradle and the command-line tool. The goals no longer default baseDir to ., filePattern to src/main/resources/*.bpmn, outputFolderPath to src/main/kotlin or src/main/resources/bpmn-json, packagePath to de.emaarco.generated or outputLanguage to KOTLIN. A missing parameter fails the build naming it.
A relative baseDir or outputFolderPath resolves against the module's directory, as in Gradle, and no longer against the directory Maven is started in. Configurations that prefix both with ${project.basedir} keep working unchanged.
Validation
Generation, the validate task and the testing library run one pipeline on one list of built-in rules, BuiltInRules in core.
- Validate task.
validateBpmnModels,validate-bpmnand the commandvalidateleave out processes markedisExecutable="false", as the API generation does, and fail when two files would be generated under one name. A model the validate task accepts now generates. They fail with the message the generation fails with, the summary followed by one line per finding, and log warnings as the generation does. - Testing library. Mandatory rules can no longer be disabled, and they run when
withRules(...)leaves them out.BpmnRules.all()includesengine-mismatch(BpmnRules.ENGINE_MISMATCH). WithfailOnWarning(), rules across models run when the models have warnings only. BpmnValidationService.validate(models, engine)returns aValidationResultinstead of throwing;collectSingleModelViolations,collectCrossModelViolationsandvalidateAndNormalizeare gone. The mandatory rules run whatever list of rules it is given.
Rejected models
Every error the user has to fix in the BPMN files is a RejectedModelException from core's domain package: BpmnReadException (a file that is not readable BPMN), BpmnValidationException and ProcessApiNamingException. ProcessApiNamingException no longer extends IllegalArgumentException, and a file that cannot be read is no longer a plain IllegalStateException. The Maven goals report them as a build failure, the web app with status 400, and every entry point names the file with its path and extension.
Domain types
BpmnModelApi and SharedDefinitionsApi are removed from core's domain package. Code generation reads the models and settings of a run from ProcessApiRequest. The name of a Process API is ProcessApiNames.apiTypeName(model), which BpmnModelApi.fileName() returned.
CollisionDetectionService is removed and CollisionDetail is internal: CollisionDetectionRule and SharedDefinitionCollisionRule find the collisions themselves and no longer take the service as a constructor parameter.
C# names
C# no longer renames a name that clashes with a member it declares itself, as no other language does (ADR 006). Where 6.x appended _, generation now fails and names what to rename:
- an element whose type would be named like another element, as for
taskandtaskNode, - a variable named
all,inputs,outputs,processVariablesornodeVariables, - a call-activity mapping into
inputMappingsoroutputMappings, - a shared definition named like its class, such as a message
Messages.
Process JSON
v7.0.0 removes the Process JSON. Since 6.0 it was close to BPMN XML without the diagram, the generated Process API carries almost the same facts, and nothing consumed it.
What to do
- Remove the configuration of
generateBpmnModelJsonfrom your Gradle build, or thegenerate-bpmn-jsonexecution from yourpom.xml, together with anything that depends on it. - Delete the generated
.jsonfiles and their output folder (Maven default:src/main/resources/bpmn-json). Nothing removes them for you. - Point what read the files at one of the alternatives below.
Alternatives
| You used the JSON for | Use instead |
|---|---|
| Process facts in code: ids, job types, messages, signals, errors, timers, variables, sequence flows | the generated Process API |
| Context for an AI assistant | the .bpmn file and the generated Process API. Agents read both directly |
| Reviewing a process change as a text diff | the diff of the generated Process API, which changes whenever an id, a name, an implementation or a flow changes. Verify in CI keeps it in step with the model |
| Checks on the process structure in CI | validation rules, built-in or your own |
| Input for scripts and other tools | the BPMN XML, with a BPMN library such as bpmn-moddle, whose vocabulary the JSON followed |
Facts that only the JSON showed
These are not part of the generated Process API. Read them from the BPMN XML, or in a custom validation rule from the domain model:
| Fact | In the BPMN XML | In the domain model |
|---|---|---|
| Retries of a Zeebe job | retries of zeebe:taskDefinition | TaskImplementation.JobWorker.retries, TaskImplementation.Connector.retries |
| Connector template | zeebe:modelerTemplate on the task | TaskImplementation.Connector.templateId |
| Correlation key of a message | correlationKey of the message's zeebe:subscription | RootElementDefinition.Message.correlationKey |
| Engine extensions and attributes that bpmn-to-code does not normalise | bpmn:extensionElements and the attributes in the engine's namespace | FlowNodeDefinition.extensions, FlowNodeDefinition.engineAttributes |
The schema stays published
https://miragon.github.io/bpmn-to-code/schema/process-model/2.0.json keeps being served, so files written by 6.x still validate against the URL in their $schema. The plugin jars no longer contain a copy under META-INF/bpmn-to-code/schema.