Creating Sequencing Orders

A sequencing order is created through a multi-step wizard at /orders/new. The wizard is a questionnaire: it collects everything the facility needs to accept the request, plus the per-sample metadata that will later drive MIxS validation and ENA submission. Nothing is sent to the facility until you reach the end and submit — the order sits in DRAFT until then.

The wizard is configurable by facility admins through the Form Builder. Admins can add, hide and reorder fields, mark them admin-only, and enable optional modules. Everything below describes the default configuration on a fresh installation.

The two fixed sections

Unlike most form builders, SeqDesk’s order form has exactly two user-facing sections and they cannot be renamed, removed or added to:

Section id	Displayed name	What lands here
`group_details`	Sequencing Order Details	Everything that is not sequencing-related
`group_sequencing`	Sequencing Information	Sequencing technology, instrument and library fields

Every user-editable order-level field is normalised into one of the two on save. A field is routed to Sequencing Information if it is a sequencing-tech field, if its name is one of platform, instrumentModel, libraryStrategy, librarySource, librarySelection, or if its group name or description contains one of sequencing, library, instrument, platform, technology, software, read. Everything else falls back to Sequencing Order Details.

If you add a custom group in the form builder, its fields will still appear under one of the two fixed sections. Design your form around that rather than around groups.

Wizard steps

Steps are derived from the form configuration, so the exact list varies. In the default configuration you get Sequencing Order Details → Sequencing Information → Samples → Review.

Study (only with per-study questionnaires)

Appears as the very first step when the dynamic-studies module is enabled and you are creating (not editing) an order. It lets you associate the order with a study up front so that sample metadata is collected against that study’s questionnaire. It is skipped when a study was already preselected via a URL parameter.

Sequencing Order Details

Field	Required	Notes
Sequencing Order Name	No	Free text, e.g. `Soil microbiome study - Batch 1`. The order number is generated separately and cannot be changed.
Number of Samples	No	Pre-fills the sample table with that many blank rows.

The Number of Samples field carries a client-side validation hint of 1–500. The server does not enforce it: POST /api/orders simply runs parseInt on whatever it receives. The value is also self-correcting — every time samples are saved, numberOfSamples is rewritten to the actual row count.

Your contact details are not asked for here. On creation SeqDesk copies contactName and contactEmail from your user profile and billingAddress from your profile’s institution, and shows them on the review step.

Sequencing Information

Field	Required	Notes
Sequencing Technology	No	Hierarchical picker for sequencer family, device, kit and read configuration
Instrument Model	No	Free text, e.g. `NovaSeq 6000`, `MinION`
Library Strategy	No	WGS (Whole Genome Sequencing), WXS (Whole Exome Sequencing), RNA-Seq, Amplicon, Bisulfite-Seq, ChIP-Seq, ATAC-seq, Other
Library Source	No	Genomic DNA, Metagenomic, Transcriptomic, Metatranscriptomic, Synthetic, Viral RNA, Other
Library Selection	No	Random, PCR, Random PCR, RT-PCR, Size Fractionation, cDNA, PolyA, Oligo-dT, Unspecified

There is no standalone Platform field on the default form. Order.platform still exists in the database and accepts ILLUMINA, OXFORD_NANOPORE, PACBIO, ION_TORRENT or BGI, but on a default install the value is derived from your Sequencing Technology choice. Pipelines that need a platform (for example MAG’s short_reads_platform column) read it from that selection.

Sample Metadata (only with the MIxS module)

Appears when the form contains a visible mixs field and the admin has enabled at least one MIxS checklist. You pick one environment checklist and then choose which of its optional fields to collect. The choice is stored on the order as _mixsChecklist and _mixsFields inside customFields.

Samples

Always present. An editable table, one row per tube.

Column	Required	Notes
Sample ID	Auto	`S-{epoch-ms}-{5 random base36 chars}`, e.g. `S-1755262041412-K7QX2`. Editable, but must stay unique within the order.
Organism	Yes	Taxonomy autocomplete — see Organism & Taxonomy
Sample Title	Yes	Short descriptive title, used for ENA submission
Sample Alias	No	Optional unique short name

Extra columns appear for per-sample custom fields and for the MIxS fields you selected. Duplicate sample IDs are rejected before saving with Duplicate Sample ID detected: <id> (samples 3 and 7), and a blank one with Sample 4 is missing a Sample ID.

