Skip to content

Configuration Reference

PropertyValuesDefaultDescription
workflow.modekafka | embeddedembeddedEvent dispatch mode
workflow.test-runs.enabledbooleanfalseEnable manual IDE test runs from embedded definitions at POST /workflow/api/test-runs. Calls real workers; use a test environment. Does not publish definitions or register triggers/schedules. Each run executes under a private definition id (vscode-<id>-<runId>), so it never mixes with a published definition’s instances, analytics or migrations. Normal REST and flow authorization still apply
workflow.test-runs.required-roleslist${workflow.security.operations.required-roles}Roles a caller must hold to start a test run, enforced even when flow authorization is off. With no role configured here or in the fallback, every test run is refused with 403. An engine that authenticates only with X-Api-Key has no caller and therefore no roles, so it refuses every test run: configure an identity provider (for example JWT) whose callers carry the role. Metrics tag every test run with the single workflowDefinitionId value vscode-test-run, so runs never open series of their own
workflow.persistencejpa | memorymemoryWorkflow state persistence mode
workflow.projection.enabledtrue | falsefalseTurn on the process-index read model: emit ProcessStatusChanged from ProcessRepository.save and run the projector that maintains the process_index table. Off = no prior-status read, no event, no projector bean; the write path is unchanged
workflow.projection.modeembedded | remoteembeddedWhere the read model is maintained. embedded: in-process, in the engine’s own database — unchanged. remote: the outbox relay diverts ProcessStatusChanged to the shared process-index topic, the in-process projector is not created, and a standalone projector maintains one fleet-wide index in a read database
workflow.projection.datasource.url / .username / .password / .pool-size— / — / — / 4The read database, in remote mode. Opened read-only: there the projector is the index’s only writer
forms.tasks.admin-rolesrole namestask-adminThe roles that make a caller a task admin: they see, claim and reassign every human task whoever it names (the form’s requiredRoles/requiredScopes still apply). A caller’s groups are their roles — the same workflow.security.claims.roles the engine reads (add an identity provider’s groups claim there). See Human tasks: assignment and escalation
forms.persistencejpa | memorymemoryForms state persistence mode. Read only by the forms engine — workflow.persistence does not cover it, so an app that embeds both engines has to set both. The standalone forms app overrides the default to jpa (FORMS_PERSISTENCE)
workflow.time.zoneIANA zoneJVM zoneThe zone in which a date without one is read — an untilVariable holding 2026-08-01, a moment (until / deadline) that names no zone
workflow.timeout-scan-interval-msms10000How often the scheduler looks for expired step timeouts and due TIMER steps. The lookup is an indexed query on the step’s materialised deadline, so its cost tracks the work that is due — normally none — and not how many steps are waiting; lowering it tightens firing latency without a scan penalty
workflow.retry.backoff-base-msms1000Auto-retry backoff for the first retry. A failed step with retries left is parked in AWAITING_RETRY and re-dispatched only after this delay, so a worker that fails fast is never hammered in a tight loop
workflow.retry.backoff-multiplierdouble2.0Exponential growth factor applied per attempt: the n-th retry waits base × multiplier^(n-1), capped at backoff-max-ms. 1.0 = fixed delay
workflow.retry.backoff-max-msms60000Upper bound on the backoff delay, however many attempts have failed
workflow.retry.backoff-jitterdouble (0–1)0.2Randomises each delay by ±this fraction, so a fleet of steps that failed together (a downstream outage) do not all retry on the same tick. 0.0 disables jitter
workflow.cron-scan-interval-msms10000How often the scheduler checks the schedules (cronExpression, schedules, cron.yaml) of ACTIVE definitions
workflow.schedulers.backgroundbooleantrueWhether the engine’s schedulers (deadline scan, cron starts, retention purges, lock-lease reaper, stalled reports, analytics rollup) run their own background loops. false leaves them to be driven pass by pass — what the workflow test kit does to skip time; not for production
workflow.cron-enabledtrue | falsetrueMaster switch for cron-scheduled process starts
workflow.outbox-poll-interval-msms500How long a relay waits before looking again when nothing woke it. A pod raises a signal after committing an outbox row of its own, so this is the fallback for rows written by other pods — a crashed pod’s undelivered work, mostly — and no longer the latency every step pays. Before the signal it set per-transition latency directly: 500 ms here meant ~500 ms per transition
workflow.outbox.relay-enabledtrue | falsetrueEnables the outbox relay (set to false to disable event relaying entirely)
workflow.consumer.process-parallelismint1How many of a poll batch’s per-process groups a pod may commit at once. 1 (the default, the original behaviour) commits them one after another on the consumer thread, so a pod’s own parallelism is its partition count; above 1 hands the batch’s independent processes to a small pool, letting a pod work more processes than it owns partitions. Only ever parallel across distinct processes — a single process’s events share a partition and stay in one ordered group drained by one thread — so ordering and single-writer are unchanged. Each concurrent process commits in its own transaction, so keep this at or below DB_POOL_SIZE. A modest, situational lever (see Performance): it helps when a pod owns few partitions relative to the work per batch. Pass as a JVM -D; the dashed name does not survive env-var relaxed binding
workflow.process-lock-timeout-secondss10How long to wait for exclusive access to a process before giving up. Exclusivity is a row lock on the process, so this is a statement timeout on the wait, not a spin: the caller queues in the database and is woken in turn
workflow.outbox.batch-sizeint100How many messages a relay claims per batch. In kafka mode the claim holds a row lock on each until the batch is published, so this also bounds how long one pod can keep another from those rows; raising it trades that for fewer round trips
workflow.outbox.relay-concurrencyint0How many partition keys the relay publishes at once. 0 is one per key in the batch — bounded by batch-size, which is the most a pass can claim. 1 sends inline on the relay thread; any other value is a ceiling. Sends are on virtual threads, so a key waiting for its ack costs nothing to have in flight; the number of keys in flight is what lets the Kafka producer build a batched request out of the pass instead of amortising one round trip across a handful of records. Within a key sends stay strictly sequential, so per-process ordering does not depend on this
workflow.outbox.retentionduration (24h, 7d, P7D)— (off)How long a sent outbox row is kept before it is deleted. Unset means nothing is ever deleted, which is the historical behaviour: every transition of every process leaves its events in that table for good — order of 25 rows per process instance, so millions of processes leave hundreds of millions of rows that autovacuum keeps rewriting and every index scan pays for. Pending and Error rows are never touched at any setting: one is undelivered work, the other is a parked message waiting for a human
workflow.outbox.purge-batch-sizeint1000Rows deleted per statement. Bounded so the delete never holds a lock long enough to matter to the relays sharing that database
workflow.outbox.purge-intervalISO-8601 durationPT1MHow often a purge pass runs
workflow.outbox.purge-max-batches-per-passint20Batches one pass may delete. Caps how much a pod that has been down while the table grew can do in one go, so catching up happens over several passes instead of one sweep competing with the engine
workflow.metrics.gauge-ttldurationPT30SHow long the two counting gauges (eventconductor.process.running, eventconductor.outbox.pending) may reuse their last value. Both answer with a count(*) against the engine’s own database, and counting running processes walks one index entry per running process — the very number being reported — so without this the cost of observing the system grows with the system, once per pod per scrape. PT0S restores a query on every scrape
workflow.message-api.api-keystring—API key required in the X-Api-Key header of the engine’s REST API (/workflow/api/**: processes, messages, events, triggers, schedules, sync invocations). See HTTP security for what happens when it is blank
workflow.message-api.allow-anonymousbooleanfalseAccept requests without credentials when no api-key is set and no Spring Security filter chain protects the application — for the REST API (since 2.27.0), for the admin UI, MCP and rule-read endpoints (since 2.28.0; see HTTP security), and for unsigned git-import webhooks with no webhook-secret (since 2.28.0). Turn it on only for an isolated or development deployment
workflow.rest.max-body-bytesbytes16777216 (16 MiB)Request bodies larger than this are cut off unread on /workflow/api/* and the git webhooks (/workflow/webhooks/*, /forms/webhooks/*, /rules/webhooks/* — also in the standalone forms and rules apps). Far above the engine’s own input limits on purpose: those answer with a message naming the field; this only stops a body too large to read
workflow.security.flow-authorization.enabledbooleanfalseEnforce definitions’ requiredScopes / requiredRoles against the caller (fail closed: a caller nobody identified holds nothing). Also checked when someone creates or edits a schedule or event trigger, or runs a schedule now, and — on the processes REST API — when a caller reads or commands one of the definition’s processes
workflow.security.operations.required-rolescsv—Roles a caller must all hold for the manual operations (set variables, complete a step, retry from a step, retry an incident) at every door, whether or not flow authorization is on. Empty: they are gated like the other commands
workflow.incidents.scan-limitint10000Incidents: how many failed steps the grouping reads (most recent first). A group retry is a batch operation — paced by workflow.batch-operations.* (workflow.incidents.retry.max-steps and .sync-limit are no longer read)
workflow.incidents.gauge-interval-msms60000How often the processes stopped on an incident are counted for the eventconductor.incidents.open gauge (one grouped count per pass); 0 turns it off
workflow.api.openapi.enabledbooleanfalseWith springdoc on the classpath, serve the OpenAPI description of /workflow/api/** as the eventconductor group (/v3/api-docs/eventconductor). See Processes REST API — OpenAPI
workflow.security.trust-forwarded-tokenbooleanfalseRead the caller’s identity from a bearer token this application did not verify. Only behind something that did (a gateway, a mesh) — on its own it believes whatever the caller typed. The application’s own Spring Security authentication is always preferred. It also decides who is signed in on the forms task pages (claim, release, complete)
workflow.security.claims.subject / .scopes / .rolescsvpreferred_username,sub / scope,scp / realm_access.roles,rolesThe token claims a forwarded token’s caller id, scopes and roles are read from (first match wins; dotted names reach into nested objects)
workflow.stalled-step-after-ms / workflow.stalled-step-scan-interval-msms900000 / 60000How long a live ACTION/RULE step with no deadline may wait before eventconductor.steps.stalled counts it, and how often that is checked
workflow.stalled-process-after-ms / workflow.stalled-process-scan-interval-msms1800000 / 300000How long a RUNNING process with no step left to run may sit before it is logged (WARN, with up to 20 ids) and counted by eventconductor.processes.stalled, and how often that is checked
workflow.analytics.rollupbooleanfalsejpa persistence: keep the analytics read model (daily rollup tables) current in the background instead of computing reports from the raw tables. Each finished process and step is counted once, even across retries and restarts
workflow.analytics.rollup-interval-msms15000How often the rollup folds new facts
workflow.analytics.rollup-batch-sizeint1000Rows read per batch
workflow.analytics.rollup-max-batches-per-cycleint200Batches per stream per cycle — bounds a first-run backfill, which then catches up over several cycles
workflow.analytics.rollup-ceiling-secondss2Rows newer than this are left for the next cycle, so a commit in flight at the boundary is not missed
workflow.analytics.rollup-lookback-secondss120How far behind its cursor each cycle looks again for finishes never counted — committed after the cursor passed them (a long transaction, a pod whose clock is behind). Folded once: the counted-facts ledger keeps out what is already in. Must outlast the longest transaction that finishes a process plus a cycle; 0 turns it off
workflow.embedded.worker-threadsint0Embedded mode only. 0 runs the worker on the thread that dispatched the task — which under jpa persistence is the single outbox relay thread, the one advancing every process in the JVM, so a worker that blocks stops all of them. Above zero the task is handed to a pool of that many threads and the dispatching thread is freed. See the note below before turning it on
workflow.embedded.worker-queue-capacityint1000How many tasks may wait for a worker thread. A full queue rejects, and the rejection is retryable: the outbox holds the message and offers it again
workflow.embedded.worker-shutdown-grace-msms10000How long shutdown waits for in-flight workers before abandoning them
workflow.dynamic.max-steps-per-processint500Runaway guard for dynamic workflows: the most step executions any one process may ever hold, runtime injections included. An injection that would push a process past this cap is rejected and its DYNAMIC step fails. A definition’s own maxSteps overrides this when it declares one (> 0); this is the fallback for every definition that does not
workflow.foreach.max-itemsint1000Runaway guard for forEach: the longest list one forEach step may run over. A longer one fails the step when it starts
workflow.loops.max-iterationsint1000Runaway guard for repeat and loopBack: the most runs any loop may make, whatever its maxIterations says. Going past it fails the step
rules.persistencejpa | memorymemoryRule catalog persistence mode
rules.sourcelocal | classpath | rest | grpclocalWhere the rule runtime reads rules from
rules.catalog.urlURL—Catalog base URL for rules.source=rest
rules.catalog.grpc-targethost:port—Catalog gRPC target for rules.source=grpc
rules.cache.ttlISO-8601 durationPT5MRemote rule cache TTL (PT0S = never expires)
rules.kafka-refreshtrue | falsefalseRefresh the rule cache from RulePublished/RuleDeleted events
rules.grpc.enabledtrue | falsefalseStart the catalog’s gRPC read API. Plaintext and unauthenticated: anyone reaching the port reads every rule — enable it only behind mTLS (service mesh) and a network policy
rules.grpc.portport9090Catalog gRPC port

By default the engine calls your EmbeddedTaskExecutor on the thread that dispatched the task and waits for it to return. With workflow.persistence=jpa that thread is embedded-outbox-relay, the single thread that drains the outbox and therefore the only one advancing every process in the JVM. A worker that blocks there — an HTTP call to a service that accepts the connection and never answers — stops the engine: no step-over runs, and processes created afterwards sit with every step in CREATED, which reads as “waiting for its preconditions” and looks nothing like the problem it is.

workflow.embedded.worker-threads > 0 hands the task to a pool instead. Three things change:

  • Delivery stops meaning completion. Inline, the outbox row is marked Sent only once the worker returned, so a crash mid-task redelivers it. Through a pool, Sent means handed off — what it already means in kafka mode. A task lost to a crash after the handoff is recovered by the step’s own timeout, so give ACTION steps one (or set workflow.default-step-timeout-ms) before enabling this.
  • Redelivery stops retrying the worker. Inline, a retryable failure propagates and the relay re-dispatches next cycle. Off-thread the step is failed instead, and the ordinary retry and compensation pipeline takes over.
  • Tasks of one process can overlap. Reporting is still serialised by the process lock, but a worker can no longer assume it is called one at a time.

Either way, an exception that escapes a worker now fails its step. Reporting ERROR through UpdateStepExecutionUseCase is still the contract — a throw carries no variables and no message of your choosing — but a step whose worker threw is no longer left waiting for a reply that is never coming.

Clones Git repositories at startup and imports workflow definition files (*.ec.yaml recommended; also .ec, .json, .yaml, .yml). .ec is EventConductor’s own extension — its content may be JSON or YAML (detected automatically). Works with either workflow.persistence: with memory the definitions are held in the heap and imported again at every start; with jpa they are stored (with version history), and what each source imported is remembered across restarts so a definition removed from the repository is archived.

PropertyDefaultDescription
workflow.git-import.repositories[].url—Git clone URL (HTTPS or SSH)
workflow.git-import.repositories[].branchmainBranch to check out
workflow.git-import.repositories[].directory—Subdirectory to scan for definitions (relative to the repo root). Leave blank to scan the whole repository.
workflow.git-import.repositories[].username—Username for HTTPS authentication
workflow.git-import.repositories[].password—Password or personal access token
workflow.git-import.webhook-secret—HMAC-SHA256 secret for verifying GitHub webhook payloads (X-Hub-Signature-256). Without it (since 2.28.0) an unsigned webhook is refused with 401 while repositories are configured, unless Spring Security protects the application or workflow.message-api.allow-anonymous=true.

The webhook endpoint is POST /workflow/webhooks/{provider} (github/gitlab/bitbucket/generic); it reloads only the pushed repository/branch and archives definitions removed from the repo. See Workflow Definitions — Importing from Git for setup instructions.

Git import — Forms engine (forms.git-import.*)

Section titled “Git import — Forms engine (forms.git-import.*)”

Clones Git repositories at startup and imports form definition files (.json, .yaml, .yml). Provided by the forms-engine module.

PropertyDefaultDescription
forms.git-import.repositories[].url—Git clone URL (HTTPS or SSH)
forms.git-import.repositories[].branchmainBranch to check out
forms.git-import.repositories[].username—Username for HTTPS authentication
forms.git-import.repositories[].password—Password or personal access token
forms.git-import.webhook-secret—HMAC-SHA256 secret for verifying GitHub webhook payloads (X-Hub-Signature-256). Without it (since 2.28.0) an unsigned webhook is refused with 401 while repositories are configured, unless Spring Security protects the application or workflow.message-api.allow-anonymous=true.

The webhook endpoint is POST /forms/webhooks/{provider} (github/gitlab/bitbucket/generic); it reloads only the pushed repository/branch and deletes forms removed from the repo. See Form Definitions — Importing from Git for setup instructions.

Git import — Rule engine (rules.git-import.*)

Section titled “Git import — Rule engine (rules.git-import.*)”

Clones Git repositories at startup and imports rule definition files (.json, .yaml, .yml). Provided by the rule-engine module.

PropertyDefaultDescription
rules.git-import.repositories[].url—Git clone URL (HTTPS or SSH)
rules.git-import.repositories[].branchmainBranch to check out
rules.git-import.repositories[].username—Username for HTTPS authentication
rules.git-import.repositories[].password—Password or personal access token
rules.git-import.webhook-secret—HMAC-SHA256 secret for verifying GitHub webhook payloads (X-Hub-Signature-256). Without it (since 2.28.0) an unsigned webhook is refused with 401 while repositories are configured, unless Spring Security protects the application or workflow.message-api.allow-anonymous=true.

The webhook endpoint is POST /rules/webhooks/{provider} (github/gitlab/bitbucket/generic); it reloads only the pushed repository/branch and deletes rules removed from the repo. See Rule Definitions — Git import for setup instructions.

Imports task contracts (.ectask, and .json/.yaml/.yml) from the classpath, local directories and Git — alongside workflows, forms and rules, and ahead of them, so a workflow step’s task: <id> resolves to the latest contract version as the definition loads. Contracts are versioned and append-only: nothing is pruned, because a version an in-flight process is pinned to must stay resolvable.

PropertyDefaultDescription
tasks.directory-import.directories[]—Local directories to scan for .ectask contracts.
tasks.git-import.repositories[].url—Git clone URL (HTTPS or SSH).
tasks.git-import.repositories[].branchmainBranch to check out.
tasks.git-import.repositories[].directory—Subdirectory to scan (relative to the repo root). Leave blank to scan the whole clone.
tasks.git-import.repositories[].username—Username for HTTPS authentication.
tasks.git-import.repositories[].password—Password or personal access token.
tasks.git-import.webhook-secret—Secret for verifying push webhooks (GitHub/Bitbucket HMAC, GitLab/generic token). Used only when workflow.git-import.webhook-secret is blank. With both blank, an unsigned webhook is refused (401) unless Spring Security protects the application or workflow.message-api.allow-anonymous=true.

Task git import runs at startup and on a push webhook: the workflow engine’s POST /workflow/webhooks/{provider} (github/gitlab/bitbucket/generic) reloads the pushed repository/branch from the tasks.git-import repositories as well as the workflow.git-import ones — contracts first, then workflows, so a step’s task: reference resolves. Nothing is pruned (contracts are append-only). Contracts also load from classpath:/tasks/ (memory mode serves them from the heap; jpa mode imports them into the database at startup).

When embedding the workflow engine, use @WorkflowEmbeddedApplication instead of @SpringBootApplication. It sets up the correct component scan — including the UI exclusion filter — automatically.

workflow.persistence=memory (default):

@WorkflowEmbeddedApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}

workflow.persistence=jpa:

@WorkflowEmbeddedApplication
@EnableJpaRepositories(basePackages = "io.mateu.workflow.infra.out.persistence")
@AutoConfigurationPackage(basePackages = "io.mateu.workflow.infra.out.persistence")
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}

@WorkflowEmbeddedApplication is provided by the workflow-engine module. It combines @SpringBootConfiguration, @EnableAutoConfiguration, and a @ComponentScan scoped to io.mateu.workflow with the UI adapter layer excluded.

When embedding the forms engine, use @FormsEmbeddedApplication instead of @SpringBootApplication.

forms.persistence=memory (default):

@FormsEmbeddedApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}

forms.persistence=jpa:

@FormsEmbeddedApplication
@EnableJpaRepositories(basePackages = "io.mateu.workflow.infra.out.persistence")
@AutoConfigurationPackage(basePackages = "io.mateu.workflow.infra.out.persistence")
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}

@FormsEmbeddedApplication is provided by the forms-engine module and follows the same pattern as @WorkflowEmbeddedApplication.

Forms engine next to an embedded workflow engine. Add forms-engine to a @WorkflowEmbeddedApplication and the two talk in process — no broker: the forms engine takes every USER_TASK that names a formId (plus its escalations and cancellations) before the application’s EmbeddedTaskExecutor, puts it in the task inbox, and a submitted form completes the step on the engine directly. Task events (HumanTaskChanged) are published as Spring application events (@EventListener void on(HumanTaskChanged changed)) instead of on the humanTasks binding. Forms are loaded with forms.directory-import.directories[] or forms.git-import.*, not from the classpath.

PropertyDefaultDescription
forms.embedded.serve-user-taskstruefalse leaves USER_TASKs to the application’s EmbeddedTaskExecutor, as without forms-engine. The workflow-test kit (@EventConductorTest) sets it, so completeUserTask keeps answering them.

For workflow.mode=kafka, use @SpringBootApplication as normal — both engines integrate as regular Spring Boot auto-configurations.

The engine’s schema — its Flyway migrations — is written for PostgreSQL, the database it is built and tested against in production, and H2 (PostgreSQL mode), which the embedded path and the test suites use. MariaDB/MySQL and Oracle are supported at the JPA and locking level only: the lock dialect is auto-detected from the JDBC connection at startup (no extra property), the queries are portable, but several migrations do not run there (V7, V10, V22, V23, V24 and V36 fail on MariaDB; Oracle has neither IF NOT EXISTS nor TEXT). On those databases the schema comes from ddl-auto and the indexes are yours to create — see below.

PostgreSQL (default in examples):

spring.datasource.url=jdbc:postgresql://localhost:5432/workflow
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=update

MariaDB / MySQL:

spring.datasource.url=jdbc:mariadb://localhost:3306/workflow
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.database-platform=org.hibernate.dialect.MariaDBDialect
spring.jpa.hibernate.ddl-auto=update

Oracle:

spring.datasource.url=jdbc:oracle:thin:@localhost:1521:XE
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.database-platform=org.hibernate.dialect.OracleDialect
spring.jpa.hibernate.ddl-auto=update

Each engine ships its own migrations and applies them itself at startup, whenever it has a data source — embedded exactly as in the standalone apps. In production also set DDL_AUTO=validate, so the migrations own the schema and Hibernate only checks it.

Do not turn this off. The migrations are the only place the engine’s indexes come from: ddl-auto=update emits no index DDL at all, so a schema built without them has primary keys and nothing else, and every deadline scan, outbox claim and message correlation becomes a sequential scan. Measured on a cluster where they were missing, PostgreSQL pinned at 750m of CPU and throughput fell to a fraction.

workflow.schema.enabled=true # forms.schema.*, rules.schema.* for the other two
workflow.schema.table=eventconductor_schema_history
PropertyDefaultWhat it does
workflow.schema.enabledtrueApply the engine’s migrations at startup. Off means something else owns its tables.
workflow.schema.tableeventconductor_schema_historyWhere the engine records its own migration history.
forms.schema.*eventconductor_schema_history_formsSame, for the forms engine.
rules.schema.*eventconductor_schema_history_rulesSame, for the rules engine.

Two things follow from the engine owning its schema:

  • It never writes to flyway_schema_history. That table is yours. Your application’s migrations are numbered from V1 and so are the engine’s; a shared history would collide them and the second one to run would fail validation on a checksum mismatch. spring.flyway.* keeps meaning exactly what it meant before — your migrations, your history — and the engine stays out of it.
  • It adopts an existing schema. The migrations baseline at 0 and every V1 is written IF NOT EXISTS, so turning this on over tables ddl-auto already created applies the indexes and nothing else.

The engines’ Flyway migrations target PostgreSQL and H2 only (the engine ships flyway-database-postgresql only), and some of them fail outright elsewhere. On MariaDB/MySQL or Oracle:

  1. Set workflow.schema.enabled=false (and forms.schema.enabled=false, rules.schema.enabled=false for those engines).
  2. Let spring.jpa.hibernate.ddl-auto=update create the tables. It also creates the indexes the entities declare (the deadline, outbox, correlation, lock and event-trigger lookups).
  3. Create the indexes that exist only in the migrations yourself — ddl-auto cannot produce them. Without them the process listing, the definition pages and analytics fall back to table scans:
IndexTable (columns)Serves
idx_process_statusprocess_entity (status)listing by status
idx_process_wf_defprocess_entity (workflow_definition_id)processes of a definition
idx_process_wf_def_versionprocess_entity (workflow_definition_id, workflow_definition_version)counts per version
idx_process_createdprocess_entity (created DESC)the process listing’s order
idx_process_status_createdprocess_entity (status, created DESC)the listing filtered by status
idx_step_exec_started_atstep_execution_entity (started_at DESC)the step listing’s order
idx_step_exec_analyticsstep_execution_entity (workflow_definition_id, step_id, status, _order)step analytics
idx_cron_schedule_workflowcron_schedule (workflow_id)schedules of a definition
idx_cron_schedule_schedule_idcron_schedule (schedule_id)a schedule by id
idx_process_created_daily_day, idx_process_finished_daily_created, idx_process_status_daily_created, idx_process_duration_daily_created, idx_step_status_daily_created, idx_step_duration_daily_createdthe analytics rollups (created_day)the analytics report’s window (only with workflow.analytics.rollup=true)
idx_process_index_status, idx_process_index_def_status, idx_process_index_business_keyprocess_indexthe process-index read model (only when it is on)

The exact statements are in db/migration/workflow in the workflow-engine jar; drop NULLS LAST and IF NOT EXISTS where your database does not take them.

Embedding the engine needs org.flywaydb:flyway-core on the classpath (plus the driver module, e.g. flyway-database-postgresql) — it is an optional dependency, since a run with workflow.persistence=memory needs neither. With persistence=jpa and no Flyway the engine warns loudly at startup rather than running indexless in silence.

The standalone apps keep their historical history-table names (flyway_schema_history, …_forms, …_rules) via FLYWAY_TABLE, so an existing deployment upgrades in place.

How the engine keeps two pods off the same process depends on the mode:

  • workflow.mode=kafka — no per-process lock. Events are keyed by process, so a consumer group hands each process’s partition to exactly one orchestrator: a process has a single writer by construction. An optimistic-locking version on the process_entity and step_execution_entity aggregates fences the brief window a Kafka rebalance leaves uncovered (the outgoing pod finishing a record the incoming one now owns) and worker replies that arrive unkeyed — a stale write is rejected instead of overwriting the new owner’s work.
  • workflow.mode=embedded + workflow.persistence=jpa — a row lock. The action runs in a transaction that opens with SELECT … FOR UPDATE on the process row and releases on commit; waiting is bounded by workflow.process-lock-timeout-seconds (default 10). Embedded pods share no partitioning, so this is what keeps two of them off the same process. No separate connection and no watchdog are involved.
  • workflow.mode=embedded + workflow.persistence=memory — an in-JVM lock (single process only).

Separately, the singleton background jobs — the timeout/timer scan, cron-scheduled starts, the embedded outbox relay, and the serialization-lock lease reaper (below) — take a short-lived database advisory lock so only one pod runs each. The lock dialect is auto-detected from the JDBC connection:

DatabaseLock mechanism
PostgreSQLpg_try_advisory_lock(bigint) / pg_advisory_unlock(bigint)
MariaDB / MySQLGET_LOCK(name, 0) / RELEASE_LOCK(name)
OracleDBMS_LOCK.REQUEST / DBMS_LOCK.RELEASE (via PL/SQL)

These locks are held only for the length of one scan and are session-scoped, so a crashed pod’s locks are released automatically by the database when its JDBC connection closes — no watchdog needed.

A definition can serialize processes by a key — LOCK/UNLOCK steps around a critical section, or a process-level processLock. The held lock is a row keyed by (name, key); whoever cannot take it waits its turn (FIFO). A lease bounds how long a hold survives if the process that took it dies without releasing — the crash backstop — and a reaper frees expired holds and admits the next waiter.

PropertyDefaultDescription
workflow.lock.lease-ms900000How long a hold lasts (ms) before the reaper may evict it. Generous by design — long enough that a merely-slow holder is never evicted.
workflow.lock.lease-scan-interval-ms60000How often (ms) the lease reaper scans for expired holds (jpa mode; one pod at a time via an advisory lock).
workflow.lock.wait-timeout-seconds10How long an acquire/release waits for the per-key row lock before giving up (jpa mode).

Only relevant to definitions that declare locks; one that uses none pays nothing. See Step types — LOCK / UNLOCK.

Sensitive variables (workflow.encryption.*)

Section titled “Sensitive variables (workflow.encryption.*)”

Keys for the variables a definition declares in sensitiveVariables; see Sensitive data and encryption. Read by the engine, the forms engine and any worker that must open sealed values — give them all the same keys.

PropertyTypeDefaultDescription
workflow.encryption.keys.<id>base64 string— (off)An AES-256 key: the base64 of 32 bytes (openssl rand -base64 32). Several for rotation — every configured key opens what it sealed. Without any, a definition declaring sensitiveVariables is refused, and an engine whose store holds one does not start
workflow.encryption.active-keystringthe only keyThe key new values are sealed with; required when several are configured
workflow.security.sensitive.reveal-roleslist— (nobody)Roles that may reveal a sensitive variable’s value (REST, MCP, console); every reveal is audited in the process log
eventconductor.worker.encryption.enabledbooleantrueIn a worker with keys: open sealed inputs before binding, re-seal the outputs named like them
eventconductor.worker.encryption.sensitive-variableslist—In a worker: output names (or globs) to seal even when no input of that name came sealed

A VariableCodec bean replaces AES-GCM (a KMS or Vault transit call per value); an EncryptionKeySource bean supplies the keys from elsewhere (Vault, unwrapped KMS data keys).

workflow.processes.*: how long finished processes are kept when their definition does not say, and how the purge job runs. A definition’s own retention wins over these; see Process retention for what is purged and what never is.

PropertyDefaultDescription
workflow.processes.retention— (off)How long a finished process is kept, counted from its end, for every terminal status (30d, P30D). Unset keeps them forever — the historical behaviour: nothing is deleted that a definition did not ask to delete.
workflow.processes.retention-by-status.<status>—Per terminal status, over the above: completed, cancelled, error, compensated, compensation-failed (any case or separator).
workflow.processes.purge.enabledtrueRun the purge job at all. false stops every deletion, whatever the retentions say.
workflow.processes.purge.intervalPT10MHow often it looks for processes past their retention. One pod at a time (jpa: an advisory lock).
workflow.processes.purge.batch-size100Process trees read per query. Each tree is deleted in its own transaction.
workflow.processes.purge.max-per-pass10000Processes one pass may delete — a backlog (retention just switched on over years of history) is worked off over several passes.

Batch operations (workflow.batch-operations.*)

Section titled “Batch operations (workflow.batch-operations.*)”

The runner that walks batch operations. One node at a time works batches (jpa: an advisory lock); every node can create and cancel them.

PropertyDefaultDescription
workflow.batch-operations.enabledtrueRun the runner on this node. Off: batches are still created and cancelled, and wait as CREATED. With workflow.schedulers.background=false its loop does not start either, and the test kit drives it (it is a scheduler pass).
workflow.batch-operations.poll-intervalPT1SPause between two pages — and how soon a new batch is picked up.
workflow.batch-operations.page-size100Processes read and acted on per page; the cursor and counters are saved after each page, so a restart repeats at most one page.
workflow.batch-operations.max-per-second50Throttle: processes acted on per second. 0 or less: as fast as the commands go.
workflow.batch-operations.list-limit200How many batches the console, REST and MCP list, newest first.

Search attributes need no configuration: they are declared per definition (searchAttributes) and stored by the migrations (V48 process_search_attribute, V49 batch_operation).

Only relevant to definitions that declare syncInvocation; see Synchronous Invocation.

PropertyDefaultDescription
workflow.sync.default-deadline-ms5000How long a caller waits when neither it (Prefer: wait=N) nor the definition says.
workflow.sync.max-deadline-ms30000The longest any caller may wait.
workflow.sync.max-waiting200Callers and progress streams waiting per node; past it, 429.
workflow.sync.poll-interval-ms250How often a node polls for replies recorded elsewhere — the fallback when NOTIFY is unavailable.
workflow.sync.retentionPT24HHow long an invocation (and so its idempotency key) is remembered.
workflow.sync.purge-intervalPT10MHow often expired invocations are forgotten.
workflow.sync.max-reply-bytes262144Largest reply a REPLY step may record; larger fails the step.
workflow.sync.stream-interval-ms200How often a progress stream (SSE) looks at its process.
workflow.sync.inline.enabledtrueThe fast path: drive a synchronously invoked process on the node that received it (jpa).
workflow.sync.inline.threads8Processes driven inline at once per node; beyond, the normal path. Keep well under the pool size.
workflow.sync.inline.max-steps64Outbox messages per inline drive before the rest goes to the relay.
workflow.sync.inline.claim-lease-ms30000How long an inline claim survives a dead node before the sweeper hands it back.
workflow.sync.inline.sweep-interval-ms5000How often lapsed inline claims are handed back.
workflow.sync.notify.enabledtruePostgreSQL LISTEN/NOTIFY wake-up across nodes (needs a direct connection, not PgBouncer in transaction mode).

Workers over HTTP (workflow.workers.http.*)

Section titled “Workers over HTTP (workflow.workers.http.*)”

Serve the tasks of some topics to workers in any language that long-poll /workflow/api/workers. See Workers over HTTP and the HTTP worker API.

PropertyDefaultDescription
workflow.workers.http.enabledfalseTurns the transport (queue, endpoints, routing) on.
workflow.workers.http.topics[]Step topics served over HTTP (downstream for steps that name none). * = every topic except the built-in tasks’ (USER_TASK, RULE, HTTP_CALL, LLM_CALL, PUBLISH_EVENT), which naming their topic still routes. Other topics keep going to the embedded or Kafka workers.
workflow.workers.http.api-keys.<name>—Worker credentials sent as X-Api-Key; they open the worker API only. The engine’s workflow.message-api.api-key (or Spring Security, or allow-anonymous) is accepted too.
workflow.workers.http.max-waitPT30SThe longest an activation may long-poll.
workflow.workers.http.default-leasePT60SThe lease of an activation (or heartbeat) that asks for none.
workflow.workers.http.max-leasePT30MThe longest lease or heartbeat extension.
workflow.workers.http.max-tasks100The most tasks one activation gets.
workflow.workers.http.max-waiting200Activations waiting per node; past it, 429.
workflow.workers.http.poll-intervalPT1SHow often waiting activations look at the queue when nothing woke them (tasks queued on another node, expired leases). A task queued on the same node wakes them at once.
workflow.workers.http.maintenance-intervalPT30SHow often cancelled and orphaned tasks are purged, the queue gauges refreshed and waiting workers woken for expired leases (a scheduler pass: with workflow.schedulers.background=false only the test kit runs it).
workflow.workers.http.orphan-retentionP7DA queued task older than this, in engine (business) time, is purged (its step moved on without a cancellation). Leases are wall-clock time: skipping time in a test does not expire them.

With workflow.persistence=jpa the queue is the http_task table (migration V50), shared by every node; in memory mode it is in the heap.

Flow control and worker rate limits (workflow.flow-control.*, workflow.workers.rate-limits.*)

Section titled “Flow control and worker rate limits (workflow.flow-control.*, workflow.workers.rate-limits.*)”

See Flow control.

PropertyDefaultDescription
workflow.flow-control.release-intervalPT1SHow often due debounces and queued (throttled) starts are released (a scheduler pass).
workflow.flow-control.creation-gracePT5MHow long a singleton counts a start whose process is not visible yet (created asynchronously) as running.
workflow.workers.rate-limits.<topic>.permits—Tasks of the topic dispatched per period (Kafka, HTTP queue and embedded alike); over it they wait PENDING.
workflow.workers.rate-limits.<topic>.periodPT1SThe fixed window the permits are counted in.
workflow.workers.rate-limit-intervalPT0.2SHow often waiting tasks are dispatched as permits free up (priority first, then one per process in turn).

With workflow.persistence=jpa the state is in flow_control_key, flow_control_pending, rate_limit_window and deferred_dispatch (migration V56), shared by every pod.

PropertyDefaultDescription
workflow.events.destinations.<name>.topic—The topic a PUBLISH_EVENT destination is published to (kafka mode).
workflow.events.destinations.<name>.formatbinarybinary / structured CloudEvents, or plain; a step may override.
workflow.events.max-payload-bytes262144Largest event payload; larger fails the step.
workflow.events.loopbacktrueEmbedded mode: a PUBLISH_EVENT of this engine is also received by its own event triggers and onEvent waits.
workflow.events.worker.enabledtrueIn whatever runs worker-events (the orchestrator, worker-embedded): register the built-in publish-event@1 task that sends a PUBLISH_EVENT’s event — to the destination’s topic in kafka mode (from the destinations above), to the ExternalEventPublisher and the loopback in embedded mode.
workflow.events.worker.topicevent-publicationsThe Kafka topic the built-in worker serves — where the engine dispatches the tasks of PUBLISH_EVENT steps that name no topic.
workflow.events.consumer.enabledtrueKafka mode, with inbound-events-kafka on the classpath: consume the topics of the destinations event triggers and onEvent waits name.
workflow.events.consumer.groupeventconductor-inbound-eventsTheir consumer group — one per deployment, so each event is used by one pod.
workflow.events.consumer.bootstrap-servers—Brokers; empty means spring.cloud.stream.kafka.binder.brokers, else spring.kafka.bootstrap-servers.
workflow.events.consumer.auto-offset-resetlatestWhere a new group starts; latest does not replay a topic’s history when a trigger is turned on.
workflow.events.consumer.refresh-intervalPT30SHow often the set of topics is recomputed from the definitions.
workflow.events.consumer.retry-backoffPT5SBack-off before retrying an event whose starts or messages could not be handed over.
workflow.events.consumer.concurrency1Consumer threads.
workflow.events.consumer.properties.<key>—Kafka client properties for this consumer only (e.g. sasl.jaas.config). Override spring.kafka.* and the binder’s configuration, never the brokers, group, offset reset, manual commits or deserializers above. See Kafka client security.
workflow.events.receipts.retentionP7DHow long an event’s receipts — the protection against a redelivery — are kept.
workflow.events.receipts.purge-intervalPT10MHow often old receipts are purged.

The workflow.events.consumer.* properties take effect only with the io.mateu.workflow:inbound-events-kafka module on the classpath — it holds the Kafka consumer of domain events. orchestrator-standalone-app includes it; an application embedding the engine in kafka mode adds it to receive domain events over Kafka.

See Starting on and waiting for domain events.

Read by the webhook-gateway module (webhook-gateway-standalone-app, or any application embedding it). See Webhooks.

PropertyDefaultDescription
workflow.webhooks.enabledtruefalse leaves the endpoints unmapped.
workflow.webhooks.path/webhooksThe path the endpoints hang from: POST <path>/<endpoint>.
workflow.webhooks.max-body-bytes26214400 (25 MB)The largest webhook body accepted; a larger one is refused with 413 before it is read whole (declared length or chunked).
workflow.webhooks.transportkafkakafka: binary CloudEvents on the destination’s topic (workflow.events.destinations.<name>.topic); rest: the engine’s POST /workflow/api/events/{destination}.
workflow.webhooks.engine.url—The engine’s base URL, for the rest transport (e.g. http://orchestrator:8080).
workflow.webhooks.engine.api-key—Its X-Api-Key, when the message API requires one.
workflow.webhooks.engine.timeoutPT10SHow long a hand-over to the engine may take.
workflow.webhooks.kafka.bootstrap-servers—Brokers, for the kafka transport; empty means spring.cloud.stream.kafka.binder.brokers, else spring.kafka.bootstrap-servers.
workflow.webhooks.kafka.send-timeoutPT10SHow long a send may take before the webhook is answered with an error.
workflow.webhooks.kafka.properties.<key>—Kafka client properties for the gateway’s producer only (e.g. sasl.jaas.config). Override spring.kafka.* and the binder’s configuration, never the brokers, byte-array serializers, acks=all or idempotence. See Kafka client security.
workflow.webhooks.endpoints.<name>.providergenericgithub or generic. <name> is the last path segment of the endpoint’s URL.
workflow.webhooks.endpoints.<name>.destination—The logical destination the event is published on (never a topic).
workflow.webhooks.endpoints.<name>.secret—The shared secret the sender signs with. Required for GitHub; optional for a generic sender.
workflow.webhooks.endpoints.<name>.sourcethe endpoint’s nameThe CloudEvents source.
workflow.webhooks.endpoints.<name>.type-prefixcom.github.GitHub: the type prefix (com.github.push, com.github.pull_request.opened).
workflow.webhooks.endpoints.<name>.signature-headerX-Signature-256Generic: the header carrying the signature (hex HMAC-SHA256 of the body, sha256= prefix tolerated).
workflow.webhooks.endpoints.<name>.type-headerCE-TypeGeneric: the header carrying the CloudEvents type; absent or empty, type.
workflow.webhooks.endpoints.<name>.type—Generic: the type when no header carries one.
workflow.webhooks.endpoints.<name>.id-headerCE-IdGeneric: the header carrying the event id; absent, a random UUID (every delivery is a new event).
workflow.webhooks.endpoints.<name>.subject-headerCE-SubjectGeneric: the header carrying the subject (also the record key); optional.

The gateway reads the destinations’ topics from the same workflow.events.destinations.<name>.topic keys as the engine, so one set of environment variables names the topics for every component.

HTTP calls (workflow.http.*, in whatever runs worker-http)

Section titled “HTTP calls (workflow.http.*, in whatever runs worker-http)”

In kafka mode that is the orchestrator itself (orchestrator-standalone-app runs the built-in workers), or the optional http-worker-standalone-app; in embedded mode, the application with worker-http (or builtin-workers).

PropertyDefaultDescription
workflow.http.enabledtrueRegister the built-in http-call@1 task.
workflow.http.topichttp-callsThe Kafka topic the task is served on.
workflow.http.connections.<name>.base-url—Base URL of a named connection.
workflow.http.connections.<name>.auth—Default auth profile for the connection.
workflow.http.connections.<name>.connect-timeout / read-timeoutPT5S / PT30STimeouts for the connection.
workflow.http.connections.<name>.headers.*—Headers added to every call on the connection.
workflow.http.connections.<name>.idempotency-headerIdempotency-KeyHeader carrying the step execution id; none to omit.
workflow.http.auth.<name>.typenonenone, basic, bearer, api-key, oauth2-client-credentials.
workflow.http.auth.<name>.*—username/password, token, header/value/in, token-uri/client-id/client-secret/scope.
workflow.http.auth.<name>.hosts(none)Hosts the profile’s credentials may be sent to (api.x.com, *.partner.com). Without it, the profile is used through a connection, or on an absolute URL only when allowed-hosts is set; with it, every target (connections too) must match. A refusal fails the step with HTTP_FORBIDDEN_AUTH.
workflow.http.credentials-to-any-hostfalseSince 2.28.0, credentials (named profiles, inline ${secret:…} blocks) are not sent to an absolute URL outside a profile’s hosts / allowed-hosts. true restores the earlier behaviour, in which a definition author could send them to any public host.
workflow.http.secrets.<NAME>—What ${secret:NAME} resolves to (else, with secrets-from-environment, the NAME property / env var).
workflow.http.secrets-from-environmentfalseWhether a ${secret:NAME} not listed under workflow.http.secrets falls back to any environment variable or Spring property named NAME. Off since 2.27.0, so a definition author cannot reach other values of the process (database passwords, cloud credentials); true restores the fallback. While true and allowed-hosts is empty, a WARN at startup says so.
workflow.http.allowed-hosts(any public host)Hosts absolute URLs — and the token-uri of an inline OAuth2 block — may target (api.x.com, *.partner.com). Internal addresses are always refused for them; a host that does not resolve is refused too (a retryable HTTP_IO).
workflow.http.connect-timeout / read-timeoutPT5S / PT30STimeouts for absolute URLs.
workflow.http.max-response-bytes1048576Largest response read; larger fails the step.

LLM calls (workflow.llm.*, in whatever runs worker-llm)

Section titled “LLM calls (workflow.llm.*, in whatever runs worker-llm)”

In kafka mode that is the orchestrator itself, or the optional llm-worker-standalone-app; in embedded mode, the application with worker-llm (or builtin-workers).

PropertyDefaultDescription
workflow.llm.enabledtrueRegister the built-in llm-call@1 task.
workflow.llm.topicllm-callsThe Kafka topic the task is served on.
workflow.llm.connections.<name>.provideranthropicanthropic or openai (OpenAI and any OpenAI-compatible endpoint). Needs spring-ai-anthropic / spring-ai-openai on the classpath.
workflow.llm.connections.<name>.model—The model steps use unless they name another (e.g. claude-sonnet-5-5).
workflow.llm.connections.<name>.api-key—Required. Configuration only — from an env var, a K8s secret, Vault; never in a definition.
workflow.llm.connections.<name>.base-urlthe provider’sA gateway, a proxy or a self-hosted OpenAI-compatible server. For openai the API root with /v1 (http://vllm:8000/v1; a bare host gets /v1 added); for anthropic the host without it (https://api.anthropic.com; a trailing /v1 is dropped). See LLM Calls.
workflow.llm.connections.<name>.temperature(unset)Default temperature; unset sends none (current Claude models accept only the default).
workflow.llm.connections.<name>.max-tokens4096Default most output tokens.
workflow.llm.connections.<name>.timeoutPT60SOne call’s limit; a longer one fails the step as LLM_IO (retried).
workflow.llm.connections.<name>.structured-outputpromptHow a responseSchema is enforced: prompt (in the system prompt, then validated) or native (also the provider’s structured output).

The IA catalogue that AGENT steps are validated against when a definition is imported. Read with OAuth2 client credentials; without a catalogue configured, a definition with an AGENT step is refused.

PropertyEnvironment variableDefaultDescription
workflow.agents.catalogue-urlWORKFLOW_AGENTS_CATALOGUE_URL(unset: no catalogue)The published catalogue’s endpoint (a JSON list of agents). Setting it enables the catalogue.
workflow.agents.token-uriWORKFLOW_AGENTS_TOKEN_URI—The token endpoint the client credentials are exchanged at.
workflow.agents.client-idWORKFLOW_AGENTS_CLIENT_IDworkflow-agent-executorThe engine’s service-account client id.
workflow.agents.client-secretWORKFLOW_AGENTS_CLIENT_SECRET—Its secret. Configuration only — from an env var, a K8s secret, Vault; never in a definition.

The engine dispatches run-agent@1 on the agent-calls topic; the agent runtime serves it and replies on upstream. HTTP workers with workflow.workers.http.topics=* leave agent-calls to the runtime. The test kit replaces the catalogue with one that accepts every reference, so tests never contact it.

spring.kafka.bootstrap-servers=localhost:9092

Besides the Spring Cloud Stream binder, two components build a Kafka client of their own: the inbound domain-event consumer (inbound-events-kafka) and the webhook gateway’s producer (webhook-gateway). Both inherit the application’s Kafka client settings, so authentication and TLS configured once reach every client. From lowest to highest precedence:

  1. Spring Kafka: spring.kafka.security.protocol, spring.kafka.ssl.*, spring.kafka.properties.* and the consumer- or producer-specific spring.kafka.consumer.* / spring.kafka.producer.*;
  2. the binder’s spring.cloud.stream.kafka.binder.configuration.*, then its consumer-properties.* / producer-properties.*;
  3. the client’s own map: workflow.events.consumer.properties.* or workflow.webhooks.kafka.properties.*;
  4. what each client needs to work, which nothing overrides — brokers, group id, offset reset, manual commits and byte-array deserializers for the consumer; brokers, byte-array serializers, acks=all and idempotence for the producer (which is never transactional).
spring.kafka.security.protocol=SASL_SSL
spring.kafka.properties.sasl.mechanism=SCRAM-SHA-512
spring.kafka.properties.sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required username="${KAFKA_USER}" password="${KAFKA_PASSWORD}";
spring.kafka.ssl.trust-store-location=file:/etc/kafka/truststore.p12
spring.kafka.ssl.trust-store-password=${KAFKA_TRUSTSTORE_PASSWORD}
spring.kafka.ssl.trust-store-type=PKCS12

Settings given only as spring.cloud.stream.kafka.binder.configuration.* (the binder’s own way) are inherited too. As environment variables: SPRING_KAFKA_SECURITY_PROTOCOL=SASL_SSL, SPRING_KAFKA_PROPERTIES_SASL_MECHANISM=…; a key such as sasl.jaas.config is safest set in a properties file or a SPRING_APPLICATION_JSON, since relaxed binding lower-cases and re-dots env-var names.

The engine wires its own. Destinations, a group per binding and batch-mode for both consumers arrive as defaults, at the lowest precedence — set any of them yourself and yours wins. What is left to the application is the list of functions it composes, because only it knows whether a worker or the forms engine is on the classpath too:

spring.cloud.function.definition=consumeOutbox;consumeUpstream
# Auto-create topics (dev/test only)
spring.cloud.stream.kafka.binder.auto-create-topics=true

With worker-kafka on the classpath, consumeWorkerEvent is appended to that list for you (merged with whatever the application declares), and its inbound group defaults to ${spring.application.name:eventconductor-worker} — so the worker’s group follows the application name unless you set one.

These are what the defaults set, if you need to name them explicitly:

# Outbox topic (internal domain events)
spring.cloud.stream.bindings.consumeOutbox-in-0.destination=outbox
spring.cloud.stream.bindings.consumeOutbox-in-0.group=orchestrator-outbox
spring.cloud.stream.bindings.consumeOutbox-in-0.consumer.batch-mode=true
spring.cloud.stream.bindings.outbox.destination=outbox
# Upstream topic (integration events from external services)
spring.cloud.stream.bindings.consumeUpstream-in-0.destination=upstream
spring.cloud.stream.bindings.consumeUpstream-in-0.group=orchestrator-upstream
spring.cloud.stream.bindings.consumeUpstream-in-0.consumer.batch-mode=true
spring.cloud.stream.bindings.upstream.destination=upstream
# Downstream topic (task execution requests to workers) — the worker's own binding, from worker-kafka
spring.cloud.stream.bindings.consumeWorkerEvent-in-0.destination=downstream
spring.cloud.stream.bindings.consumeWorkerEvent-in-0.group=${spring.application.name:eventconductor-worker}
spring.cloud.stream.bindings.downstream.destination=downstream
# Where events the engine can never process are parked
spring.cloud.stream.bindings.deadLetter.destination=dead-letter

Consumer redelivery (workflow.consumer.retry.*)

Section titled “Consumer redelivery (workflow.consumer.retry.*)”

A Kafka consumer that fails with a retryable error — an optimistic-lock conflict or a deadlock between two consumers writing the same process, the database or the broker being away — has the record redelivered with exponential back-off, without limit, until it succeeds. It is never discarded and its offset is not committed until it has been processed, or deliberately parked on the dead-letter topic. Only a failure that will fail the same way forever (a defective event, a record that cannot be converted) is parked. Batches are retried from the failed record: the records before it are committed, so a conflict on one process does not redo the whole poll.

The engine names this error handler on every one of its consumer bindings (consumeOutbox-in-0, consumeUpstream-in-0, consumeMessages-in-0) itself, with spring.cloud.stream.kafka.bindings.<binding>.consumer.common-error-handler-bean-name=eventconductorEngineErrorHandler and spring.cloud.stream.bindings.<binding>.consumer.max-attempts=1 (so the binder’s own in-memory retry, which ends in a discard, is not in front of it). Both are lowest-precedence defaults: an application that names its own handler still wins.

PropertyDefaultDescription
workflow.consumer.retry.initial-interval100msFirst pause before a failed record is redelivered
workflow.consumer.retry.multiplier2.0Growth of the pause from one attempt to the next
workflow.consumer.retry.max-interval10sLongest pause; an outage is retried at this rate for as long as it lasts
workflow.consumer.retry.max-attempts00 = no limit. A positive value bounds the deliveries of one record, after which it is parked on dead-letter (never discarded) — for operators who prefer a dead letter to a partition stalled behind a failure that will not clear
workflow.consumer.retry.warn-after10A record still failing after this many attempts is logged at WARN, and again every this many attempts

Each redelivery is counted in eventconductor.events.redelivered (tags topic, cause) — see Observability. The same behaviour, with the same properties under eventconductor.worker.consumer.retry.*, applies to every consumer that answers tasks — consumeWorkerEvent-in-0 (worker-kafka, the standalone, HTTP and LLM workers), consumeWorkerEventForRuleRuntime-in-0 (rule runtime) and consumeWorkerEventForFormsEngine-in-0 (forms engine), whose handler eventconductorWorkerErrorHandler comes from the shared module: a task whose reply the broker refused is redelivered rather than committed unanswered, counted in eventconductor.worker.tasks.redelivered. The projector’s consumer uses projector.consumer.retry.*. The inbound domain-event consumer keeps its own fixed back-off (workflow.events.consumer.retry-backoff), also unlimited.

Startup resilience (broker down at startup)

Section titled “Startup resilience (broker down at startup)”

The standalone apps set the following so an unreachable broker at startup fails fast and consumers bind as soon as the broker comes up, instead of blocking the context for ~2 minutes:

# Retry failed bindings every 10 s so consumers bind once the broker becomes available
spring.cloud.stream.bindingRetryInterval=10
# Bound the broker-provisioning admin timeout (Kafka default is 120 s).
# Kafka requires default.api.timeout.ms >= request.timeout.ms.
spring.cloud.stream.kafka.binder.configuration.default.api.timeout.ms=15000
spring.cloud.stream.kafka.binder.configuration.request.timeout.ms=10000

Run the engine as N shared-nothing shards to scale writes past a single database, with shards added and removed hot. Entirely opt-in and off by default — a single-cluster deployment is unchanged and never touches any of this. Design and deployment: k8s/scale/sharded/README.md and k8s/reliability/ELASTIC-SHARDING-DESIGN.md in the benchmark module.

PropertyValuesDefaultDescription
workflow.sharding.enabledtrue | falsefalseMaster switch. On: MessageReceived routes to a shared messages topic every shard consumes (cross-shard SEND_MESSAGE→WAIT_FOR_MESSAGE), and operator commands (retry/cancel/pause/resume) route to the shard that owns the process. Off: messages and commands go through this shard’s own upstream exactly as before
workflow.sharding.shard-idstring—This shard’s id. Stamped on every ProcessStatusChanged (so the read-model row records where the process lives — the lookup command routing and ingress idempotency use). Leave unset when not sharded
workflow.sharding.active-shardscsv—Static list of active shard ids the ingress router places new processes across (round-robin). Overridden by registry-file when set
workflow.sharding.registry-filepath—Path to a file listing the active shard ids (comma/newline separated, # comments). Re-read on an interval, so editing it — in Kubernetes, a mounted ConfigMap — scales the fleet hot, no restart. Keeps the last good list on a read error. When set, it is the active-shard source instead of active-shards
workflow.sharding.registry-refresh-msms5000How often registry-file is re-read
workflow.sharding.placement.datasource.url / .username / .password / .pool-size— / — / — / 4The database holding the placement claims — which shard each business key is placed on, decided once and synchronously before the creation is published. Usually the same database as the read model, separate pool (this one must be writable). Setting the URL is what switches the claim on; without it the ingress router falls back to the eventually-consistent read model and the engine warns at startup that a redelivered creation can be placed a second time. See placement

Each shard is the stock engine re-pointed by config: its own DB_URL, per-shard Kafka bindings (upstream-<i>/downstream-<i>/outbox-<i>/dead-letter-<i> via spring.cloud.stream.bindings.*.destination), and two shared topics — messages, consumed under a per-shard consumer group so every shard sees every message, and process-index, produced to by every shard and consumed by the projector under one group. See the sharded manifests for the full set of overrides.

Mode: embedded + memory (no external dependencies)

Section titled “Mode: embedded + memory (no external dependencies)”
workflow.mode=embedded
workflow.persistence=memory

Kafka and JPA autoconfiguration are excluded automatically — no spring.autoconfigure.exclude needed.

Mode: embedded + jpa (PostgreSQL or H2; MariaDB/Oracle without migrations)

Section titled “Mode: embedded + jpa (PostgreSQL or H2; MariaDB/Oracle without migrations)”
workflow.mode=embedded
workflow.persistence=jpa
spring.datasource.url=jdbc:postgresql://localhost:5432/workflow
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=update

Kafka autoconfiguration is excluded automatically. Workflow definitions placed in classpath:/workflows/ are imported into the database at startup.

Mode: kafka + jpa (full distributed; PostgreSQL, or MariaDB/Oracle without migrations)

Section titled “Mode: kafka + jpa (full distributed; PostgreSQL, or MariaDB/Oracle without migrations)”
workflow.mode=kafka
workflow.persistence=jpa
spring.datasource.url=jdbc:postgresql://localhost:5432/workflow
spring.datasource.username=workflow
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=update
spring.kafka.bootstrap-servers=localhost:9092
# The engine's own bindings (destinations, a group each, batch-mode) come as defaults;
# worker-kafka appends consumeWorkerEvent and names its group after spring.application.name.
spring.cloud.function.definition=consumeOutbox;consumeUpstream
spring.cloud.stream.kafka.binder.auto-create-topics=true

Metrics (Micrometer/Prometheus) and distributed tracing (OpenTelemetry/OTLP), including the meter catalogue for every engine and how to enable Prometheus scraping and OTLP export, are documented on the dedicated Observability page.

The engine’s REST API (/workflow/api/**: processes, messages, events, triggers, schedules, sync invocations) lets a request in when:

  1. workflow.message-api.api-key is set and the X-Api-Key header matches it; or
  2. no key is set and a Spring Security filter chain protects the application (the request has passed the application’s own authentication — the standalone apps below); or
  3. no key is set, no filter chain exists, and workflow.message-api.allow-anonymous=true.

Otherwise it answers 401. Since 2.27.0: before, an engine embedded in an application without Spring Security and without a key answered anybody who could reach the port. At startup the engine logs which of the three applies. A filter chain that permits everything (for instance eventconductor.security.enabled=false in the standalone apps) counts as protection — set a key if such an engine is reachable on a network.

Calling it from outside: send X-Api-Key when the engine has a key; against the standalone orchestrator (Spring Security, no key) send its HTTP Basic credentials (eventconductor.security.user / .password) instead.

The consoles — the admin UI (/_workflow, /_workflow-admin, /_rules, /_forms…, and every other Mateu UI in an application that mounts one of them, since the engine’s menus and pages can be mounted in any of them), the MCP endpoints (Mateu’s /mateu/mcp, and a Spring AI MCP server exposing the engine’s tools), the rule-read endpoints (GET /rules, GET /rules/{id}) and the task-project downloads (/eventconductor/tasks/{group}/*.zip) — follow the same rule without the api key, which a browser cannot send. A request comes in when:

  1. a Spring Security filter chain protects the application; or
  2. workflow.message-api.allow-anonymous=true.

Otherwise it answers 403, with a page (or a JSON body) that tells the operator what to do. Since 2.28.0: before, an application without Spring Security served them to anyone who could reach the port. The check is made on the handler Spring MVC resolved for the request, not on its path, so no spelling of a URL (encoded characters, ;parameters, a UI mounted at the application’s root) gets past it; the application’s own endpoints, the actuator and static resources are not touched, and an application without a console (a worker with Mateu pages of its own) keeps its UIs as they were. The startup line of the engine says how the API and the consoles are protected.

Mounting the admin UI. The consoles are the beans in io.mateu.workflow.infra.in.ui (pages, adapters and the controllers Mateu generates for them). Whether an application has them depends on two things:

  • Mounted by a scan. A @SpringBootApplication in a package under io.mateu.workflow — every standalone app — scans them with everything else. @WorkflowEmbeddedApplication, @FormsEmbeddedApplication and @RulesEmbeddedApplication leave them out on purpose, so a headless or in-memory app never loads them; an embedded application that shows the UI (its own @UI mounts WorkflowMenu, FormsMenu or RulesMenu) adds @EnableWorkflowUi beside the embedded annotation (since 2.28.0: until then Mateu’s own scan of all of io.mateu swept them in, wanted or not).
  • Removed by workflow.ui.enabled=false. However they were mounted — scan or @EnableWorkflowUi — the property drops them before any is created. It wins over the annotation, so one image can ship the UI and a deployment can still turn it off.

Mounted either way, they sit behind the access rule above: the check is made on the resolved handler, so @EnableWorkflowUi changes what is mounted, never who may reach it.

PropertyTypeDefaultDescription
workflow.ui.enabledbooleantrueMount the admin UI. false drops every console bean the EventConductor modules contribute (io.mateu.workflow.infra.in.ui: the workflow, workflow-admin, rules and forms consoles and the task-project zips) before it is created, so those routes answer 404 — also when @EnableWorkflowUi mounted them. An application whose own Mateu UI mounts WorkflowMenu must drop that too
workflow.ui.localestringenThe language the console is drawn in, a BCP 47 tag. The engine’s pages are written in English; this makes Mateu’s own words on them (the New button, the search box, confirmations, toasts) match, instead of following the browser’s Accept-Language. auto follows the browser, as before 2.41. An application that declares its own Mateu Translator keeps deciding the language (and translating)

The MCP server is the application’s (the spring-ai-starter-mcp-server-webmvc starter and the ToolCallbackProvider it registers), so it is switched off with Spring AI’s own spring.ai.mcp.server.enabled=false.

The standalone apps protect their HTTP endpoints (UI, REST, actuator) with basic authentication, configured via eventconductor.security.*:

PropertyEnv variableDefaultDescription
eventconductor.security.enabledSECURITY_ENABLEDtrueMaster switch for HTTP security
eventconductor.security.userSECURITY_USERadminUsername
eventconductor.security.passwordSECURITY_PASSWORD(blank)Password. If left blank, a random password is generated at startup and — since 2.28.0 — not shown, so nobody can log in: set it

The standalone images are fully configured via environment variables. All variables have defaults so only values that differ from the defaults need to be set. Note that apps/docker-compose.yml overrides several of them (it sets SERVER_PORT=8080 inside each container and the compose Postgres credentials workflow/secret).

VariableDefaultMaps to
SERVER_PORT8105server.port
WORKFLOW_MODEkafkaworkflow.mode
WORKFLOW_PERSISTENCEjpaworkflow.persistence
DB_URLjdbc:postgresql://127.0.0.1:5432/workflowspring.datasource.url
DB_USERNAMEuser_appspring.datasource.username
DB_PASSWORD— (no default: set it)spring.datasource.password
DB_DRIVERorg.postgresql.Driverspring.datasource.driver-class-name
JPA_DIALECTorg.hibernate.dialect.PostgreSQLDialectspring.jpa.database-platform
DDL_AUTOupdatespring.jpa.hibernate.ddl-auto
FLYWAY_ENABLEDtrueworkflow.schema.enabled
FLYWAY_TABLEflyway_schema_historyworkflow.schema.table
DB_POOL_SIZE16spring.datasource.hikari.maximum-pool-size
DB_CONNECTION_TIMEOUT20000spring.datasource.hikari.connection-timeout (ms)
KAFKA_BROKERSlocalhost:9092spring.cloud.stream.kafka.binder.brokers
KAFKA_CONCURRENCY3Consumer threads per pod on each consumer binding
KAFKA_MIN_PARTITIONS6spring.cloud.stream.kafka.binder.min-partition-count
BUILTIN_WORKER_TOPICShttp-calls,llm-calls,event-publicationsThe topics the orchestrator’s built-in workers (HTTP_CALL, LLM_CALL, PUBLISH_EVENT) consume, binding consumeWorkerEvent, group orchestrator-builtin-workers. Take a topic out when a standalone worker serves it, and turn the built-in one off (WORKFLOW_HTTP_ENABLED / WORKFLOW_LLM_ENABLED / WORKFLOW_EVENTS_WORKER_ENABLED=false) — two groups on one topic run every task twice
BUILTIN_WORKERS_START_OFFSETearliestWhere that group starts on a topic it has not consumed yet. Set latest for the rollout that moves a topic from a standalone worker onto the orchestrator, or the retained tasks are run again
DEFAULT_STEP_TIMEOUT_MS0 (off)workflow.default-step-timeout-ms — fallback deadline for ACTION, RULE, HTTP_CALL, LLM_CALL and PUBLISH_EVENT steps that declare none
STALLED_STEP_AFTER_MS900000workflow.stalled-step-after-ms — how long a live step with no deadline may wait before eventconductor.steps.stalled counts it
SECURITY_ENABLEDtrueeventconductor.security.enabled
SECURITY_USERadmineventconductor.security.user
SECURITY_PASSWORD(blank)eventconductor.security.password
TRACING_SAMPLING0.0management.tracing.sampling.probability
OTLP_TRACING_ENDPOINThttp://localhost:4318/v1/tracesmanagement.opentelemetry.tracing.export.otlp.endpoint
OTLP_METRICS_ENABLEDfalsemanagement.otlp.metrics.export.enabled — push metrics to a collector as well as exposing them for scraping
OTLP_METRICS_ENDPOINThttp://localhost:4318/v1/metricsmanagement.otlp.metrics.export.url
OTLP_METRICS_INTERVAL60smanagement.otlp.metrics.export.step
VariableDefaultMaps to
SERVER_PORT8106server.port
WORKFLOW_MODEkafkaworkflow.mode
WORKFLOW_PERSISTENCEjpaworkflow.persistence
DB_URLjdbc:postgresql://127.0.0.1:5432/workflowspring.datasource.url
DB_USERNAMEuser_appspring.datasource.username
DB_PASSWORD— (no default: set it)spring.datasource.password
DB_DRIVERorg.postgresql.Driverspring.datasource.driver-class-name
JPA_DIALECTorg.hibernate.dialect.PostgreSQLDialectspring.jpa.database-platform
DDL_AUTOupdatespring.jpa.hibernate.ddl-auto
FLYWAY_ENABLEDtrueforms.schema.enabled
FLYWAY_TABLEflyway_schema_history_formsforms.schema.table
DB_POOL_SIZE16spring.datasource.hikari.maximum-pool-size
DB_CONNECTION_TIMEOUT20000spring.datasource.hikari.connection-timeout (ms)
KAFKA_BROKERSlocalhost:9092spring.cloud.stream.kafka.binder.brokers
SECURITY_ENABLEDtrueeventconductor.security.enabled
SECURITY_USERadmineventconductor.security.user
SECURITY_PASSWORD(blank)eventconductor.security.password
TRACING_SAMPLING0.0management.tracing.sampling.probability
OTLP_TRACING_ENDPOINThttp://localhost:4318/v1/tracesmanagement.opentelemetry.tracing.export.otlp.endpoint
OTLP_METRICS_ENABLEDfalsemanagement.otlp.metrics.export.enabled — push metrics to a collector as well as exposing them for scraping
OTLP_METRICS_ENDPOINThttp://localhost:4318/v1/metricsmanagement.otlp.metrics.export.url
OTLP_METRICS_INTERVAL60smanagement.otlp.metrics.export.step

The rule-standalone-app follows the same variable set with SERVER_PORT defaulting to 8107, plus RULES_PERSISTENCE (jpa), RULES_GRPC_ENABLED (false since 2.28.0: the gRPC read API is plaintext and unauthenticated — enable it only behind mTLS/a network policy) and RULES_GRPC_PORT (9090).

Switching databases via environment variables

Section titled “Switching databases via environment variables”

To use MariaDB instead of PostgreSQL, override the three DB-related variables:

Terminal window
DB_URL=jdbc:mariadb://db:3306/workflow
DB_DRIVER=org.mariadb.jdbc.Driver
JPA_DIALECT=org.hibernate.dialect.MariaDBDialect

For Oracle (remember the DBMS_LOCK grant prerequisite):

Terminal window
DB_URL=jdbc:oracle:thin:@db:1521:XE
DB_DRIVER=oracle.jdbc.OracleDriver
JPA_DIALECT=org.hibernate.dialect.OracleDialect

See ia-agent-service for the full application.yaml reference.

Key environment variables:

VariableDescription
ANTHROPIC_API_KEYAnthropic API key (required)