Skip to content

Maven Plugin: validating definitions

Because EventConductor definitions are data owned by developers — flat JSON/YAML files in a pull request — you can validate them the same way you validate any other source: at build time. The workflow-maven-plugin checks every workflow, form and rule definition against the same JSON schemas the engine ships plus most of the engine’s semantic checks, and fails the build on any problem, so most mistakes are caught in the PR rather than at runtime when the engine loads them (see what it checks for the checks that still only happen at engine load).

The plugin bundles the same JSON schemas the engine ships (workflow-definition-schema.json, form-schema.json, rule-schema.json — copied straight from the engine modules at build time, so it can never drift), plus the semantic checks a schema cannot express:

  • Workflows — schema, duplicate step ids, self-referencing / dangling precondition (preconditions / preconditionStepIds / preconditionStepId) and compensationStepId references, the entry-point rule (every step with no preconditions must be a START or a WAIT_FOR_MESSAGE, and a START must have none), precondition-cycle detection (DFS over the multi-edge precondition graph), the PROCESS child id (childWorkflowDefinitionId present and different from the workflow’s own id), cron-expression validity, and JEXL parseability of preconditionExpression, the conditions on preconditions links, and correlationExpression. It also emits build-time warnings (logged, never failing the build) for risky-but-legal patterns: currently, a JOIN waiting directly on a guarded step — if the guard is false the join never fires and the flow beyond it is silently cancelled.
  • Rules — schema, decision-table row arity (one when cell per input, one then cell per output) and JEXL parseability of expressions.
  • Forms — schema validation.
  • Tasks — schema validation of each .ectask, plus cross-file checks: an id belongs to exactly one group, no two files define the same id@version, and every task an ACTION step references exists (with the pinned version, if one is given). Checking that a referenced task’s required inputs are actually reachable in the graph (start variables, branches, JOINs) is a documented TODO — it needs the same dataflow analysis the engine does at runtime.
<plugin>
<groupId>io.mateu.workflow</groupId>
<artifactId>workflow-maven-plugin</artifactId>
<version>${eventconductor.version}</version> <!-- the same version as workflow-engine -->
<executions>
<execution>
<goals>
<goal>validate</goal>
</goals>
</execution>
</executions>
</plugin>

The validate goal binds to process-resources and scans, under the project resources, the same layout the engine loads from the classpath:

src/main/resources/
workflows/**/*.{ec,ecform,ecrule,ectask,json,yaml,yml}
forms/**/*.{ec,ecform,ecrule,ectask,json,yaml,yml}
rules/**/*.{ec,ecform,ecrule,ectask,json,yaml,yml}
tasks/**/*.{ec,ecform,ecrule,ectask,json,yaml,yml}

The same extensions the engine imports. Workflows, rules and task contracts are also what the engines load from the classpath. Forms are not: the forms engine imports them with forms.directory-import.directories or forms.git-import (whose directory can name this folder in the repository), so src/main/resources/forms/ is only the default place the plugin validates them — point formsDirectory at wherever your forms really live. The plugin logs a reminder when it validates forms. .ec, .ecform and .ecrule are what the graph editor and the two IDE plugins write (alongside *.ec.yaml, the recommended name for a workflow, collected as a .yaml), and they were not collected before 2.2.3 — a repository of them was walked, nothing was found, and the build passed. Anything that is not .json is read by the YAML parser, which reads JSON too, so an .ec holding either parses.

Run it in the build (mvn verify) or on demand with mvn eventconductor:validate. On a violation the build fails with a per-file report:

EventConductor definition validation found 2 problem(s):
src/main/resources/workflows/order.ec.yaml:
- 'not a cron' is not a valid cron expression
- Step 's1' references unknown precondition step 'nope'.
ParameterPropertyDefaultDescription
workflowsDirectory${basedir}/src/main/resources/workflowsWorkflow definitions directory.
formsDirectory${basedir}/src/main/resources/formsForm definitions directory (validated only; forms ship via forms directory/git import).
rulesDirectory${basedir}/src/main/resources/rulesRule definitions directory.
tasksDirectory${basedir}/src/main/resources/tasksTask contracts directory.
validateWorkflowseventconductor.validate.workflowstrueValidate workflows.
validateFormseventconductor.validate.formstrueValidate forms.
validateRuleseventconductor.validate.rulestrueValidate rules.
validateTaskseventconductor.validate.taskstrueValidate task contracts.
failOnErroreventconductor.validate.failOnErrortrueFail the build on violations (otherwise warn).
failOnMissingeventconductor.validate.failOnMissingfalseFail if a configured directory has no definitions.
skipeventconductor.validate.skipfalseSkip validation entirely.

Checking a migration: the check-migration goal

Section titled “Checking a migration: the check-migration goal”

Before a new version of a workflow ships, check-migration checks that the processes running the old one could be migrated onto it: every step of the old version a process can be waiting in needs a compatible counterpart in the new one — by id, or by a mapping file. The same rules the engine applies when it migrates a process (MigrationRules in definition-analysis), on the two definitions alone.

Terminal window
mvn eventconductor:check-migration -Dfrom=v3 # a git tag or ref, against the working copy
mvn eventconductor:check-migration -Dfrom=v3 -Dto=v4
mvn eventconductor:check-migration -Dfrom=released/workflows -Dmapping=src/main/resources/migration.yaml

