Java API
Maven dependency
Section titled “Maven dependency”<dependency>
<groupId>io.mateu.workflow</groupId>
<artifactId>workflow-engine</artifactId>
<version>2.42.1</version>
</dependency>
Entry points
Section titled “Entry points”ProcessUpstreamEventUseCase
Section titled “ProcessUpstreamEventUseCase”The main entry point for integration events. Handles process creation, task status updates, message delivery, and timeout/timer checks.
@AutowiredProcessUpstreamEventUseCase processUpstreamEventUseCase;
// Start a processprocessUpstreamEventUseCase.handle(new ProcessUpstreamEventCommand( new ProcessCreationRequested( "workflow-id", "business-key", List.of(new Variable("key", "value")) )));CancelProcessUseCase and RetryProcessUseCase
Section titled “CancelProcessUseCase and RetryProcessUseCase”Cancellation and retry are dedicated use cases (they are not upstream events):
@AutowiredCancelProcessUseCase cancelProcessUseCase;cancelProcessUseCase.handle(new CancelProcessCommand(processId));
@AutowiredRetryProcessUseCase retryProcessUseCase;retryProcessUseCase.handle(new RetryProcessCommand(processId));PauseProcessUseCase and ResumeProcessUseCase
Section titled “PauseProcessUseCase and ResumeProcessUseCase”Pause a PENDING/RUNNING process (→ PAUSED) and resume it (→ RUNNING). Pause holds
the frontier, not in-flight work: worker reports and messages are still accepted, but
successors do not start and timer/timeout clocks freeze (shifted forward by the pause
duration on resume). See Statuses — Pause semantics.
@AutowiredPauseProcessUseCase pauseProcessUseCase;pauseProcessUseCase.handle(new PauseProcessCommand(processId));
@AutowiredResumeProcessUseCase resumeProcessUseCase;resumeProcessUseCase.handle(new ResumeProcessCommand(processId));PauseWorkflowUseCase and ResumeWorkflowUseCase
Section titled “PauseWorkflowUseCase and ResumeWorkflowUseCase”Pause/resume a whole workflow definition by id (a plain String, no command record):
pausing sets the definition’s runtime paused flag and pauses all its PENDING/RUNNING
processes; while paused, new instances (cron included) are created born-PAUSED. Resuming
clears the flag and resumes all the definition’s PAUSED processes.
@AutowiredPauseWorkflowUseCase pauseWorkflowUseCase;pauseWorkflowUseCase.handle(workflowDefinitionId);
@AutowiredResumeWorkflowUseCase resumeWorkflowUseCase;resumeWorkflowUseCase.handle(workflowDefinitionId);UpdateStepExecutionUseCase
Section titled “UpdateStepExecutionUseCase”Reports task progress from workers. Available as a Spring bean — inject it anywhere.
@AutowiredUpdateStepExecutionUseCase updateStepExecution;
updateStepExecution.handle(new UpdateStepExecutionCommand( taskExecutionId, List.of(new Variable("result", "ok")), "Optional log message", StepExecutionStatus.COMPLETED));Valid StepExecutionStatus values for reporting: RUNNING, COMPLETED, ERROR.
Note: the command’s first record component is named stepId in the source, but the
value to pass is the task execution id received in TaskExecutionRequested (it is
the step execution id, not the step id from the definition). The Variable here is
io.mateu.workflow.domain.aggregates.Variable.
Repositories
Section titled “Repositories”ProcessRepository
Section titled “ProcessRepository”Extends CrudStore<Process> and adds findByBusinessKey and countByStatus.
@AutowiredProcessRepository processRepository;
// Find by IDOptional<Process> process = processRepository.findById(processId);
// Find by business keyOptional<Process> process = processRepository.findByBusinessKey("order-123");
// List allList<Process> processes = processRepository.findAll();
// Count by status (there is no findByStatus — filter findAll() for listings)long running = processRepository.countByStatus(ProcessStatus.RUNNING);StepExecutionRepository
Section titled “StepExecutionRepository”Extends CrudStore<StepExecution> and adds a few query methods:
@AutowiredStepExecutionRepository stepExecutionRepository;
// Find by process (takes the aggregate, not an id)List<StepExecution> steps = stepExecutionRepository.findByProcess(process);
// Steps awaiting or in execution, system-wideList<StepExecution> active = stepExecutionRepository.findPendingOrRunning();
// …or of a single process. Prefer this whenever you know the process: the// system-wide query grows with every step waiting anywhere in the engine.List<StepExecution> live = stepExecutionRepository.findPendingOrRunningByProcessId(processId);
// Live steps whose deadline (a TIMER's due moment, or a step timeout) has passed.// This is what the scheduler uses; it is an indexed lookup on the deadline, so it// costs what is due rather than what is waiting.List<StepExecution> due = stepExecutionRepository.findDue(LocalDateTime.now());
// The WAIT_FOR_MESSAGE steps subscribed to a message under a correlation key.// A null key matches nothing — an unevaluable correlation expression fails closed.List<StepExecution> subscribed = stepExecutionRepository.findWaitingForMessage("payment-received", "booking-42");WorkflowDefinitionRepository
Section titled “WorkflowDefinitionRepository”A plain CrudStore<WorkflowDefinition>:
@AutowiredWorkflowDefinitionRepository workflowDefinitionRepository;
// Find by IDOptional<WorkflowDefinition> def = workflowDefinitionRepository.findById("my-workflow");
// List runnable definitions (not disabled, not archived)List<WorkflowDefinition> active = workflowDefinitionRepository.findAll().stream() .filter(d -> !d.disabled() && !d.archived()) .toList();
// Save/updateworkflowDefinitionRepository.save(definition);Embedded worker interface
Section titled “Embedded worker interface”@FunctionalInterfacepublic interface EmbeddedTaskExecutor { void execute(TaskExecutionRequested request);}Register one such bean. Embedded mode has no transport to route over, so every ACTION step goes
to it regardless of the step’s topic — the bean name is not matched against anything — and you
branch on request.stepId() inside it. (Per-step routing by topic is a Kafka-mode feature.)
@Beanpublic EmbeddedTaskExecutor myWorker(UpdateStepExecutionUseCase updateStepExecution) { return request -> { // ... do work ... updateStepExecution.handle(new UpdateStepExecutionCommand( request.taskExecutionId(), List.of(), "", StepExecutionStatus.COMPLETED )); };}Domain model
Section titled “Domain model”Process
Section titled “Process”| Field | Type | Description |
|---|---|---|
id | String | Unique process ID |
name | String | Name of the workflow definition at creation time |
workflowDefinitionId | String | ID of the workflow definition |
workflowDefinitionVersion | int | Version of the definition the process runs on |
businessKey | String | Optional human-readable identifier |
status | ProcessStatus | Current status |
completionPercentage | int | Progress indicator (0–100) |
variables | List<Variable> | Process variables |
created | LocalDateTime | Creation timestamp |
started | LocalDateTime | When execution started |
finished | LocalDateTime | When the process reached a terminal status |
pausedAt | LocalDateTime | Set while the process is PAUSED; used to shift step clocks on resume. null otherwise |
StepExecution
Section titled “StepExecution”| Field | Type | Description |
|---|---|---|
id | String | Unique step execution ID — this is the taskExecutionId that workers receive and must echo back in UpdateStepExecutionCommand |
processId | String | Parent process ID |
workflowDefinitionId | String | Workflow definition ID |
stepId | String | Step ID from the workflow definition |
status | StepExecutionStatus | Current status |
workerId | String | Worker that took the task |
order | long | Execution order within the process |
startedAt | LocalDateTime | When the step started |
finishedAt | LocalDateTime | Set when the step reaches a terminal status |
attemptCount | int | Attempts already made (0 = first attempt, 1 = first retry, …) |
Variable
Section titled “Variable”record Variable(String name, String value) {}There are two Variable records with this shape: io.mateu.workflow.dtos.Variable
(used by the integration events TaskExecutionRequested, TaskStatusChanged,
ProcessCreationRequested) and io.mateu.workflow.domain.aggregates.Variable
(used by UpdateStepExecutionCommand and the aggregates). Import the one that
matches the API you are calling — they are not interchangeable.
WorkflowDefinition
Section titled “WorkflowDefinition”| Field | Type | Description |
|---|---|---|
id | String | Unique workflow ID |
name | String | Human-readable name |
description | String | Optional description |
version | int | Version number |
paused | boolean | Runtime flag (not in the definition file): while true, the definition’s processes are held and new instances are created born-PAUSED |
disabled | boolean | Runtime flag (not in the definition file): while true, accepts no new instances |
archived | boolean | Runtime flag (not in the definition file): set by the git-import prune to hide a removed definition |
cronExpression | String | Optional Spring cron expression for scheduled starts |
limitConcurrentExecutions | boolean | Whether to cap concurrent processes |
maxConcurrentExecutions | int | The cap, when limited |
enqueueOnLimit | boolean | Queue starts that exceed the cap instead of rejecting them |
defaultMaxStepExecutions | int | Default per-step execution cap (0 = unbounded) |
steps | List<Step> | Step definitions |