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.
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
- D01
Steps depend on work the automation does not control
- D02
A restart must not repeat completed steps
- D03
The business owner needs to see progress and failures
- D04
Test runs must not have side effects
03Options considered
| Option | Right when | Cost / trade-off | Verdict |
|---|---|---|---|
| One scheduled job calling every step | Short, local, idempotent work | Restart from zero; no identity; no visibility | Rejected |
| A chain of triggers, one per step | Two or three local steps | No run identity; a failure silently breaks the chain | Rejected |
| Run record with a state machine and step guards | Multi-step, cross-system or long-running work | A run model, a guard per step and a small run view | Selected |
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.
- Observability
Anyone can open a run and see its state, step, progress, failures and owner.
- Recovery
A resume never repeats a completed step or effect.
- Dependencies
Dependencies become explicit waiting states with budgets.
- 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:
The work fits in one transaction and one system.
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.
08Related decisions
Decisions this one depends on, or constrains.
- ADR / 003Use code at orchestration boundariesKeep transparent local rules declarative; move stateful, cross-system orchestration behind tested service boundaries.
- 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.