Skip to content

Managing Orders

Create and manage clinical orders using the Flow CLI.

Overview

Orders represent clinical cases in the Flow platform. Each order can contain:

  • Samples - Biological samples for analysis
  • Pipeline runs - Associated analysis runs
  • Status tracking - FDA/CLIA-compliant workflow states

Prerequisites

  1. Installed CLI - See Installation
  2. Authenticated - Run flow login
  3. Project selected - Run flow config select-project

Listing Orders

List orders for the selected project:

flow orders list

Filter by status:

flow orders list --status created
flow orders list --status analyzing
flow orders list --status ready_for_review

Filter by priority:

flow orders list --priority urgent
flow orders list --priority stat

Creating Orders

Basic Order

flow orders create -n "Patient Case 001"

With Clinical Details

flow orders create \
  -n "Smith Family Case" \
  --accession ACC-2026-001 \
  --priority urgent \
  --indication "Family history of hereditary cancer" \
  --test-type "Whole Exome Sequencing" \
  --provider "Dr. Jane Smith" \
  --facility "City General Hospital" \
  -t hereditary \
  -t wes

Order Options

Option Description
-n, --name Order name (required)
--accession Lab accession number
--external-id External system reference
--description Order description
--priority Priority: routine, urgent, stat
--indication Clinical indication
--test-type Type of genetic test
--provider Ordering provider name
--facility Ordering facility name
-t, --tag Tags (can specify multiple)

Getting Order Details

flow orders get ORDER_ID

Output:

Order: Smith Family Case
  ID: abc123-def456-...
  Status: created
  Priority: urgent
  Accession: ACC-2026-001
  Indication: Family history of hereditary cancer
  Test Type: Whole Exome Sequencing
  Provider: Dr. Jane Smith
  Facility: City General Hospital
  Created: 2026-01-13T10:00:00Z
  Tags: hereditary, wes

Order Status Workflow

Orders follow a FDA/CLIA-compliant workflow:

created -> analyzing -> ready_for_review -> reviewed -> signed_off -> completed
                                                                        -> amended

Transitioning Status

# Start analysis
flow orders transition ORDER_ID analyzing

# Mark ready for review
flow orders transition ORDER_ID ready_for_review

# First-level review complete
flow orders transition ORDER_ID reviewed

# Final sign-off
flow orders transition ORDER_ID signed_off

# Complete the order
flow orders transition ORDER_ID completed

Valid Transitions

From To
created analyzing, cancelled
analyzing ready_for_review, cancelled
ready_for_review reviewed, cancelled
reviewed signed_off, ready_for_review
signed_off completed
completed amended
amended completed

Managing Samples

List Samples in Order

flow orders samples ORDER_ID

Add Sample to Order

flow orders add-sample ORDER_ID SAMPLE_ID

Remove Sample from Order

flow orders remove-sample ORDER_ID SAMPLE_ID

Deleting Orders

flow orders delete ORDER_ID

You'll be prompted to confirm the deletion.

Complete Workflow Example

This example shows the full workflow from order creation to pipeline execution:

1. Login and Select Project

flow login --token YOUR_PAT_TOKEN
flow config select-project

2. Create the Order

flow orders create \
  -n "Case-2026-0113" \
  --accession "ACC-2026-0113" \
  --priority urgent \
  --indication "Suspected hereditary cancer syndrome" \
  --test-type "Hereditary Cancer Panel" \
  -t hereditary \
  -t cancer

Output:

Order created successfully!
  ID: e7f8a9b0-1234-5678-90ab-cdef12345678
  Name: Case-2026-0113
  Status: created
  Priority: urgent
  Accession: ACC-2026-0113

3. Submit Pipeline Run with Order Association

File paths are relative to your project bucket:

flow runs submit \
  --pipeline hereditary-mock \
  --order-id e7f8a9b0-1234-5678-90ab-cdef12345678 \
  -P case_id=Case-2026-0113 \
  -P child_fastq=data/sample_R1.fastq.gz \
  -P child_fastq=data/sample_R2.fastq.gz \
  --watch

4. Transition Order to Analyzing

flow orders transition e7f8a9b0-... analyzing

5. Check Order Status

flow orders get e7f8a9b0-...

6. List Runs for Order

flow runs list --order-id e7f8a9b0-...

Using Different Projects

All order commands use your selected project by default. To work with a different project:

# Override for single command
flow orders list -p OTHER_PROJECT_ID

# Or switch default project
flow config select-project OTHER_PROJECT_ID

API Access

For programmatic access, the orders API is available at https://miner.flow.labpgx.com/api/v1/orders:

Create order:

curl -X POST https://miner.flow.labpgx.com/api/v1/orders \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Order",
    "priority": "routine",
    "indication": "Testing"
  }'

List orders:

curl https://miner.flow.labpgx.com/api/v1/orders \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID"

Transition status:

curl -X POST https://miner.flow.labpgx.com/api/v1/orders/ORDER_ID/transition \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"status": "analyzing"}'

Troubleshooting

"No project specified"

You need to select a default project or provide -p:

# Select default project
flow config select-project

# Or specify for single command
flow orders list -p PROJECT_ID

"Invalid transition"

Order status transitions must follow the workflow. Check the current status:

flow orders get ORDER_ID

Then verify the transition is valid according to the workflow diagram.

"Resource not found"

The order may not exist or you may not have access to it. Verify the order ID and project ID are correct.

Next Steps