Skip to content

v7 Migration Guide ​

Am I affected? ​

SurfaceAffected
Gradle task generateBpmnModelJson (GenerateBpmnJsonTask)yes, removed: a build that configures or calls it fails, see Process JSON
Maven goal generate-bpmn-jsonyes, removed: an execution of it fails, see Process JSON
Web endpoint POST /api/generate-jsonyes, removed: it answers 404, see Process JSON
"Process JSON" tab of the web app, /static/json.html and ?tab=jsonyes, removed: see Process JSON
Build plugins as a source of kotlinx-serializationyes if your build logic relied on it: the plugins no longer bring it onto the build classpath
Maven goalsyes 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 rulesyes: mandatory rules always run, BpmnValidationService changed, see Validation
Code that catches core's exceptionsyes: see Rejected models
Code that uses BpmnModelApi, SharedDefinitionsApi, CollisionDetectionService or CollisionDetail from core's domainyes, 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-bpmn and the command validate leave out processes marked isExecutable="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() includes engine-mismatch (BpmnRules.ENGINE_MISMATCH). With failOnWarning(), rules across models run when the models have warnings only.
  • BpmnValidationService. validate(models, engine) returns a ValidationResult instead of throwing; collectSingleModelViolations, collectCrossModelViolations and validateAndNormalize are 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 task and taskNode,
  • a variable named all, inputs, outputs, processVariables or nodeVariables,
  • a call-activity mapping into inputMappings or outputMappings,
  • 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 ​

  1. Remove the configuration of generateBpmnModelJson from your Gradle build, or the generate-bpmn-json execution from your pom.xml, together with anything that depends on it.
  2. Delete the generated .json files and their output folder (Maven default: src/main/resources/bpmn-json). Nothing removes them for you.
  3. Point what read the files at one of the alternatives below.

Alternatives ​

You used the JSON forUse instead
Process facts in code: ids, job types, messages, signals, errors, timers, variables, sequence flowsthe generated Process API
Context for an AI assistantthe .bpmn file and the generated Process API. Agents read both directly
Reviewing a process change as a text diffthe 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 CIvalidation rules, built-in or your own
Input for scripts and other toolsthe 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:

FactIn the BPMN XMLIn the domain model
Retries of a Zeebe jobretries of zeebe:taskDefinitionTaskImplementation.JobWorker.retries, TaskImplementation.Connector.retries
Connector templatezeebe:modelerTemplate on the taskTaskImplementation.Connector.templateId
Correlation key of a messagecorrelationKey of the message's zeebe:subscriptionRootElementDefinition.Message.correlationKey
Engine extensions and attributes that bpmn-to-code does not normalisebpmn:extensionElements and the attributes in the engine's namespaceFlowNodeDefinition.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.