Skip to content

Managing Orders

Create and manage clinical orders using the iFlow CLI.

Overview

Orders represent clinical cases in iFlow. Each order carries one or more samples, selects a test mode, runs through a labflow, and — once signed — owns an immutable signed PDF. See the Orders service page for the data model and Orders state machine for the full transition graph.

Prerequisites

  1. Installed CLI — see Installation.
  2. Authenticated — iflow login --token <PAT> (see Token management).
  3. Project selected — iflow config select-project.

Listing orders

iflow orders list

Filter by status:

iflow orders list --status created
iflow orders list --status analyzing
iflow orders list --status review
iflow orders list --status sign_off
iflow orders list --status completed

Filter by priority:

iflow orders list --priority low
iflow orders list --priority medium
iflow orders list --priority high

Valid status values: created, analyzing, review, sign_off, completed, cancelled. Legacy compat aliases — reviewed, signed_off, amended — still resolve but are not used for new transitions.

Creating orders

Minimal

iflow orders create --display-id ORD-2026-0001

With clinical details

iflow orders create \
  --display-id ORD-2026-0001 \
  --accession ACC-2026-001 \
  --mode somatic \
  --priority high \
  --indication "Suspected BRCA1 variant" \
  --provider "Dr. Jane Smith" \
  --facility "City General Hospital" \
  -t hereditary \
  -t wes

Options

Option Description
-n, --display-id Order display ID (required; unique per project)
--accession Lab accession number
--external-id External system reference
--description Order description
--mode Analysis mode: hereditary or somatic
--priority Priority: low, medium, or high
--indication Clinical indication
--provider Ordering provider name
--facility Ordering facility name
-t, --tag Tags (repeatable)

Getting an order

iflow orders get ORDER_ID

Sample output:

Order: ORD-2026-0001
  ID: abc123-def456-...
  Status: created
  Mode: somatic
  Priority: high
  Accession: ACC-2026-001
  Indication: Suspected BRCA1 variant
  Provider: Dr. Jane Smith
  Facility: City General Hospital
  Created: 2026-01-13T10:00:00Z
  Tags: hereditary, wes

Status workflow

created → analyzing → review → sign_off → completed
                                   ↓
                                amended (after sign-off)

Any non-terminal status can also transition to cancelled. See Orders state machine for the authoritative transition graph.

Transitioning

# Hand off to pipeline
iflow orders transition ORDER_ID analyzing

# Move to curation
iflow orders transition ORDER_ID review

# Ready for sign-off
iflow orders transition ORDER_ID sign_off

# Cancel at any non-terminal point
iflow orders transition ORDER_ID cancelled

Sign-off happens in the UI

The final transition from sign_off to completed is driven by the Approve-and-Sign flow in the web UI because the confirmation modal is part of the audit chain. The CLI does not expose a direct sign_off → completed command.

Managing samples on an order

iflow orders samples ORDER_ID               # list
iflow orders add-sample ORDER_ID SAMPLE_ID  # add
iflow orders remove-sample ORDER_ID SAMPLE_ID  # remove

Generating a samplesheet

Generate an nf-core compatible samplesheet CSV from an order's samples:

iflow orders samplesheet ORDER_ID > samplesheet.csv

Output columns: sample, fastq_1, fastq_2, strandedness, specimen_type, sex, accession_id.

Deleting an order

iflow orders delete ORDER_ID

You are prompted to confirm. Deleting an order that has already been signed is not possible — amend it instead (see Amendments).

End-to-end example

# 1. Authenticate and select a project
iflow login --token "$IFLOW_PAT"
iflow config select-project

# 2. Create the order
iflow orders create \
  --display-id ORD-2026-0042 \
  --accession ACC-2026-0042 \
  --mode somatic \
  --priority high \
  --indication "Suspected hereditary cancer syndrome" \
  -t somatic -t panel

# 3. Add the sample (assumed already registered)
iflow orders add-sample ORD-2026-0042 S-2026-0042

# 4. Hand off to analysis
iflow orders transition ORD-2026-0042 analyzing

# 5. Submit the pipeline run
iflow analyses submit \
  --pipeline somatic-mock \
  --order-id ORD-2026-0042 \
  -P sample_vcf=samples/s-2026-0042/uploads/somatic.vcf.gz \
  --watch

# 6. Once succeeded, move to review
iflow orders transition ORD-2026-0042 review

The remaining transitions (review → sign_off → completed) are easier to drive from the web UI, where the variant browser and Approve-and-Sign modal live. See the default scenario walkthrough.

REST API

Base URL: https://miner.<env-domain>/api/v1/orders. The CLI is a thin wrapper; everything here is also callable via HTTP.

Create order:

curl -X POST https://miner.<env-domain>/api/v1/orders \
  -H "Authorization: Bearer $IFLOW_PAT" \
  -H "X-Project-ID: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "display_id": "ORD-2026-0042",
    "mode": "somatic",
    "priority": "high",
    "indication": "Suspected hereditary cancer syndrome"
  }'

List orders:

curl "https://miner.<env-domain>/api/v1/orders?status=review" \
  -H "Authorization: Bearer $IFLOW_PAT" \
  -H "X-Project-ID: $PROJECT_ID"

Transition status:

curl -X POST https://miner.<env-domain>/api/v1/orders/ORDER_ID/transition \
  -H "Authorization: Bearer $IFLOW_PAT" \
  -H "X-Project-ID: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "review"}'

See API Reference for the full list.

Troubleshooting

"No project specified"

iflow config select-project
# or
iflow orders list -p PROJECT_ID

"Invalid transition"

The requested transition is not in the allowed set. Check the current status and the Orders state machine.

"Permission denied"

You may be missing orders:write / orders:write_any or you may not be assigned to the current stage. See RBAC Matrix.

Next steps