0.1.0 - ci-build

SENAITEFHIRImplementationGuide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Artifacts Summary

This page provides a list of the FHIR artifacts defined as part of this implementation guide.

Capability Statements

FHIR capability statements describing the SENAITE API surface.

SENAITE FHIR API Capability Statement

Describes the FHIR R5 capabilities of the SENAITE FHIR API when operating as the server (API provider). Covers the lab request and results workflow and the instrument integration workflow.

Request/Results Workflow — Operations

Custom operations defined for the lab request and results workflow.

Revoke a ServiceRequest

Revokes a ServiceRequest in SENAITE, transitioning its status to revoked and triggering the corresponding revocation workflow. Only callable on ServiceRequests in active status. The request body is optional — if omitted or empty, the operation proceeds without a reason.

Request/Results Workflow — Profiles

Profiles supporting the lab request and results workflow.

Senaite Service Request Bundle

A transaction Bundle used to submit a laboratory service request to SENAITE. The ServiceRequest is the backbone of the Bundle.

Patient, Practitioner and Organization entries are 0..1. Include an entry when the resource may not yet exist on the server — the server creates it and assigns a logical id, or matches an existing one if request.ifNoneExist is supplied. Omit the entry when the resource is already known, and reference it by logical id (e.g. Organization/{id}) from the ServiceRequest. Every request must still identify its Client via extension[SenaiteClient], whether by urn:uuid or logical id.

ServiceRequest and Specimen are always created and always present, and a Bundle carries exactly one of each: one request is one sample. An order spanning several sample types (tubes) is submitted as one Bundle per tube, each ServiceRequest carrying the same requisition. See multi-tube orders in lab-request-and-results.html.

Identifiers on create. Patient, Practitioner, Organization and Specimen each carry a paired internal/external identifier. The internal identifier (use = usual) is generated by SENAITE and must not appear on any entry in this Bundle — no-internal-id-on-create rejects it. The external identifier (use = secondary) is consumer-owned and may be supplied. The ServiceRequest carries no identifier; its only identifier is the optional requisition, which groups the Bundles of one multi-tube order. See identifiers.html#general-pattern and identifiers.html#sample-group-id.

Barcode on create. The Specimen's barcode label (SenaiteSpecimenBarcode) is generated by SENAITE and must not appear on the Specimen entry — no-barcode-on-create rejects it. It is returned on the Specimen entry of the SenaiteBundleResponse.

ifNoneExist. Where supplied, it must take the form identifier=<system>|<value>. Either identifier may be used as the key: the external identifier the consumer already owns, or the internal identifier SENAITE returned from an earlier order. The system is mandatory in both cases — the identifier search parameter matches on system and value and ignores Identifier.use, so a bare value would match across every consumer's namespace and across SENAITE's own internal one. Supplying the internal identifier as an ifNoneExist key is not the same as supplying it in the resource body, which remains prohibited.

SENAITE Service Request

This will be an incoming lab request. It relies on references to:

  • Specimen: to handle the related specimen details.
  • Subject: The patient
  • Organization: Determining from which client the request originated.
  • Requester: The practitioner who made the request.

