ADR / 009

Model long-running automation as a run record with a state machine

When automation spans steps, systems or days, give each run an identity, a state and step-level guards—so it can wait, fail, resume and finish exactly once.

Reference pattern

Independently created. Contains no employer or client implementation detail, internal names or figures.

01Context

A monthly commercial cycle refreshes data, computes KPIs, classifies customers, writes results to the CRM and generates actions. It runs as one scheduled job. When a step fails the job is restarted from the beginning, steps that already succeeded run again, and some accounts receive their actions twice. Nobody outside the platform team can see where a run stands.

02Decision drivers

  1. D01

    Steps depend on work the automation does not control

  2. D02

    A restart must not repeat completed steps

  3. D03

    The business owner needs to see progress and failures

  4. D04

    Test runs must not have side effects

03Options considered

Options considered: when each would be the right choice, what it costs, and the verdict under these premises
OptionRight whenCost / trade-offVerdict
One scheduled job calling every stepShort, local, idempotent workRestart from zero; no identity; no visibilityRejected
A chain of triggers, one per stepTwo or three local stepsNo run identity; a failure silently breaks the chainRejected
Run record with a state machine and step guardsMulti-step, cross-system or long-running workA run model, a guard per step and a small run viewSelected

Every option is right under some premises. The verdict applies to the context above.

04Decision

Create one run record per business key (for example period and scope), refused if one already exists. The run moves through declared states—created, running, waiting, completed, failed, aborted—and each step records its own outcome and checks its own “already done for this run” guard. Long work is split into keyed batches with continuations. Failures hold the run at the failed step; resume continues from there. A dry-run flag executes every check without side effects.

05Consequences

What this choice changes elsewhere in the system.

  1. Observability

    Anyone can open a run and see its state, step, progress, failures and owner.

  2. Recovery

    A resume never repeats a completed step or effect.

  3. Dependencies

    Dependencies become explicit waiting states with budgets.

  4. Scope

    Simple local automations stay simple: the pattern is reserved for work that needs it.

06Revisit when

The decision holds while its context holds. Challenge it when:

01

The work fits in one transaction and one system.

02

A platform orchestrator provides run identity, state and resume natively.

07Where this decision is applied

The decision says why this path was chosen; each case shows how it takes part in a larger architecture.

  1. Automation case / 01Designing stateful orchestration for a long-running commercial processOne durable run per period with an explicit state machine, start-once steps, waiting as a state, a lightweight continuation that wakes unfinished runs, retry classified at the step boundary and a run record that answers the operator's questions—so a failure in step seven resumes at step seven.AutomationData & IntegrationsRevenue OperationsArchitecture case · 12 min

Decisions this one depends on, or constrains.

  1. ADR / 003Use code at orchestration boundariesKeep transparent local rules declarative; move stateful, cross-system orchestration behind tested service boundaries.Proposed patternAutomation · Governance · Integration
  2. ADR / 010Automate exits, not only entriesEvery automation that creates work when a record enters a state must also define what happens when it leaves it—or the downstream state goes stale.Proposed patternAutomation · RevOps · Data