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).
What it checks
Section titled “What it checks”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) andcompensationStepIdreferences, the entry-point rule (every step with no preconditions must be aSTARTor aWAIT_FOR_MESSAGE, and aSTARTmust have none), precondition-cycle detection (DFS over the multi-edge precondition graph), thePROCESSchild id (childWorkflowDefinitionIdpresent and different from the workflow’s own id), cron-expression validity, and JEXL parseability ofpreconditionExpression, the conditions onpreconditionslinks, andcorrelationExpression. It also emits build-time warnings (logged, never failing the build) for risky-but-legal patterns: currently, aJOINwaiting 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
whencell per input, onethencell per output) and JEXL parseability of expressions. - Forms — schema validation.
- Tasks — schema validation of each
.ectask, plus cross-file checks: anidbelongs to exactly onegroup, no two files define the sameid@version, and every task an ACTION step references exists (with the pinned version, if one is given). Checking that a referenced task’srequiredinputs 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'.Configuration
Section titled “Configuration”| Parameter | Property | Default | Description |
|---|---|---|---|
workflowsDirectory | ${basedir}/src/main/resources/workflows | Workflow definitions directory. | |
formsDirectory | ${basedir}/src/main/resources/forms | Form definitions directory (validated only; forms ship via forms directory/git import). | |
rulesDirectory | ${basedir}/src/main/resources/rules | Rule definitions directory. | |
tasksDirectory | ${basedir}/src/main/resources/tasks | Task contracts directory. | |
validateWorkflows | eventconductor.validate.workflows | true | Validate workflows. |
validateForms | eventconductor.validate.forms | true | Validate forms. |
validateRules | eventconductor.validate.rules | true | Validate rules. |
validateTasks | eventconductor.validate.tasks | true | Validate task contracts. |
failOnError | eventconductor.validate.failOnError | true | Fail the build on violations (otherwise warn). |
failOnMissing | eventconductor.validate.failOnMissing | false | Fail if a configured directory has no definitions. |
skip | eventconductor.validate.skip | false | Skip 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.
mvn eventconductor:check-migration -Dfrom=v3 # a git tag or ref, against the working copymvn eventconductor:check-migration -Dfrom=v3 -Dto=v4mvn eventconductor:check-migration -Dfrom=released/workflows -Dmapping=src/main/resources/migration.yamlfrom 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.
| Parameter | Property | Default | Description |
|---|---|---|---|
from | from | (required) | The version processes run now: current, a path, or a git ref. |
to | to | current | The version to move them to. |
mapping | mapping | YAML/JSON file {<workflow id>: {<old step>: <new step>}}; an empty target says “no counterpart”. | |
workflow | workflow | Only this workflow. | |
workflowsDirectory | ${basedir}/src/main/resources/workflows | Workflow definitions directory. | |
failOnError | eventconductor.migration.failOnError | true | Fail the build on errors (otherwise warn). |
skip | eventconductor.migration.skip | false | Skip the check. |
Everything at once: the verify goal
Section titled “Everything at once: the verify goal”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>mvn verify -Deventconductor.migration.from=origin/main # one command for CImvn 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-roomBound 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.
| Parameter | Property | Default | Description |
|---|---|---|---|
workflowsDirectory, formsDirectory, rulesDirectory, tasksDirectory | as for validate | What validate and check-migration read. | |
failOnMissing | eventconductor.validate.failOnMissing | false | As for validate. |
skipValidation | eventconductor.verify.skipValidation | false | Leave validate out. |
migrationFrom | eventconductor.migration.from | The version processes run now (a git ref, a path, current). Unset: no migration check. | |
migrationTo | eventconductor.migration.to | current | The version to move them to. |
migrationMapping | eventconductor.migration.mapping | The step mapping file, as check-migration’s mapping. | |
coverageReport | eventconductor.coverage.report | ${project.build.directory}/eventconductor-coverage/coverage.json | The report workflow-test writes. |
minStepCoverage | eventconductor.coverage.minSteps | The lowest share of steps (percent) the tests must run. Unset: no floor. | |
minBranchCoverage | eventconductor.coverage.minBranches | The lowest share of branches (percent) — CHOICE branches, guarded links, timeout routes, compensations, loop-backs — the tests must take. Unset: no floor. | |
skip | eventconductor.verify.skip | false | Skip 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>| Parameter | Property | Default | Description |
|---|---|---|---|
basePackage | eventconductor.generate.basePackage | io.mateu.workflow.tasks.generated | Base package; a contract’s group is appended as a sub-package. |
tasksDirectory | ${basedir}/src/main/resources/tasks | Local contracts, used when neither definitions nor repository is set. | |
definitions | eventconductor.generate.definitions | Definitions Maven artifact groupId:artifactId:version (resolved as a zip). | |
repository | eventconductor.generate.repository | Git repository URL for the definitions. | |
ref | eventconductor.generate.ref | Git tag or commit to check out (a branch needs allowBranch). | |
allowBranch | eventconductor.generate.allowBranch | false | Allow a git branch ref (warns instead of failing). |
group | eventconductor.generate.group | Generate only these groups (comma-separated). | |
tasks | eventconductor.generate.tasks | Generate only these tasks (id or id@version, comma-separated). | |
applicationClass | eventconductor.generate.applicationClass | Also generate this @SpringBootApplication class (a standalone service). | |
skip | eventconductor.generate.skip | false | Skip generation entirely. |