Skip to content
Demiton

Workflows

Workflows are the core execution mechanism of the Demiton platform. A workflow defines a deterministic sequence of steps that performs a specific operational task — retrieving labour records, transforming them into canonical structures, posting project costs to an ERP ledger.

Execution model

When a workflow is triggered:

  1. A WorkflowRun record is created
  2. TaskRun records are created for each step
  3. The run is persisted to the database (pre-flight commit)
  4. Execution is delegated to the ARQ worker

Execution always occurs asynchronously. No workflow logic runs inside the HTTP control plane.

Step lifecycle

Each step transitions through a defined lifecycle:

StateMeaning
PENDINGCreated, not yet started
RUNNINGCurrently executing
SUCCEEDEDCompleted successfully
FAILEDEncountered an error; workflow stops
SUSPENDEDAwaiting governance approval
SKIPPEDBypassed by a LOGIC_GATE

All state transitions are recorded in the platform database.

Workflow verbs

Each step executes exactly one verb. See the Workflow Verbs reference for the complete list.

External verbs (interact with adapters):

  • FETCH — retrieve records from an external system
  • LOOKUP — retrieve a single entity
  • PUSH — write records into an external system
  • EXECUTE — perform operational commands

Internal verbs (operate in memory only):

  • TRANSFORM — normalize and map records
  • GOVERN — evaluate governance policies
  • LOGIC_GATE — control workflow branching

Pipeline context

During execution, workflows maintain a PipelineContext — an in-memory structure that stores step outputs. It is:

  • scoped to a single workflow run
  • cleared after execution completes
  • never shared across runs

This prevents cross-run data contamination. Sensitive data (credentials, PII) lives in RAM only and is never persisted to the workflow state.

Suspension and approval

Workflows may suspend when a governance check requires manual approval.

When a step returns a suspension signal:

  1. The workflow pauses at that step
  2. Current state is persisted to the database
  3. An approval request is created
  4. Execution resumes only after an authorized user approves

This enables approval flows for financial postings, vendor creation, and other sensitive operations.

Triggers

Workflows can be triggered:

  • Manually — user action from the platform UI or API
  • Scheduled — cron expression evaluated by the workflow scheduler
  • Programmatic — via the API (POST /workflows/{id}/runs)

See Scheduled Pipelines for cron configuration.

Fan-out execution

Workflows that need to process a list of records in parallel use ChunkedDispatch. The runtime spawns one ChunkRun per generator record, allowing large datasets to be processed concurrently while each chunk maintains its own isolated execution context.

Further reading