Sequencing Order Lifecycle

Order.status is a plain string column with a default of DRAFT. The application only ever writes three values, and it validates transitions against the ordered list ["DRAFT", "SUBMITTED", "COMPLETED"]. There is no cancelled or rejected state — an order that should not proceed is deleted, or simply left in DRAFT.

The status is what gates almost every capability in the product, so it is worth understanding precisely rather than by feel.

Status flow

DRAFT ──researcher or admin──▶ SUBMITTED ──admin, or automatically──▶ COMPLETED
                                    ▲                                     │
                                    └──────── admin can move back ────────┘

Two asymmetries worth internalising:

• Researchers can make exactly one transition: DRAFT → SUBMITTED. Any other requested status returns 400 Invalid status transition.
• Facility admins are not restricted to forward moves. The “cannot move status backwards” guard in PUT /api/orders/[id] applies only to non-admins, so an admin can push a COMPLETED order back to SUBMITTED to reopen it. Every move writes a STATUS_CHANGE note, so the reversal is auditable.

DRAFT

The starting state for every order. The order is a work in progress and exists only for its creator and for facility admins.

• All order fields and all sample data can be edited.
• Samples can be added, edited and deleted.
• The owner can delete the whole order with no special permission.
• No email or in-app notification reaches the facility.
• Sequencing capabilities are all closed. Run plans, file discovery, read assignment, checksum computation and uploads all reject a DRAFT order with Sequencing data can only be managed on submitted or completed sequencing orders (or, for run plans, Sequencing run plans can only be managed on submitted or completed sequencing orders).
• Marking samples as sent is refused with Cannot mark samples as sent before order submission.

SUBMITTED

The researcher has finished preparing the order and handed it to the facility.

What changes immediately:

• Sample data freezes. POST /api/orders/[id]/samples returns 400 Cannot modify samples after order submission for any regular sample edit, by anyone. Organism, titles, aliases, MIxS values and non-admin custom fields are now read-only.
• Admin-only per-sample fields stay open. Facility admins can still write Sample QC Result and Sample Notes through the same endpoint using its facility-fields mode.
• Order-level metadata stays editable for the researcher, right up until the order is COMPLETED.
• The facility’s sequencing surface unlocks: run plans, discovery, manual association, uploads and checksums all become available to facility admins.
• Notifications go out. The researcher receives an order.submitted confirmation and every facility admin is notified that a new order arrived.
• A STATUS_CHANGE note is written automatically.
• If the admin has configured post-submission shipping instructions, they appear on the order page under Send Samples to Institutions.

The Sequencing Order Process panel

Once an order has samples, the researcher’s order page shows a three-step tracker. It is derived state — nothing about it is stored:

Step 2 carries a Mark sent button, visible to the owner or a facility admin once the order is submitted and no shipment note exists yet. Pressing it writes a single SAMPLES_SENT note; pressing it again does nothing because SeqDesk refuses to create a second one. When a researcher presses it, facility admins are notified; when an admin presses it, no notification is sent.

COMPLETED

The facility has finished and the data is available.

• Order-level metadata becomes read-only for the researcher — PUT /api/orders/[id] returns 400 Cannot edit completed order.
• Facility admins can still edit everything they could before, including admin-only per-sample fields.
• File association, uploads and run plans remain available, exactly as at SUBMITTED.
• Samples remain assignable to studies for downstream analysis.
• A STATUS_CHANGE note is written.

Automatic completion

This is the part most people miss. A submitted order completes itself.

After reads are assigned (assignOrderSequencingReads) or a sequencing upload finishes, SeqDesk runs a check: if the order is SUBMITTED, has at least one sample, and every sample has at least one Read with a non-null file1, the order is moved to COMPLETED and a status note is recorded with the content Automatically completed - all samples have sequencing files. An in-app notification tells the researcher that SeqDesk completed the order.

Consequences to plan for:

• A facility admin does not need to remember to complete anything. Associating the last sample’s R1 is what finishes the order.
• Because completion freezes the researcher’s ability to edit order metadata, associating files early will lock the researcher out of fields they may still have wanted to correct.
• Auto-completion never runs on a DRAFT or already-COMPLETED order, and never fires when a sample is missing file1 — a sample with only R2 does not count.

Releasing data to the researcher

Assigning a read file does not show it to the researcher. Sequencing delivery is a separate, explicit publication step controlled entirely by the facility, and recorded on the order as sequencingFilesPublishedAt and sequencingFilesPublishedById.

Until an admin publishes, GET /api/orders/[id] returns zero reads to a non-admin caller — the query is deliberately given an impossible filter. After publication, the researcher sees only reads that are active and classified cleaned; raw and unknown reads are never exposed. Customer-facing artifacts follow the same rule with visibility: "customer".

The control lives in the Delivery to user card on the order’s Sequencing Data page:

Publishing is refused with No cleaned reads or customer-facing reports are available to publish. when the delivery summary would contain nothing. A file counts only if it is a cleaned active read (or a customer-visible artifact with an allowed extension: .html, .htm, .pdf, .txt, .tsv, .csv, .json, .log) and the file actually exists on disk under the configured data base path. The card’s four indicators — Cleaned reads present, Missing files, Customer reports, Published state — tell you which of those conditions is failing before you press the button.

Status notes

Status notes are an append-only audit trail on the order. The application creates exactly two kinds:

Notes are listed newest-first on the order detail page, with the author’s name where one was recorded (auto-completion has no author).

Deleting an order

Deletion is destructive and cascades: samples, reads, sequencing runs, run-plan assignments, sequencing artifacts and uploads all go with the order. Before the delete, every sample in the order is unassigned from its study (studyId → null), so studies survive but lose those samples.

The permission is a site setting — allowDeleteSubmittedOrders in the admin extra settings — not a per-order option. Leave it off unless you are actively cleaning up test data.

Visibility and department sharing

By default a researcher sees only their own orders. Facility admins always see every order regardless of any setting.

When department sharing is enabled (departmentSharing under Admin → Settings → Extra Settings), a researcher who belongs to a department sees every order created by members of that department. A researcher with no department still sees only their own. GET /api/orders reports which rule applied in its sharingMode field: personal, department or all.

Troubleshooting

Next

• Sequencing Runs — the run plan that makes file matching reliable.
• Assigning Files to Samples — what actually creates the Read records that complete an order.