Skip to content

Java API

<dependency>
    <groupId>io.mateu.workflow</groupId>
    <artifactId>workflow-engine</artifactId>
    <version>2.42.1</version>
</dependency>

The main entry point for integration events. Handles process creation, task status updates, message delivery, and timeout/timer checks.

@Autowired
ProcessUpstreamEventUseCase processUpstreamEventUseCase;
// Start a process
processUpstreamEventUseCase.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):

@Autowired
CancelProcessUseCase cancelProcessUseCase;
cancelProcessUseCase.handle(new CancelProcessCommand(processId));
@Autowired
RetryProcessUseCase 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.

@Autowired
PauseProcessUseCase pauseProcessUseCase;
pauseProcessUseCase.handle(new PauseProcessCommand(processId));
@Autowired
ResumeProcessUseCase 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.

@Autowired
PauseWorkflowUseCase pauseWorkflowUseCase;
pauseWorkflowUseCase.handle(workflowDefinitionId);
@Autowired
ResumeWorkflowUseCase resumeWorkflowUseCase;
resumeWorkflowUseCase.handle(workflowDefinitionId);

Reports task progress from workers. Available as a Spring bean — inject it anywhere.

@Autowired
UpdateStepExecutionUseCase 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.

Extends CrudStore<Process> and adds findByBusinessKey and countByStatus.

@Autowired
ProcessRepository processRepository;
// Find by ID
Optional<Process> process = processRepository.findById(processId);
// Find by business key
Optional<Process> process = processRepository.findByBusinessKey("order-123");
// List all
List<Process> processes = processRepository.findAll();
// Count by status (there is no findByStatus — filter findAll() for listings)
long running = processRepository.countByStatus(ProcessStatus.RUNNING);

Extends CrudStore<StepExecution> and adds a few query methods:

@Autowired
StepExecutionRepository stepExecutionRepository;
// Find by process (takes the aggregate, not an id)
List<StepExecution> steps = stepExecutionRepository.findByProcess(process);
// Steps awaiting or in execution, system-wide
List<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");

A plain CrudStore<WorkflowDefinition>:

@Autowired
WorkflowDefinitionRepository workflowDefinitionRepository;
// Find by ID
Optional<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/update
workflowDefinitionRepository.save(definition);
@FunctionalInterface
public 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.)

@Bean
public EmbeddedTaskExecutor myWorker(UpdateStepExecutionUseCase updateStepExecution) {
return request -> {
// ... do work ...
updateStepExecution.handle(new UpdateStepExecutionCommand(
request.taskExecutionId(),
List.of(),
"",
StepExecutionStatus.COMPLETED
));
};
}
FieldTypeDescription
idStringUnique process ID
nameStringName of the workflow definition at creation time
workflowDefinitionIdStringID of the workflow definition
workflowDefinitionVersionintVersion of the definition the process runs on
businessKeyStringOptional human-readable identifier
statusProcessStatusCurrent status
completionPercentageintProgress indicator (0–100)
variablesList<Variable>Process variables
createdLocalDateTimeCreation timestamp
startedLocalDateTimeWhen execution started
finishedLocalDateTimeWhen the process reached a terminal status
pausedAtLocalDateTimeSet while the process is PAUSED; used to shift step clocks on resume. null otherwise
FieldTypeDescription
idStringUnique step execution ID — this is the taskExecutionId that workers receive and must echo back in UpdateStepExecutionCommand
processIdStringParent process ID
workflowDefinitionIdStringWorkflow definition ID
stepIdStringStep ID from the workflow definition
statusStepExecutionStatusCurrent status
workerIdStringWorker that took the task
orderlongExecution order within the process
startedAtLocalDateTimeWhen the step started
finishedAtLocalDateTimeSet when the step reaches a terminal status
attemptCountintAttempts already made (0 = first attempt, 1 = first retry, …)
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.

FieldTypeDescription
idStringUnique workflow ID
nameStringHuman-readable name
descriptionStringOptional description
versionintVersion number
pausedbooleanRuntime flag (not in the definition file): while true, the definition’s processes are held and new instances are created born-PAUSED
disabledbooleanRuntime flag (not in the definition file): while true, accepts no new instances
archivedbooleanRuntime flag (not in the definition file): set by the git-import prune to hide a removed definition
cronExpressionStringOptional Spring cron expression for scheduled starts
limitConcurrentExecutionsbooleanWhether to cap concurrent processes
maxConcurrentExecutionsintThe cap, when limited
enqueueOnLimitbooleanQueue starts that exceed the cap instead of rejecting them
defaultMaxStepExecutionsintDefault per-step execution cap (0 = unbounded)
stepsList<Step>Step definitions