from and to are each current (the workflows directory), a path (a definition file or a directory of them) or a git ref, read with git show <ref>:<file> for every definition file under the workflows directory. Steps without a compatible counterpart that a process can wait in fail the build; instantaneous steps, changed task contracts, forEach items, locks and fewer escalation levels are warnings; a workflow missing from to is a warning.

ParameterPropertyDefaultDescription
fromfrom(required)The version processes run now: current, a path, or a git ref.
totocurrentThe version to move them to.
mappingmappingYAML/JSON file {<workflow id>: {<old step>: <new step>}}; an empty target says “no counterpart”.
workflowworkflowOnly this workflow.
workflowsDirectory${basedir}/src/main/resources/workflowsWorkflow definitions directory.
failOnErroreventconductor.migration.failOnErrortrueFail the build on errors (otherwise warn).
skipeventconductor.migration.skipfalseSkip the check.

verify is what CI runs: validate, then check-migration (when migrationFrom says what processes run now), then the workflow coverage the test kit recorded against its floors (when any is set). Every check runs, and the build fails once, listing what each found.

<execution>
<id>eventconductor-verify</id>
<goals><goal>verify</goal></goals> <!-- binds to the verify phase, after the tests -->
<configuration>
<minStepCoverage>90</minStepCoverage>
<minBranchCoverage>75</minBranchCoverage>
</configuration>
</execution>
Terminal window
mvn verify -Deventconductor.migration.from=origin/main # one command for CI
mvn eventconductor:verify -Deventconductor.migration.from=v3 -Deventconductor.coverage.minBranches=80
[INFO] EventConductor workflow coverage: steps 45/47 (95.7%), branches 4/6 (66.7%), edges 34/36 (94.4%)
[ERROR] EventConductor verify failed:
[ERROR]
[ERROR] [coverage] branches coverage is 66.7%, below the minimum of 75.0%
[ERROR] Not covered:
[ERROR] rooms-booking-http: step cancel-room, compensation rooms → cancel-room

Bound to the verify phase it runs after the tests, which is when the coverage report exists; a floor with no report fails (the tests did not run, or ran without workflow-test). With validate also bound to an earlier phase, set skipValidation on the verify execution so the definitions are not validated twice.

ParameterPropertyDefaultDescription
workflowsDirectory, formsDirectory, rulesDirectory, tasksDirectoryas for validateWhat validate and check-migration read.
failOnMissingeventconductor.validate.failOnMissingfalseAs for validate.
skipValidationeventconductor.verify.skipValidationfalseLeave validate out.
migrationFromeventconductor.migration.fromThe version processes run now (a git ref, a path, current). Unset: no migration check.
migrationToeventconductor.migration.tocurrentThe version to move them to.
migrationMappingeventconductor.migration.mappingThe step mapping file, as check-migration’s mapping.
coverageReporteventconductor.coverage.report${project.build.directory}/eventconductor-coverage/coverage.jsonThe report workflow-test writes.
minStepCoverageeventconductor.coverage.minStepsThe lowest share of steps (percent) the tests must run. Unset: no floor.
minBranchCoverageeventconductor.coverage.minBranchesThe lowest share of branches (percent) — CHOICE branches, guarded links, timeout routes, compensations, loop-backs — the tests must take. Unset: no floor.
skipeventconductor.verify.skipfalseSkip every check.

Generating worker types: the generate-worker-sources goal

Section titled “Generating worker types: the generate-worker-sources goal”

The second goal turns task contracts into the Java a worker developer implements against — records, a <Id>V<n>Task interface per contract version, a TaskFailure subclass per declared error, and a per-group @AutoConfiguration that registers each implemented handler. It binds to generate-sources, writes to target/generated-sources (added as a compile root) and a generated resources root (the AutoConfiguration.imports), and never emits code you edit. Most projects get it for free by inheriting task-module-parent or task-service-parent; see implementing workers and the task contract format.

The contracts come from, in order of precedence: a Maven artifact (definitions, a versioned zip — the reproducible default), a git checkout (repository + ref, pinned to a tag or commit; a branch is refused unless allowBranch), or the project’s own tasksDirectory. Select a subset with group or tasks.

<plugin>
<groupId>io.mateu.workflow</groupId>
<artifactId>workflow-maven-plugin</artifactId>
<executions>
<execution>
<goals><goal>generate-worker-sources</goal></goals>
</execution>
</executions>
<configuration>
<basePackage>com.example</basePackage>
<group>greetings</group>
</configuration>
</plugin>
ParameterPropertyDefaultDescription
basePackageeventconductor.generate.basePackageio.mateu.workflow.tasks.generatedBase package; a contract’s group is appended as a sub-package.
tasksDirectory${basedir}/src/main/resources/tasksLocal contracts, used when neither definitions nor repository is set.
definitionseventconductor.generate.definitionsDefinitions Maven artifact groupId:artifactId:version (resolved as a zip).
repositoryeventconductor.generate.repositoryGit repository URL for the definitions.
refeventconductor.generate.refGit tag or commit to check out (a branch needs allowBranch).
allowBrancheventconductor.generate.allowBranchfalseAllow a git branch ref (warns instead of failing).
groupeventconductor.generate.groupGenerate only these groups (comma-separated).
taskseventconductor.generate.tasksGenerate only these tasks (id or id@version, comma-separated).
applicationClasseventconductor.generate.applicationClassAlso generate this @SpringBootApplication class (a standalone service).
skipeventconductor.generate.skipfalseSkip generation entirely.