This resource carries no identifier. ServiceRequest.identifier is prohibited (0..0) on both read and write. SENAITE holds no stored ServiceRequest object — a ServiceRequest is POST input within a SenaiteRequestBundle and thereafter a projection over the AnalysisRequest it created. Sample identity belongs to the Sample, and is carried on the resources that represent it: SenaiteSpecimen and SenaiteDiagnosticReport, which hold the internal Sample ID (#usual) and the consumer-owned Client Sample ID (#secondary). A consumer supplying its own reference for one sample puts it on the Specimen entry, not here. The ServiceRequest is addressed by the logical id returned in the transaction response — that is the id supplied to $revoke.

Requisition (Sample Group ID). ServiceRequest.requisition is the one identifier this resource may carry. It groups the ServiceRequests of a single order that is submitted as several SenaiteRequestBundle transactions — normally one per sample type (tube). Its system is fixed by this IG to the Sample Group ID namespace (https://fhir.senaite.org/NamingSystem/sample-group-id); the consumer chooses the value and supplies the same value on every ServiceRequest in the order. It is optional, is a label rather than a contract (the server cannot know that an order is complete), and is not required to be unique per sample. Because the system is shared, the value must be unique within the consumer, and the server scopes searches on it to the Client(s) the caller is authorised for. Each bundle still carries exactly one ServiceRequest and one Specimen. See Sample Group ID and Multi-tube orders.

See Identifiers.

SenaitePatient

Demographic details of the patient

SenaitePractitioner

The Practitioner that orders the test.

SenaiteOrganization

Used to specify the Organization who makes a SenaiteServiceRequest.

SenaiteSpecimen

This is the specimen to accompany the ServiceRequest

SENAITE Specimen Barcode

The barcode label for the specimen container, as a base64-encoded PDF or image. The barcode encodes the Sample ID by default, or the Client Sample ID where the deployment is configured to use it. Populated by SENAITE on every Specimen it returns; never accepted on create.

Senaite Bundle Response

The transaction-response Bundle returned by the server after successfully processing a SenaiteRequestBundle. One entry is returned per entry in the request, in the same order. Each entry carries the server-assigned fullUrl and a response status.

Specimen resource body. The Specimen entry additionally carries the full, server-populated SenaiteSpecimen resource in entry.resource — the only entry in this Bundle that does. This is how a consumer learns the SENAITE-assigned internal Sample ID (identifier[senaiteId]), which is not otherwise present anywhere in the response: entry.fullUrl / entry.response.location carry only the FHIR logical id, a separate value from the Sample ID business identifier used on printed barcodes and worklists. Returning the Specimen also lets a consumer immediately confirm the clientSampleId it supplied, if any, was preserved. No other entry (ServiceRequest, Patient, Practitioner, Organization) carries a resource body; a consumer needing one of those bodies still performs a read against the id returned in that entry.

Senaite Results Bundle

A searchset Bundle returned by the SENAITE FHIR API in response to a DiagnosticReport polling request. May contain one or more DiagnosticReports — one per completed Sample matched by the search criteria (typically _lastUpdated=gt&lt;since&gt;), plus any combined report that covers several Samples sharing a requisition.

Each DiagnosticReport is the backbone for its results. A per-sample report carries a basedOn reference to the originating ServiceRequest (absent for a Sample created inside SENAITE); a combined report carries one basedOn reference per ServiceRequest it covers. Both link their Observations via result.

Per-sample and combined reports coexist: the same Sample can appear in a per-sample report and in a combined report in one response. DiagnosticReport.basedOn having more than one entry marks a combined report. Consumers should ingest per-sample reports as the results and treat a combined report as a document.

Observations are returned as sibling entries via _include=Observation:result. Consumers can distinguish matched resources from included ones via entry.search.mode: DiagnosticReport entries carry mode = #match and Observation entries carry mode = #include.

Referenced resources already known to both systems (Patient, ServiceRequest, Practitioner, etc.) do not need to be included as entries. Their references within DiagnosticReport and Observation are plain relative references resolved out-of-band.

Bundle.type is searchset — this Bundle is always the direct response to a FHIR search interaction.

SenaiteDiagnosticReport

This is the results for the lab test requested by the ServiceRequest - as such it carries a basedOn link to the Service Request (or, for a combined report, to each of them). It may contain either the pdf file in presentedForm or the quantitative results as Observations in results.

Two kinds of report. A SenaiteDiagnosticReport is one of:

  • Per-sample report — the default, and the only kind until a combined report is published. It is a projection of one Sample: basedOn has at most one ServiceRequest (none when the Sample was created inside SENAITE rather than from a SenaiteRequestBundle), it carries the Sample ID and Client Sample ID identifiers, and its presentedForm is that Sample's PDF.
  • Combined report — optional. It is a projection of a multi-sample report published by the laboratory for the samples with a common ServiceRequest.requisition. basedOn lists every ServiceRequest it covers (more than one), result lists the Observations of all of them, presentedForm is the single combined PDF, and code is the default panel code 30954-2 because several panels are covered. It carries one Sample ID for each Sample it covers, a Client Sample ID for each Sample that has one, and the Sample Group ID (the requisition value) as identifiers. These lists are unordered and carry no pairing; to pair a Client Sample ID with its Sample ID read the referenced Specimens or use the per-sample report.

basedOn.count() &gt; 1 is the marker for a combined report. A combined report over a single Sample is not a combined report: it is a per-sample report.

Specimen. specimen references the Specimen of each Sample the report covers: exactly one on a per-sample report, and one for each covered Sample on a combined report (as many as basedOn). It makes a report self-describing without matching identifiers or dereferencing ServiceRequests. Each referenced Specimen carries its own Sample ID and Client Sample ID, so reading the Specimens is how the identifiers on a combined report are paired. The list is unordered, like the other lists. _include=DiagnosticReport:specimen is not supported in this version: read each Specimen by id.

Coexistence. Both kinds can exist for the same Sample at the same time. Publishing or republishing a combined report never removes or replaces a per-sample report, so a search can return both: searching by a Sample ID returns that Sample's per-sample report and any combined report covering it. Consumers should ingest per-sample reports as the results and treat a combined report as a document. Each Observation's own basedOn identifies the ServiceRequest it belongs to, so the Observations of a combined report can always be split by sample.

Combined report lifecycle. A combined report is only created once every Sample it covers is final, so its status is final at creation. Its membership (basedOn) is fixed when it is published; it is not re-evaluated if more samples later join the requisition. A correction or a late sample is delivered as a new combined report, and the superseded one is marked entered-in-error. The combined PDF is a snapshot: after a correction to a constituent Sample it can disagree with the live Observations until it is republished. A combined report never spans different Clients or Patients.

See Combined reports and Identifiers.

Polling behaviour and _summary=true

When consumers poll for new results via the search endpoint, _summary=true is required. Under this mode the FHIR server returns only the summary elements of the DiagnosticReport as defined by the base specification. Critically, presentedForm.data (the base64-encoded PDF payload) is not a summary element and will be absent from search results — only metadata such as presentedForm.contentType and presentedForm.title is returned.

To retrieve the full PDF, consumers must perform a direct read of the specific DiagnosticReport by id:

GET {fhir_api_root}/DiagnosticReport/{id}

This two-step pattern — poll with _summary=true to discover new reports, then fetch by id for the PDF — is intentional and keeps polling responses lightweight.

SenaiteObservation

A single result produced by an instrument or a lab analyst, pushed to SENAITE or returned within a SenaiteResultsBundle.

  • code (LOINC preferred) identifies the specific analyte or observation, matched against ServiceRequest.orderDetail codes.
  • basedOn links the result back to the originating ServiceRequest.
  • performer optionally identifies the analyst or technician who recorded the result.
  • device optionally identifies the instrument that produced the result.
  • referenceRange optionally carries the normal range for the analyte as configured in SENAITE. Only meaningful for numeric (valueQuantity) results, and only ever populated by SENAITE on outbound (GET) Observations — never expected, and not meaningful, on an Observation POSTed by an instrument.
Senaite ServiceRequest Revoked

The ServiceRequest resource returned by the server in the 200 OK response body after a successful $revoke operation. Identical to SenaiteServiceRequest but with status fixed to revoked, meta.versionId and meta.lastUpdated required to confirm the update was applied, and note optionally populated with the plain-text reason supplied to the $revoke operation.

Senaite ServiceRequest Revocation Error

The OperationOutcome returned with a 409 Conflict when a ServiceRequest cannot be revoked, for example because results have already been published in SENAITE.

SENAITE Client

The Organisation (Client) that submits the laboratory request and to whom results will be reported. This replaces the need for an Encounter reference to convey organisational origin in a LIMS workflow.

EstimatedDateBirth

If the date of birth is unknown to a high degree of precision

Request/Results Workflow — Examples

Example instances for the lab request and results workflow.

[Request Bundle] Liver Panel Transaction Bundle

Transaction bundle for a liver panel order, submitted by a consumer that has not previously ordered for this patient, clinician or client.

Entry fullUrls are urn:uuid placeholders with no persistence — they exist only so entries can reference each other. No entry carries a Resource.id; the server assigns all logical ids.

Patient, Practitioner and Organization entries carry request.ifNoneExist so a repeat submission matches the existing resource (200 OK) instead of creating a duplicate. Each key is identifier=<system>|<value> against the consumer's own external identifier; the system is mandatory. Specimen and ServiceRequest are always created.

No entry carries an internal identifier (use = usual) — SENAITE generates those on creation and returns them on subsequent reads. The ServiceRequest carries no identifier; its only identifier is the requisition, which groups this serum tube with the EDTA (CBC) tube drawn at the same time. That second tube is its own transaction — see the multi-tube CBC example.

The submitting Client is identified via extension[SenaiteClient] on the ServiceRequest, pointing at the Organization entry's urn:uuid.

[Request Bundle] Repeat Liver Panel — Existing Patient and Client

A repeat order for a patient, clinician and client that already exist in SENAITE. Only Specimen and ServiceRequest are submitted as entries; the other three are referenced by the logical ids returned in the response to the consumer's first order.

Reference form follows entry presence, not resource type: targets with an entry in this bundle use that entry's urn:uuid, targets already on the server use ResourceType/{id}. A urn:uuid reference with no matching entry resolves to nothing and will fail.

No ifNoneExist appears here — there is nothing to match, since neither a Specimen nor a ServiceRequest is ever reused.

[Request Bundle] Multi-tube Order — CBC (EDTA) Tube

The second transaction of a two-tube order. The first (serum, hepatic function panel) is the liver panel example; both ServiceRequests carry requisition (Sample Group ID) https://fhir.senaite.org/NamingSystem/sample-group-id|ORD-20260408-0173.

Each tube is its own transaction, so a failure in one does not roll back the other — the transactions are atomic individually, not across tubes. A failed tube creates nothing and is resent on its own. There is no ServiceRequest lookup, so after a timeout a resend can create a duplicate Sample; that is visible in SENAITE and can be deleted.

Patient, Practitioner and Organization were created by the first transaction and are referenced here by the logical ids in its response, so only Specimen and ServiceRequest appear as entries. The requisition value is a consumer-owned grouping label: SENAITE does not require it to be unique per sample and does not know whether the order is complete.

[Request Bundle] Liver Panel Transaction Response

Transaction response for the liver panel order. One entry per request entry, in the same order.

All five resources were created (201), since this consumer had not previously ordered for this patient, clinician or client. Had the ifNoneExist queries on entries 0–2 matched existing resources, those entries would return 200 OK with the location of the matched resource and no new resource would be created.

The logical ids assigned here are unrelated to the urn:uuid placeholders in the request bundle.

The Specimen entry (entry[3]) additionally carries the full created SenaiteSpecimen in entry.resource — the only entry in this Bundle that does. This is how the consumer reads the SENAITE-assigned internal Sample ID and confirms its own Client Sample ID was preserved, without a follow-up GET.

[Request Bundle] Repeat Liver Panel Transaction Response

Transaction response for the repeat liver panel order. One entry per request entry, in the same order.

Both resources were created (201). The Patient, Practitioner and Organization referenced by the ServiceRequest were resolved from their literal ResourceType/{id} references and are not reported — a transaction-response describes only what the request asked the server to do, and nothing was asked of those three.

entry[0] additionally carries the created Specimen's resource body, as every Specimen entry does, so the consumer reads the new Sample ID (distinct from the previous draw's) without a follow-up GET.

[Request Bundle] Multi-tube Order — CBC (EDTA) Tube Response

Transaction response for the second tube of a multi-tube order. One entry per request entry, in the same order.

The response does not mention the requisition: it is supplied on the ServiceRequest. Each tube later produces its own per-sample DiagnosticReport; if the laboratory publishes a combined report for the order, that report lists the ServiceRequests it covers in basedOn and carries the Sample Group ID and one Sample ID per covered Sample.

entry[0] carries the created Specimen's resource body, as every Specimen entry does. Its Sample ID (SAMP-2026-0408-002) is distinct from the serum tube's (SAMP-2026-0408-001); the two tubes are two Samples that share only the requisition.

[OperationOutcome] Unknown LOINC Panel Code

OperationOutcome returned when a ServiceRequest references an unknown LOINC panel code, causing transaction rollback.

[OperationOutcome] Sample Group ID Used for a Different Patient

OperationOutcome returned with 422 Unprocessable Entity when the second request of a multi-sample order names a different Patient from the one already recorded for the same Sample Group ID. The Bundle is rolled back and nothing is created. expression points at the offending ServiceRequest.subject within the submitted Bundle. The existing Patient is not identified in the response.

[OperationOutcome] Sample Group ID Used for a Different Client

OperationOutcome returned with 422 Unprocessable Entity when the second request of a multi-sample order names a different Client (the SenaiteClient Organization) from the one already recorded for the same Sample Group ID. The Bundle is rolled back and nothing is created. expression points at the offending client reference within the submitted Bundle. The existing Client is not identified in the response.

[Results Bundle] Cardiac Enzymes Results

Results Bundle for a Cardiac Enzymes panel returned to the consumer following a polling request:

GET {fhir_api_root}/DiagnosticReport ?_lastUpdated=gt2026-05-28T00:00:00Z &_summary=true &_include=Observation:result

presentedForm.data is absent because this Bundle reflects a _summary=true response. To retrieve the full PDF, fetch the DiagnosticReport directly:

GET {fhir_api_root}/DiagnosticReport/d9246225-950f-4e7f-9c7d-4ff9d053e151

[Results Bundle] Cross Match Results

Results Bundle for a Cross Match order returned to the consumer following a polling request:

GET {fhir_api_root}/DiagnosticReport ?_lastUpdated=gt2026-05-30T00:00:00Z &_summary=true &_include=Observation:result

presentedForm.data is absent because this Bundle reflects a _summary=true response. To retrieve the full PDF, fetch the DiagnosticReport directly:

GET {fhir_api_root}/DiagnosticReport/4155dcf1-10b3-4f69-a63f-d19f608501da

[Parameters] Revoke Liver Panel Request — With Reason

Parameters body for revoking a liver panel ServiceRequest, supplying an optional plain-text reason. The server persists the reason into ServiceRequest.note[0].text on the updated resource.

[ServiceRequest] Revoke Liver Panel — Success Response (200 OK)

The ServiceRequest returned by SENAITE after a successful $revoke operation. Identical to the original ServiceRequest (id: 2d6bb491-6b87-4558-a07f-2d181831e298) but with status set to revoked, versionId incremented to 2, and the supplied reason persisted in note[0].text.

[OperationOutcome] Revoke Liver Panel — Conflict (409)

OperationOutcome returned when a ServiceRequest cannot be revoked because results have already been published in SENAITE.

[OperationOutcome] Revoke Liver Panel — Not Found (404)

OperationOutcome returned when no ServiceRequest exists with the supplied id.

[OperationOutcome] Revoke Liver Panel — Invalid Status (422)

OperationOutcome returned when the $revoke operation is called on a ServiceRequest whose current status does not permit revocation, for example completed or already revoked.

[ServiceRequest] CBC

ServiceRequest for a Full Blood Count (CBC) panel. Demonstrates all permitted ServiceRequest properties: SenaiteClient extension, category with text, code, orderDetail for each analyte, priority, note, subject, requester, and specimen. ServiceRequest.identifier is prohibited on this profile: sample identity is carried on the referenced Specimen — see Identifiers. The one identifier shown is the optional requisition, which this request shares with the ServiceRequest for the other tube of the same order (the CBC and the urinalysis) — see Sample Group ID.

[Specimen] Venous Blood (Collected)

Specimen representing a collected venous blood specimen used for CBC testing. Demonstrates the paired identifiers: the SENAITE-assigned sample ID (shared with DiagnosticReport) and the optional client-supplied sample ID.

[DiagnosticReport] CBC (PDF)

Per-sample DiagnosticReport for a Full Blood Count (CBC) panel with references to component Observations and an attached PDF. Based on one ServiceRequest, so it is not a combined report. It carries the Sample ID and Client Sample ID (identical to those on the Specimen it was created from) and the Sample Group ID (requisition value) shared with the urinalysis tube of the same order. A combined report covering both tubes also exists — see the combined example.

[Observation] Hemoglobin

Hemoglobin measurement in blood. Demonstrates all permitted Observation properties.

[Observation] Red Blood Cells

Red blood cell count in blood. Demonstrates all permitted Observation properties.

[Observation] White Blood Cells

White blood cell count in blood. Demonstrates all permitted Observation properties.

[Observation] Platelets

Platelet count in blood. Demonstrates all permitted Observation properties.

[ServiceRequest] Urinalysis

ServiceRequest for a urinalysis panel. Demonstrates all permitted ServiceRequest properties including priority and a note. ServiceRequest.identifier is prohibited on this profile: sample identity is carried on the referenced Specimen — see Identifiers. The one identifier shown is the optional requisition, which this request shares with the ServiceRequest for the other tube of the same order (the CBC and the urinalysis) — see Sample Group ID.

[Specimen] Urine (Collected)

Specimen representing a urine specimen collected at the specified date/time. Demonstrates the paired identifiers: the SENAITE-assigned sample ID (shared with DiagnosticReport) and the optional client-supplied sample ID.

[DiagnosticReport] Urinalysis Report (PDF)

Per-sample DiagnosticReport for a urinalysis panel represented as a PDF attached in presentedForm. Based on the urinalysis ServiceRequest (its own, distinct from the CBC ServiceRequest), and carrying the same Sample Group ID as the CBC report.

[DiagnosticReport] Combined CBC and Urinalysis (PDF)

Combined DiagnosticReport for one order's two tubes. It is marked as combined by having more than one basedOn — here one for each ServiceRequest it covers. It carries one Sample ID for each Sample it covers (each matching the Specimen of that Sample, so a consumer can find the report by any of them), and the Sample Group ID (the requisition value), plus the Client Sample ID of each Sample that has one. These lists are unordered and carry no pairing: here the Sample IDs and Client Sample IDs happen to be listed in the same order, but a consumer must not rely on that — to pair them, read the two referenced Specimens (each carries its own Sample ID and Client Sample ID) or use the per-sample reports. specimen references the Specimen of each covered Sample. code is the default panel code 30954-2 because more than one panel is covered, and result lists the Observations of the covered ServiceRequests — here the four CBC Observations, since the urinalysis is reported only as a PDF. Each Observation's own basedOn identifies the ServiceRequest it belongs to, so the list can be split by sample. presentedForm is the single combined PDF.

Status is final: a combined report is only created once every Sample it covers is final. Its membership is fixed at publication.

[Patient] Example Jane Doe (Estimated BirthDate)

Patient resource for Jane Doe with an estimated birth date indicated by the EstimatedDateBirth extension. Demonstrates all permitted Patient properties.

[Patient] Example Alex Miller

Patient resource for Alex Miller demonstrating all permitted Patient properties, including telecom, address, marital status, and a deceased date.

[Practitioner] John Smith

Practitioner resource for John Smith demonstrating all permitted Practitioner properties: both identifier slices, a fully-populated name, telecom, address, gender, and birthDate.

[Practitioner] Kim Nguyen

Practitioner resource for Kim Nguyen demonstrating all permitted Practitioner properties.

[Organization] Microbiology Laboratory

Organization resource representing the Microbiology laboratory. Demonstrates all permitted Organization properties: both identifiers, name, partOf, and a fully-populated contact block.

[DiagnosticReport] Cardiac Enzymes

Cardiac Enzymes DiagnosticReport. presentedForm.data absent — _summary=true response. Fetch by id to retrieve full PDF.

[Observation] AST
[Observation] Creatine Kinase (CK)
[Observation] Troponin I
[Observation] Creatine Kinase MB (CKMB)
[Observation] Creatine Kinase MB Percent (CKMB%)
[Observation] Lactate Dehydrogenase (LDH)
[diagnosticReport][1] Cross Match

Cross Match DiagnosticReport. presentedForm metadata is present but data is absent — this reflects a _summary=true response. Fetch by id to retrieve the full PDF.

[Observation] Reason for Transfusion
[Observation] Blood Component
[Observation] Required When
[Observation] Donor ID — Unit 1
[Observation] Donor ID — Unit 2
[Observation] Patient's Blood Group
[Observation] Donor's Blood Group
[Observation] Donor Compatibility
[Observation] Blood Product
[Observation] Issued By
[Observation] Date and Time Unit Issued

Instrument Workflow — Profiles

Profiles supporting the instrument integration workflow.

Senaite Device

Represents a laboratory instrument that produces results in SENAITE. Used to identify the source instrument of an Observation, supporting multi-device labs and enabling per-instrument QC and audit trails. If SENAITE does not recognise the device identifier it will be created using the supplied fields.

Senaite Instrument ServiceRequest

A single analyte-level ServiceRequest generated by SENAITE and scoped to a specific laboratory instrument (Device). Instrument Middleware polls for these resources to build its worklist and routes each to the assigned instrument.

The instrument loop is self-contained at the analyte level: the middleware receives analyte + specimen + device, transmits to the instrument, and the instrument returns a result which the middleware posts as a SenaiteObservation with basedOn referencing this resource. Panel context is not required at any point in this loop.

basedOn is optional: present when the work originated from an external SenaiteServiceRequest, absent when the AnalysisRequest was created directly within SENAITE. The senaiteId identifier is the authoritative traceability link to the underlying SENAITE AnalysisRequest in all cases.

Senaite Worksheet Task

A SENAITE worksheet — a batch of analyses collected for execution on a single laboratory instrument, optionally including internal QC checks (not modelled in this iteration; see design notes). Worksheets are a complementary grouping construct: instrument work can and does also arrive outside of any worksheet, as described in the Instrument Integration workflow.

A worksheet only becomes a Task once it has at least one analysis attached — a closed SENAITE worksheet (no analyses) is never represented in FHIR.

Worksheet Capacity

The total number of analysis slots available on this worksheet, as defined by its SENAITE worksheet template.

Instrument Workflow — Examples

Example instances for the instrument integration workflow.

[Device] Sysmex XN-1000

Haematology analyser used for full blood count panels. Demonstrates all permitted Device properties.

[Device] Roche Cobas c502

Chemistry analyser used for liver panel and general biochemistry panels. Demonstrates all permitted Device properties.

[Instrument SR] Haemoglobin — Sysmex XN-1000

Test-level instrument ServiceRequest for Haemoglobin (LOINC 718-7), derived from the CBC panel ServiceRequest (LOINC 57021-8) and assigned to the Sysmex XN-1000 haematology analyser. Demonstrates all SenaiteInstrumentServiceRequest properties: senaiteId identifier, basedOn referencing the parent SenaiteServiceRequest, filler-order intent, single analyte code, 1..1 performer referencing a SenaiteDevice, subject, specimen, and note.

[Instrument SR] White Blood Cells — Sysmex XN-1000

Test-level instrument ServiceRequest for White Blood Cells (LOINC 777-3), part of the CBC panel assigned to the Sysmex XN-1000. One of four analytes on the Haematology Worksheet example.

[Instrument SR] Platelets — Sysmex XN-1000

Test-level instrument ServiceRequest for Platelets (LOINC 4544-3), part of the CBC panel assigned to the Sysmex XN-1000. One of four analytes on the Haematology Worksheet example.

[Instrument SR] Red Blood Cells — Sysmex XN-1000

Test-level instrument ServiceRequest for Red Blood Cells (LOINC 789-8), part of the CBC panel assigned to the Sysmex XN-1000. One of four analytes on the Haematology Worksheet example.

[Instrument SR] ALT — Roche Cobas c502

Test-level instrument ServiceRequest for Alanine Aminotransferase / ALT (LOINC 1742-6), derived from the Liver Panel ServiceRequest and assigned to the Roche Cobas c502 chemistry analyser. Demonstrates all SenaiteInstrumentServiceRequest properties: senaiteId identifier, basedOn referencing the parent SenaiteServiceRequest, filler-order intent, single analyte code, 1..1 performer referencing a SenaiteDevice, subject, specimen, and note.

[Instrument SR] AST — Roche Cobas c502

Test-level instrument ServiceRequest for Aspartate Aminotransferase / AST (LOINC 1920-8), derived from the Liver Panel ServiceRequest and assigned to the Roche Cobas c502. Shown with status completed, alongside ALT, on the Liver Panel Worksheet example awaiting verification.

[Observation] Hemoglobin (instrument)

Hemoglobin result pushed by the Sysmex XN-1000 for the CBC ServiceRequest.

[Observation] Red Blood Cells (instrument)

Red blood cell count pushed by the Sysmex XN-1000 for the CBC ServiceRequest.

[Observation] White Blood Cells (instrument)

White blood cell count pushed by the Sysmex XN-1000 for the CBC ServiceRequest.

[Observation] Platelets (instrument)

Platelet count pushed by the Sysmex XN-1000 for the CBC ServiceRequest.

[Observation] ALT (instrument)

Alanine aminotransferase result pushed by the Roche Cobas c502 for the liver panel ServiceRequest.

[Observation] AST (instrument)

Aspartate aminotransferase result pushed by the Roche Cobas c502 for the liver panel ServiceRequest.

[Observation] ALP (instrument)

Alkaline phosphatase result pushed by the Roche Cobas c502 for the liver panel ServiceRequest.

[Observation] Total Bilirubin (instrument)

Total bilirubin result pushed by the Roche Cobas c502 for the liver panel ServiceRequest.

[Observation] Albumin (instrument)

Albumin result pushed by the Roche Cobas c502 for the liver panel ServiceRequest.

[Worksheet] Haematology Worksheet — Sysmex XN-1000 (ready)

A haematology worksheet scoped to the Sysmex XN-1000, collecting the four CBC analytes (Haemoglobin, White Blood Cells, Platelets, Red Blood Cells) for a single specimen. Status ready corresponds to SENAITE's ready state — the worksheet's composition is frozen (no further analyses can be added) and it is safe for the owning instrument/middleware to claim and act on. This is the state consumers should poll for. Demonstrates capacity, the requested performer (instrument), and a multi-item input list.

[Worksheet] Liver Panel Worksheet — Roche Cobas c502 (to_be_verified)

A liver panel worksheet scoped to the Roche Cobas c502, collecting ALT and AST for a single specimen. Status on-hold corresponds to SENAITE's to_be_verified state — the instrument has returned results and the worksheet's work is paused, awaiting a verifier. AST has already completed; ALT remains active pending final confirmation, illustrating that worksheet-level state does not require every individual analysis to have reached the same status.

Terminology

Code systems defined by this IG.

SENAITE Analysis Keyword

CodeSystem defining SENAITE Analysis Keywords — short mnemonic codes used internally by SENAITE and its ecosystem to identify test types.

Keywords are sourced from the SENAITE Analysis Registry and provided as a convenience coding in SenaiteInstrumentServiceRequest and other SENAITE FHIR profiles for compatibility with SENAITE-native systems. FHIR consumers should rely on LOINC codes for semantic interoperability but may use keywords for display, caching, or SENAITE-specific routing.

This CodeSystem represents all active keywords from a SENAITE laboratory configuration and includes tests across hematology, biochemistry, serology, and urinalysis disciplines.

Identifier Namespaces

NamingSystem resources defining the identifier namespaces used in SENAITE integrations.

SENAITE Sample Identifier Namespace

Defines the identifier namespace for the Sample ID — the internal SENAITE Object ID generated when a Sample is created, whether that creation was triggered by a POSTed SenaiteRequestBundle or performed directly within the SENAITE web application. It must not be supplied by a client on POST. Used as the system value for the senaiteId identifier slice on SenaiteSpecimen and SenaiteDiagnosticReport, where it holds the same value, allowing the two to be correlated without traversing references. Fixed by this IG and not deployment-configurable, precisely because that correlation depends on both resources using the same system.

SENAITE Client Sample Identifier Namespace

Defines the identifier namespace for the Client Sample ID — the external, consumer-owned business identifier for a SENAITE Sample. It is assigned outside SENAITE, either supplied on POST on the Specimen entry of a SenaiteRequestBundle or entered against the Sample by laboratory staff in the web application, and is preserved as-is by SENAITE. Where the deployment is configured to do so, the value is encoded in the specimen container barcode in place of the default Sample ID. Carried as identifier[clientSampleId] on both SenaiteSpecimen and SenaiteDiagnosticReport — named for the SENAITE field rather than the generic pattern — where it holds the same value. Fixed by this IG rather than deployment-configurable, unlike the Patient, Practitioner and Organization external ID namespaces.

SENAITE Sample Group Identifier Namespace

Defines the identifier namespace for the Sample Group ID — the consumer-owned identifier shared by the requests of one order that is submitted as several SenaiteRequestBundle transactions, normally one per sample type (tube). Carried as SenaiteServiceRequest.requisition and as the sampleGroupId identifier on a combined SenaiteDiagnosticReport (not on a per-sample report). It is a grouping label: it is not required to be unique per Sample, and SENAITE cannot know whether the order is complete. Fixed by this IG rather than deployment-configurable, so values must be unique within the consumer that supplies them, and searches on it are scoped by the server to the Client(s) the caller is authorised for.

SENAITE Analysis Identifier Namespace

Defines the identifier namespace for the Analysis ID — identifying a single analysis, being one analyte measured on one sample, corresponding to an Analysis object within a SENAITE Sample. Assigned by SENAITE. Used as the system value for the senaiteId identifier slice on SenaiteInstrumentServiceRequest. Distinct from the Sample ID namespace, which identifies the Sample as a whole; values here are conventionally derived from the parent Sample ID but that derivation must not be parsed by consumers.

SENAITE Worksheet Identifier Namespace

Defines the identifier namespace for SENAITE-assigned worksheet identifiers. A worksheet groups a batch of analyses for processing within the laboratory. Assigned by SENAITE and must not be supplied by a client. Used as the system value for the senaiteId identifier slice on SenaiteWorksheetTask.

SENAITE Patient Internal Identifier Namespace

Default namespace for the internal SENAITE Patient ID — the human-readable identifier generated by SENAITE when a Patient is created. Carried as identifier[senaiteId] (use = #usual) on SenaitePatient. It must not be supplied by a client on an external create, but once assigned it may be used to identify the Patient on reads, updates and in Bundle.entry.request.ifNoneExist. A deployment may substitute its own URI for this namespace; this URI is the default where it has not.

SENAITE Patient MRN Namespace

Default namespace for the external Patient ID — the consumer-owned business identifier for a patient, being the Medical Record Number. Carried as identifier[mrn] (use = #secondary) on SenaitePatient and may be supplied on create. Both the slice and this namespace URI are named for the MRN field in SENAITE rather than for the generic pattern. A consumer will normally supply its own registry URI here, agreed at integration time; this URI is the default for deployments and consumers that have none. A system is mandatory either way, because request.ifNoneExist and the identifier search parameter match on system and value and ignore Identifier.use. Note that this default is a shared namespace: it must not be relied on where more than one consumer submits to the same SENAITE instance, since two consumers using the same MRN value would then match each other.

SENAITE Practitioner Internal Identifier Namespace

Default namespace for the internal SENAITE Practitioner ID — the human-readable identifier generated by SENAITE when a Practitioner is created. Carried as identifier[senaiteId] (use = #usual) on SenaitePractitioner. It must not be supplied by a client on an external create, but once assigned it may be used to identify the Practitioner on reads, updates and in Bundle.entry.request.ifNoneExist. A deployment may substitute its own URI for this namespace; this URI is the default where it has not.

SENAITE Practitioner External Identifier Namespace

Default namespace for the external Practitioner ID — the consumer-owned business identifier for a practitioner, for example a national provider number or hospital staff ID. Carried as identifier[externalId] (use = #secondary) on SenaitePractitioner and may be supplied on create. A consumer will normally supply its own provider registry URI here, agreed at integration time; this URI is the default for deployments and consumers that have none.

SENAITE Device Identifier Namespace

Defines the identifier namespace for laboratory instrument identifiers in SENAITE integrations. Typically corresponds to the asset register number assigned by the laboratory.

SENAITE Organization Internal Identifier Namespace

Default namespace for the internal SENAITE Client ID — the human-readable identifier generated by SENAITE when a Client Organisation is created. Carried as identifier[senaiteId] (use = #usual) on SenaiteOrganization. It must not be supplied by a client on an external create, but once assigned it may be used to identify the Organization on reads, updates and in Bundle.entry.request.ifNoneExist. A deployment may substitute its own URI for this namespace; this URI is the default where it has not.

SENAITE Organization External Identifier Namespace

Default namespace for the external Organization ID — the consumer-owned business identifier for a client organisation, for example a national organisation ID or an internal client code. Carried as identifier[externalId] (use = #secondary) on SenaiteOrganization and may be supplied on create. A consumer will normally supply its own organisation registry URI here, agreed at integration time; this URI is the default for deployments and consumers that have none.