Lab

What it does

Lab is Zhenus LIMS — the platform's laboratory information management system. It covers the test catalog, order accessioning, specimen tracking, result entry / validation / release, and quality-control runs.

Where to find it

• Catalog — /lab/catalog
• Accessioning — /lab/orders
• Specimens — /lab/specimens
• Results — /lab/results
• QC — /lab/qc
• Critical results — /lab/critical-results (lab-filtered shared acknowledgement queue)
• Patient results preview — /lab/patient-results?patientId=… (interim demo for the shared recent-results panel until the provider-portal BFF embeds it on the chart)

You need the matching view permission for each screen (lab.catalog.read, lab.order.read, lab.specimen.read, lab.result.read, lab.qc.read, lab.critical.read). Write actions need the corresponding .write permission. If a Lab entry is missing from your sidebar, you either lack the view permission or the lab module is not activated for your facility.

Test catalog

Opening Catalog shows three tabs: Tests, Panels, and Reference lists.

The catalog you see is three lists merged:

• entries your facility published,
• entries your organisation published,
• entries published by national health bodies in your country.

Two identically named rows are normal — use Published by to tell them apart. You can only retire entries your own organisation (or facility) published.

Register a specimen type or method

1. Open Reference lists.
2. Register specimen type or Register method — enter a short code, a display name, and optionally a description. Choose whether the entry is facility-local or organisation-wide.
3. The new row appears with its owner and scope. Tests pick from these lists; they are not free text.

Add a test

1. Open Tests and choose Add test.
2. Choose the test concept from the concept dictionary (search by name or code). Every test must be coded as a concept; LOINC mappings live on that concept, not as a lab-local code. The concept cannot be changed after the test is created.
3. Pick a specimen type (and optionally a method) from the reference lists. Register a new one from the dialog if the list is empty.
4. Optionally set units (UCUM), preparation instructions, and default turnaround hours.
5. Choose facility-local versus organisation-wide ownership, then Add test.

The row shows the concept name, specimen/method codes, unit code, and Published by.

Manage reference ranges

Use Manage reference ranges on a test row. Add one or more normal ranges by sex (Male, Female, or Any) and optional age band in days, with numeric low/high values and/or a text range. Result validation uses these ranges to flag abnormal values — a test with no ranges cannot flag anything.

Add a panel

1. Open Panels → Add panel.
2. Enter a display name and optionally a profile concept (e.g. a LOINC panel code). A facility-defined grouping with no concept is fine.
3. After create, use Manage members to add catalog tests in display order.

Retire a test, panel, or reference row

Use Retire … on the row and give a reason. You can only retire entries your own owner published. Entries from another organisation stay visible but are not editable here.

Search

The Tests and Panels tables search on the server (name / concept). Typing in the search box issues a paged request — it is not a client-side filter of a one-time download.

Accessioning desk

Accessioning (/lab/orders) is the facility desk for clinical LAB orders.

1. Optionally configure the accession number format (prefix, year, sequence width). If unset, the first accession creates a platform default.
2. Enter the clinical order id, patient id, and orderable concept id (optional encounter / provider / note / priority), then Accession order. The server mints the accession number and specimen tracking ids — you never type them. Repeating the same clinical order id returns the existing accession.
3. Use Look up by accession or open a row to see order lines and Print barcodes (accession and per-specimen payloads).

Specimen tracking

Specimens (/lab/specimens) follows collect → receive → aliquot → store.

1. Collect by tracking id using a tracking id printed at accessioning.
2. Open a specimen to Receive, Aliquot, Store (location required), or Reject (reason required). Rejection keeps the specimen record; results against a rejected specimen are refused.
3. The custody trail is append-only — events are never edited or deleted.

Result entry and validation

Results (/lab/results) is the validation queue.

1. Enter a result against an order line and specimen (numeric and/or text). Status starts at Entered — nothing auto-releases.
2. Advance Tech validate → Path validate → Release. Release publishes a clinical observation; abnormal flags come from the catalog reference ranges.
3. After release, Amend appends a new result that replaces the released one; the original is kept.

Quality control

QC (/lab/qc) records control-lot runs and charts Levey-Jennings trends.

1. Record a manual QC run — pick a catalog test, enter the control lot, expected mean/SD from the package insert, and the observed control value. The server derives the z-score; you never send one.
2. Filter the Levey-Jennings chart by test and control lot. Points outside ±2 SD are highlighted; the chart repeats every z-score as text below the line for accessibility.
3. Instrument-fed runs appear in the same list when an analyzer interface is configured for the deployment — manual entry still works with no analyzer.

Critical (panic) results

Critical results (/lab/critical-results) is a lab-filtered view of the shared acknowledgement queue used by every module that raises a critical finding. When a released result crosses a configured panic bound on a reference range, it appears here with source_module=lab and on the shared Notifications → Critical results queue.

1. Open Lab → Critical results to review unacknowledged panic values for your facility.
2. Acknowledge then Close on the shared loop — there is no lab-local escalation UI or second queue. Acknowledgement actions also require the notification critical-result write permission.
3. Configure panic bounds on reference ranges (catalog Manage reference ranges) — normal low/high ranges flag abnormality; panic bounds drive critical raise on release.

Recent lab results on the patient chart (M20-009 / FE-373)

Released lab results appear read-only on the patient summary (/patients/{id}/summary) and in the compact summary panel above clinical observation forms. The panel lists up to five recently released results with the test concept name, status, primary value, and release time — never bare concept ids. In-progress validation stays on Results (/lab/results).

Until the provider-portal BFF (M16) owns the aggregation, you can preview the same component at Patient results preview (/lab/patient-results?patientId=…). You need lab.result.read.

Automated end-to-end (FE-253)

The Playwright suite src/test/e2e-fullstack/lab-journey.spec.ts (FE-253, pairs backend M20-007) walks catalog → accession → specimen custody → result validate/release → QC → the lab-filtered critical queue on the full-stack harness. Run instructions live in src/test/e2e-fullstack/README.md. Panic raise through acknowledgement is asserted on the backend Milestone20LimsIntegrationTest; the FE gate proves every lab screen is reachable after release.

Troubleshooting

What you see	What it means
The Lab section is missing from the sidebar	You do not hold a lab view permission, or the lab module is not activated for your facility.
/lab/catalog (or orders / specimens / results / qc) shows a denied state	Same as above — the permission gates the route, not just the nav link.
Critical results missing from Lab	You lack lab.critical.read, or the lab module is not activated.
Released result crossing a panic bound never appears on Critical results	No panic bound configured on the reference range, or the shared notification critical-result API is unavailable.
Add test / Retire missing	You hold view but not lab.catalog.write.
Accession / collect / enter actions missing	You hold the matching .read but not .write permission.
"A live test with concept id … already exists for this owner"	That concept is already in your catalog for this owner. Search for it rather than creating a duplicate.
"This … is published by another owner and cannot be retired here"	The entry belongs to another organisation. Ask them, or publish your own version.
Specimen type / method dropdown empty	Register at least one on Reference lists before adding a test.
Result entry refused for a specimen	The specimen was rejected — redraw / collect a new specimen.
No raw concept UUID on the screen	Concept ids on this platform are numbers; rows show names via the concept dictionary.