Facility Fields (facility admins only)

Only rendered when you are a facility admin and the form has admin-only fields. On a default install this step contains:

Field	Scope	Options
Internal QC Status	Order	Pending, In Review, Passed, Needs Follow-up
Internal Notes	Order	Free text
Sample QC Result	Per sample	Pending, Passed, Failed, Repeat Requested
Sample Notes	Per sample	Free text

Researchers never see these fields, and — unlike regular sample data — facility admins can keep editing them after the order leaves DRAFT.

Review and Submit

A read-only summary of your contact details, every order-level value grouped by section, the MIxS selection, and the sample table. Submitting creates the order in DRAFT.

Order numbers

Each order gets ORD-YYYYMMDD-XXXX, for example ORD-20260415-0001. The sequence restarts each day and is derived from the highest existing number with today’s prefix. If two people submit at the same instant and collide on the unique index, SeqDesk retries with a fresh number up to five times before returning Failed to create unique order number.

The number is assigned at creation and never changes. It is the identifier to quote in support tickets — the internal id in the URL is a cuid and is not meaningful to anyone else.

Draft mode

Orders start in DRAFT. While in draft:

every field can be edited, including sample data;
samples can be added, edited and deleted;
the order can be deleted outright by its owner;
no notification is sent to the facility;
sequencing runs, file discovery and uploads are all unavailable — those require SUBMITTED.

Submitting is a one-way door for sample data. POST /api/orders/[id]/samples rejects any regular sample edit on a non-draft order with Cannot modify samples after order submission. Get the sample table right before you submit.

Working in Excel

For anything beyond a handful of samples, use the spreadsheet round-trip. The sample table toolbar has two buttons:

Excel Template downloads sample_template_<order name>.xlsx containing one column per per-sample field, pre-filled with the rows currently in the table.
Upload Excel parses a filled-in .xlsx (or .xls) and opens the Import Excel Data dialog, which reports parsed rows, unmapped columns, errors and warnings before anything is applied.

The import replaces the sample table rather than merging into it. Both dialog buttons — Import Valid Only (n) and Import (n rows) — swap the whole table for the parsed rows. Download the template first so existing rows survive the round-trip.

Columns are matched by header name against the per-sample field definitions. After import, numberOfSamples is set to the new row count.

A separate Export CSV button on the order’s sample page produces samples_<order name>.csv — a one-way snapshot including system fields, checklist fields and custom fields. It cannot be re-imported.

Quick actions on the sample table

The Quick Actions menu (visible when the table has rows) offers:

Auto-generate sample aliases — overwrites every alias with Sample_1, Sample_2, … in table order. It does not skip rows that already have an alias, so do not use it after you have entered meaningful aliases by hand.
Copy organism to all samples — copies taxId and scientificName from the first row to every row. Only shown when there is more than one sample.

Custom fields

Fields added through the Form Builder can be:

Per-order — one value for the whole order, stored in Order.customFields as JSON;
Per-sample — a column in the sample table, stored in Sample.customFields as JSON;
Admin-only — visible only to facility admins, at either scope.

Available types are text, text area, dropdown, multi-select, checkbox, number, date, MIxS metadata, funding info, billing info, sequencing technology, organism and barcode. Two of them are scope-locked and the form builder will move them for you: organism and barcode are always per-sample; mixs, funding, billing and sequencing-tech are always per-order.

Troubleshooting

Symptom	Cause	Fix
`Duplicate Sample ID detected: …`	Two rows share a Sample ID, case-insensitively	Edit one of the two rows named in the message
`Sample 4 is missing a Sample ID`	A blank row was left in the table	Fill it in or delete the row
`Cannot modify samples after order submission`	The order left DRAFT	Ask a facility admin — regular sample data is frozen; only admin-only fields stay editable
`Cannot edit completed order`	You are the researcher and the order is COMPLETED	Order-level metadata is frozen at COMPLETED for researchers
`Failed to create unique order number`	Five consecutive collisions on `ORD-YYYYMMDD-XXXX`	Retry; if it persists, something is wrong with the `Order.orderNumber` unique index
Import dialog shows unmapped columns	Header text does not match any per-sample field label	Re-download the template and copy your data into it

Sequencing Order Lifecycle — what changes when you submit, and what completes an order.
Samples & Metadata — the sample record in detail.