Workflows

This reference covers every primitive, configuration option, and pattern available in the Axon Workflow Engine.

Note that the Workflow Engine is part of Axoniq Framework and requires a license for production use.

Status and compatibility

Java 21.
Axon Framework 5.4.x.
Kotlin DSL: axoniq-workflow-dsl-kotlin.
Spring Boot: included in axoniq-spring-boot-starter.

Workflow API boundaries

WorkflowContext is the author-facing contract supplied to a workflow body. The built-in BaseWorkflowContext and SimpleWorkflowContext implement that contract and add Java-friendly overloads. Use WorkflowContext (or one of those implementations) for workflow logic and custom workflow contexts.

The engine translates calls on the author-facing context to its internal WorkflowExecutionOperations contract. That runtime contract provides primitive operations and execution metadata; application workflow code does not need to depend on it. Event-message creation likewise uses the internal, read-only WorkflowEventPublicationContext rather than the full runtime-operation surface.

New to the engine? Start with the Getting Started tutorial first.

Example code

The Java and Kotlin examples in this guide are available in the workflow examples directory. They are compiled documentation samples, with supporting types for each topic. To compile them from the repository root with Java 21, run:

./mvnw -pl docs/_samples -am compile

Steps

Execute Steps: Run actions synchronously (awaitExecute) or asynchronously (execute)
Waiting for Events: Suspend until external events arrive (awaitEvent, waitForEvent, sleep)
Publishing Events: Publish a business event as a durable step (awaitPublish, publish); how workflows talk to each other
Understanding Steps: Cross-cutting concerns: timeouts, payload reducers, event naming, execution semantics

Workflow lifecycle

Workflow Lifecycle: States, fail vs cancel, lifecycle listeners
Error Handling: Step failure types, what is stored about an error, when a workflow fails and when it pauses and resumes
Managing Workflow Instances: Find workflow instances and request cancellation from outside a workflow (WorkflowManager)

Orchestration

Step Orchestration: Combinators: allMatch, anyMatch, noneMatch

Patterns

Common Patterns: Fan-out/fan-in, saga, scatter-gather, human-in-the-loop, circuit breaker, sub-workflows through published events

Data & configuration

Payload & State: Reading, setting, and managing durable workflow state
Configuration: Declarative setup, workflow modules, metadata propagation, custom contexts, multi-node operation (Running on several nodes)

Testing

Testing Workflows: BDD fixture tests and advanced workflow test driver usage

Code evolution

Workflow Versioning: ctx.migrateVersion(changeId, n) for safe evolution of in-flight workflows