Skip to content
Cyoda Documentation
Settings

Workflows and events

A workflow is the state machine an entity lives inside. It declares the states an entity can be in, the transitions between them, the criteria that gate whether a transition is allowed, and the processors that run along the way. This page explains the concept; the Build guide for workflows and processors covers how to configure one.

State machines define allowed change

Section titled “State machines define allowed change”

Every entity type has a workflow. Nothing changes the entity except a transition defined in that workflow. A transition is atomic: it produces a new, durable revision of the entity, runs any attached processors under the platform’s event contract, and either succeeds or has no effect.

Workflows are general state machines, not pipelines. Transitions can be automatic (fire as soon as their source state is entered and any criteria are satisfied) or manual (fire only when invoked by an actor). A workflow can contain cycles, branches, and multiple terminal-looking states that are actually re-entered later — it does not need to terminate at all.

Triggers

Section titled “Triggers”

Transitions fire in one of two ways:

  • Manual — an actor (a user, a service, an admin) calls the transition by name through the API.
  • Automatic — on entering a state, the first valid auto transition fires within the same transaction, recursing until no further auto transition applies.

Processors

Section titled “Processors”

A processor is code that runs as part of a transition. It can read the entity, compute a new field, call an external service, persist a side effect, or reject the transition.

Two flavours:

  • Internal processors — shipped with the platform for common work (validation, projection, enrichment) and invoked declaratively.
  • External processors — your code, hosted anywhere, called by Cyoda over gRPC. External processors preserve audit hygiene (every call is logged against the transition), keep authorization simple (the platform brokers identity), and support bidirectional streaming for high-throughput workloads. For why gRPC is preferred and how to implement one, see Build → client compute nodes.

Processors can run synchronously within the transition’s transaction, or asynchronously alongside it.

Processors run in one of three modes: SYNC (inline, shares the transition’s transaction — failure aborts the transition), ASYNC_SAME_TX (runs asynchronously but in the same transaction context — failure still aborts), or ASYNC_NEW_TX (runs in a separate transaction via savepoint isolation — failure is logged and the transition succeeds). Choose the mode based on how atomically the side-effect must compose with the state change.

Audit trail is the storage model

Section titled “Audit trail is the storage model”

Because every transition produces a revision and every processor invocation is recorded against it, the audit trail is not a separate log — it is a view of the storage. You can query the transitions an entity has been through, the criteria that were evaluated, the processors that ran, and the inputs and outputs of each. Point-in-time queries use the same index.

Why this matters

Section titled “Why this matters”

State machines plus durable transitions plus a queryable audit trail are the native ingredients for regulated, auditable, and replayable systems. Replaying a workflow from history does not require an event-sourcing framework on the side — it is the default behavior of the store.

Where to go next

Section titled “Where to go next”