Skip to content

Session state machine reference

A Session tracks two things independently: where it is in the pipeline (current_stage) and how it's doing (health). Keeping them separate is why a session can be at the checked stage and still be blocked by errors, or ready to confirm.

Stages

current_stage advances through:

CREATED → UPLOADED → PARSED → TRANSFORMED → VALIDATED → CONFIRMED → APPROVED → EXPORTED
  • Automated stages — parsed, transformed, checked — advance only when their outcome is passed or warnings. On errors, the stage does not advance, so you can fix and re-run from where it stopped.
  • Manual stages — confirmed, approved, exported — always advance when actioned, regardless of outcome.

Stage outcomes

Each stage records an outcome in a per-stage summary:

Outcome Meaning
pending Not started.
running In progress.
passed Completed cleanly.
warnings Completed with warnings.
errors Failed; blocks progress.

Per stage, the session stores the outcome, an error_count, a warning_count, and an updated_at timestamp — which is what drives per-step colouring in the UI.

Optional sources and skipped work

When a DataContract source is optional and not delivered, a transformer that depends only on it is marked SKIPPED instead of failing. A skipped transformer counts as resolved, so the transformed and checked stages still reach passed and health can become ready. On export, the absent optional source is listed under omissions in datapackage.json and the session's export_report. A missing required source still produces errors.

Health

health is derived from the stages and current stage — never set directly. The derivation, in priority order:

  1. current_stage == exported → completed
  2. any stage outcome is errors → blocked
  3. any stage outcome is running → in_progress
  4. any stage outcome is warnings → attention
  5. current_stage in (checked, confirmed, approved) with no errors/warnings → ready
  6. no stages recorded yet → created
  7. otherwise → in_progress

So: one error anywhere makes the whole session blocked; warnings without errors make it attention; a clean run through validation makes it ready to confirm.

Re-running a blocked session

blocked stops the session from moving forward — it does not stop a re-run. Until the session is confirmed, run, transform and check can be started again, including on a checked session whose business rules failed. After a business rule, an entity rule, a transformer mapping or a catalog was fixed: run (or check) on a checked session re-runs entity validation and the business rules; transform on a transformed or checked session re-runs from the transform. The session steps back to the stage before the one being re-run (checked → transformed, transformed/checked → parsed) until the new run records its outcome, and each start is recorded as a new run in the run history. While the stage that failed is re-executed the session stays blocked (its stage entry is running with previous_outcome: errors); the block lifts only when the re-run records a clean outcome, and returns if it fails again. confirm, approve and export remain gated.

Why this matters when reviewing

When you open the Sessions list, the health column tells you what needs action (blocked / attention) versus what's progressing or ready. The stage tells you how far each delivery has gone. Together they let you triage many deliveries at a glance without opening each one.