Chain of custody
A Chain of Custody (CoC) is a project-scoped manifest that records the Samples you hand off to a laboratory, the analyses you request for them, and the sequence of physical custody handoffs from sampler to lab. It is the paper-trail document a lab expects with an incoming shipment, recreated in Erde so it lives alongside the rest of your project data. To look up the term later, see the glossary.
What a Chain of Custody holds
A CoC belongs to one Project and gathers four things:
- Header details — a unique
Code, the shipping company, the laboratory, shipping and tracking information, and a requested turnaround time. - Samples — the Samples on this shipment, each with a sequence number and a snapshot of its code, Matrix, and collection date.
- Analyses — the Methods you are requesting, named as they should read on the form.
- Transfers — each custody handoff, recording who relinquished the samples and when, and (once accepted) who received them and when.
Most header and sample fields are deliberately free-text snapshots: transcriptions of what is printed on the paper form, captured when you create the CoC and editable afterward. The Project Code, Laboratory Name, and per-sample Sample Matrix are allowed to differ from the live Project, Laboratory, and Sample records — they record what the form says, not a live lookup.
A Sample's Container Count is recorded as a single number per sample. Per-container records (tracking individual bottles or jars) are not part of V1.
How the sample link works
A Sample carries no reference back to its CoC. The link lives on the CoC side, in a join record that points at the real Sample. Because the Sample row holds no back-reference, one Sample can appear on many Chains of Custody — for example, when split portions of the same sample go to different labs.
Figure: how the sample link works — a Chain of Custody lists CoC Samples (each linked to a real Sample) and records custody Transfers. Analyses and their per-sample assignments are covered below.
The join record is the deletion guard, not a lifecycle coupling: while a Sample is listed on any CoC, deleting that Sample is blocked. Removing the Sample from the CoC clears the link without touching the Sample itself.
Analyses and assignments
A CoC lists the analyses you are requesting once, then maps which samples need which analyses. Each request to a sample is a separate assignment, so the same analysis can apply to many samples and each sample can carry many analyses. On the Analyses tab, an Assign Samples matrix (samples as rows, analyses as columns) lets you check the pairs that apply.
The printed form
Every CoC can produce a PDF for the shipment:
- Print COC renders the filled form — header, sample table, and an X in each analysis column a sample is assigned to — as
COC-{Code}.pdf. - Print Blank COC renders an empty form (ten blank sample rows) to complete by hand in the field, as
COC-Blank.pdf.
The paper form prints up to 15 analysis columns. Erde accepts more, but any beyond the 15th are footnoted as recorded electronically rather than printed.
Status values
A CoC moves through four statuses in order. Moving forward is silent; stepping backward, or editing a CoC that is already Closed, raises a non-blocking warning rather than blocking the change.
| Value | Meaning | Notes |
|---|---|---|
Draft | Being prepared | Default on a new CoC |
Submitted | Sent to the lab | — |
Received | Lab has received the samples | — |
Closed | Finalized | Edits warn but are still allowed |
How it fits together
| Concept | Relationship to a Chain of Custody |
|---|---|
| Project | Owns the CoC; every CoC belongs to exactly one Project |
| Sample | Listed via a CoC Sample link; one Sample can ride many CoCs |
| Lab Report | A Lab Report can reference its CoC; that reference blocks deleting the CoC |
| Laboratory | Optionally linked; the CoC also stores a free-text Laboratory Name snapshot, so it can name a lab that isn't a registered Laboratory |