Quick Start
This guide gets you from zero to a running workflow in under 10 minutes using the fully embedded mode (no Kafka, no database needed).
Prerequisites
Section titled “Prerequisites”- Java 21+
- Maven 3.8+
- A Spring Boot 4 application — the simplest is a project whose
pom.xmlhasspring-boot-starter-parentas its parent (step 7 runs it with the Spring Boot Maven plugin)
1. Add the dependency
Section titled “1. Add the dependency”<dependency>
<groupId>io.mateu.workflow</groupId>
<artifactId>workflow-engine</artifactId>
<version>2.42.1</version>
</dependency>
2. Configure embedded mode
Section titled “2. Configure embedded mode”In src/main/resources/application.properties:
workflow.mode=embeddedworkflow.persistence=memory3. Define a workflow
Section titled “3. Define a workflow”Create src/main/resources/workflows/hello-world.ec.yaml:
# yaml-language-server: $schema=https://raw.githubusercontent.com/miguelperezcolom/eventconductor/main/modules/workflow-engine/src/main/resources/workflow-definition-schema.jsonid: hello-worldname: Hello Worldversion: 1steps: - id: start type: START name: Start - id: greet type: ACTION name: Greet the user preconditionStepId: start - id: end type: END name: Done preconditionStepId: greet4. Create the application class
Section titled “4. Create the application class”@WorkflowEmbeddedApplicationpublic class MyApplication { public static void main(String[] args) { SpringApplication.run(MyApplication.class, args); }}5. Implement a worker
Section titled “5. Implement a worker”The engine hands every ACTION step to the EmbeddedTaskExecutor bean; declare it in a
@Configuration class:
@Configurationpublic class WorkerConfig {
@Bean public EmbeddedTaskExecutor greetWorker(UpdateStepExecutionUseCase updateStepExecution) { return request -> { String name = request.variables().stream() .filter(v -> "name".equals(v.name())) .map(Variable::value) .findFirst().orElse("World");
System.out.println("Hello, " + name + "!");
updateStepExecution.handle(new UpdateStepExecutionCommand( request.taskExecutionId(), List.of(new Variable("greeting", "Hello, " + name + "!")), "", StepExecutionStatus.COMPLETED )); }; }}6. Start a process
Section titled “6. Start a process”Something has to start the process — a REST controller, a scheduled job, a message listener. For
this guide, an ApplicationRunner starts one as soon as the application is up (the definitions in
classpath:/workflows/ are loaded by then):
@Componentpublic class HelloWorldStarter implements ApplicationRunner {
private final ProcessUpstreamEventUseCase processUpstreamEventUseCase;
public HelloWorldStarter(ProcessUpstreamEventUseCase processUpstreamEventUseCase) { this.processUpstreamEventUseCase = processUpstreamEventUseCase; }
@Override public void run(ApplicationArguments args) { processUpstreamEventUseCase.handle(new ProcessUpstreamEventCommand( new ProcessCreationRequested( "hello-world", "my-first-process", List.of(new Variable("name", "Alice")) ) )); }}7. Build and run
Section titled “7. Build and run”mvn spring-boot:run needs the Spring Boot Maven plugin: with spring-boot-starter-parent as the
parent, declaring org.springframework.boot:spring-boot-maven-plugin under <build><plugins> is
enough (without the parent, give the plugin a version and import spring-boot-dependencies).
mvn clean installmvn spring-boot:runYou should see Hello, Alice! in the logs, and the process will complete automatically.
Next steps
Section titled “Next steps”- Learn about deployment modes to add PostgreSQL or Kafka
- Explore workflow definitions for retries, timeouts, and branching
- Add user tasks to pause workflows for human input
- Connect Claude Desktop via MCP