Skip to content

Labflows

A labflow is the configurable state machine that an order travels through. It defines the stages, the valid transitions between them, and the capability flags that control what each stage allows.

Data model

A labflow is composed of several related records:

Table Purpose
Labflow The workflow definition: name, version, scope, immutability
LabflowStage Individual stages: analyzing, review, sign_off, etc.
LabflowTransition Allowed transitions between stages
OrderLabflow Binds one order to one labflow instance
OrderStageState Per-stage execution state for the order
OrderStageTransitionHistory Immutable audit trail of every transition

Scoping

Labflows exist at three levels:

  • System — built-in, applies to every project unless overridden.
  • Org — defined at the organization level; applies to every project in the org unless overridden.
  • Project — defined on a single project.

The most specific scope wins. A project-level labflow overrides an org-level one, which overrides the system default.

Stage state machine

Each stage on an order progresses through:

stateDiagram-v2
    [*] --> unassigned
    unassigned --> pending: assign user
    unassigned --> skipped: skip (admin)
    unassigned --> on_hold: pause
    pending --> in_progress: start work
    pending --> on_hold: pause
    pending --> skipped: skip (admin)
    in_progress --> completed: complete
    in_progress --> on_hold: pause
    in_progress --> skipped: skip (admin)
    on_hold --> pending: resume
    on_hold --> in_progress: resume
    on_hold --> skipped: skip (admin)
    completed --> [*]
    skipped --> [*]

The valid transitions are enforced by the model:

  • unassigned → pending, on_hold, skipped
  • pending → in_progress, on_hold, skipped
  • in_progress → completed, on_hold, skipped
  • on_hold → pending, in_progress, skipped
  • completed, skipped — terminal

Terminal states cannot be reversed

Once a stage reaches completed or skipped, it cannot be undone. If the wrong stage was completed, the only recourse is an amendment after sign-off.

Capability flags per stage

Each stage carries four flags that govern what users can do while the order is at that stage:

Flag Controls
browser_viewable Whether the VCF browser is visible
browser_editable Whether variants can be edited
report_viewable Whether the report is visible
report_editable Whether the report can be edited

Typical defaults:

  • analyzing — browser_viewable=true, everything else false. Users can peek at incoming VCFs but cannot curate yet.
  • review — all four true. The working stage.
  • sign_off — report_viewable=true, everything else false. The report is frozen pending sign-off.
  • completed / cancelled / skipped — terminal; all four false.

These flags combine with RBAC. For example, to edit a variant the caller must be project_editor or higher, and be assigned to the current stage, and the stage's browser_editable must be true (unless the caller holds orders:write_any).

Assignment

A stage starts in unassigned. Until a user is assigned, the stage is read-only even for project_editor. Assignment options:

  • Self-assign — any project_editor can pick up an unassigned stage.
  • Assign another user — requires orders:write_any (project_admin or higher).

Assignment is captured in OrderStageState.assigned_user_id and also denormalised onto OrderLabflow for fast dashboard rendering.

Self-assign for cleaner audit trails

In a CLIA-compliant workflow, "who accepted responsibility and when" is a compliance question. Prefer self-assignment over admin bulk-assign.

Transition history

Every transition is written to OrderStageTransitionHistory with:

  • from_stage_id, to_stage_id, from_state, to_state
  • transition_id (the LabflowTransition that fired)
  • transitioned_by_id (the acting user)
  • transitioned_at
  • Optional notes, tags, properties

This table is append-only and serves as the immutable audit trail required for CLIA-style documentation.

Configuring a labflow

Labflow configuration is an admin task. System labflows ship with iFlow; org and project labflows are edited through the admin UI:

  • New labflow — clone from an existing system labflow or start from scratch.
  • Add a stage — define code, name, position, colour, icon, and the four capability flags.
  • Add a transition — pick from_stage, to_stage, button label, and whether it is the default forward path.
  • Publish — once published, a labflow can become is_immutable=true. Immutable labflows cannot be edited, only cloned.

Versioning

Each labflow record has a version field. Operating labs typically publish a versioned labflow and lock it immutable so in-flight orders always run on the same definition. Changes cut a new version.

UI

  • Labflows list — /labflows.
  • Labflow detail — /labflows/{labflow_id}. Stage list, transitions, version, immutability.
  • Order labflow panel — on the order detail page, shows the current stage, assignment, and the available transition buttons.

API

Base URL: https://miner.<env-domain>/api/v1/labflows for labflow definitions; order-specific state lives under https://miner.<env-domain>/api/v1/orders/{order_id}/labflow.