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

Lab Request and Results

Lab Request and Results

Actors:

  • Provider: SENAITE will function as the API provider.
  • External Consumer or simply Consumer: Can be an EHR directly or via a middleware layer. Could also be another consumer too.

This is what most people would consider the primary workflow in a LIMS integration: posting lab requests to SENAITE (the Provider) and making results available to an EHR (the External Consumer) either directly or via a middleware layer.

This workflow handles the following actions:

  1. Order Lab test: A new lab test has been ordered in the consumer and its details need to be shared with SENAITE for processing. This will include details about the sample/specimen along with test information like profiles/panels and tests.
  2. Revoke Existing Order: When lab test that has been ordered needs to be revoked. Please see the valid state transitions to see when it is possible to revoke and how they will transition.
  3. Fetch Results: Once processing a sample is complete, results need to be made available to the consumer. Due to complexities around structuring the vast array of possible test results across multiple categories, this report can be a PDF as published from SENAITE. Additionally, the quantitative results can be represented in a structured form, including reference ranges made available for parsing by the external software.

Artefacts for Request/Results Workflow

See:

  • ​Profiles: these define the structure of particular resources as they vary from the base type.
  • ​Instances or Examples: these are examples of each of the profiles above. Available in JSON or XML.

Sequence Diagram & Explanation

Example workflow of request/results exchange

The diagram describes a request-in, poll-for-results integration pattern, where the consumer pushes a lab order, waits for the lab to process it, and then retrieves results either as structured FHIR data or as a PDF report.

  1. ​Pushing the request: The workflow begins with the External Consumer (e.g. a hospital system or ordering application) POSTing a FHIR Transaction Bundle to the SENAITE FHIR API. The Bundle carries exactly one ServiceRequest and one Specimen — one request is one sample — which are created for every request, and may carry Patient, Practitioner and Organization (Client) entries where those resources may not yet exist in SENAITE. The submitting Client Organisation is identified directly on the ServiceRequest via the SenaiteClient extension — unlike previous SENAITE IGs no Encounter is required. For an example Request Bundle see here. An order that spans several sample types (tubes) is submitted as one Bundle per tube — see Multi-tube orders.

    Note that Resource.id must be absent from every entry, and that references between entries use urn:uuid placeholders rather than ResourceType/{id} paths — see Identifying Resources in a Request Bundle below. Please also see Panel and orderDetail Behaviour on the relationship between panels and individual tests.

  2. Internal processing: Once received, the FHIR API processes the Bundle and instructs the SENAITE Application to generate a new Sample — translating the FHIR resources into SENAITE's internal data model. SENAITE generates the Sample ID at this point; it is not present anywhere in the submitted Bundle and must not be supplied on POST. The optional Client Sample ID, if the consumer included one on the Specimen entry, is preserved as-is — the Specimen is the only place it can be supplied, since the ServiceRequest carries no identifier. Both identifiers appear on the DiagnosticReport retrieved in step 5. See Identifiers.

  3. Acknowledgement: The FHIR API returns a transaction-response Bundle — one entry per request entry, in the same order, which is how the consumer matches them up. Each entry carries the resource's absolute URL in fullUrl and its path in response.location. SENAITE returns no resource bodies, with one exception: the Specimen entry, which always carries the full created Specimen in entry.resource. This is the only place the SENAITE-assigned internal Sample ID is available without a follow-up read — it does not appear in fullUrl/response.location, which carry only the FHIR logical id — and it lets the consumer confirm the Client Sample ID it supplied, if any, was preserved. Prefer: return=representation has no effect either way; a consumer needing a body other than the Specimen's must perform a read.

    ​The assigned logical ids bear no relation to the urn:uuid placeholders sent in the request. A consumer that intends to reference the Patient, Practitioner or Organization in later orders should store them from this response. See an example, and Response Shapes below for the failure case.

  4. Sample processing (SENAITE internal): Shown as a parallel block, this step happens independently and asynchronously. A lab clerk works through the sample processing workflow in SENAITE — receiving, analysing, and resulting the sample.

  5. Results polling: The Consumer regularly polls the FHIR API using a GET search of the following structure:

   GET {fhir_api_root}/DiagnosticReport
     ?_lastUpdated=gt<since>
     &_summary=true
     &_include=Observation:result
  • _lastUpdated=gt<since> — consumers should store the timestamp of the last successful fetch and pass it on each subsequent poll to retrieve only new or changed reports.
  • _summary=true — required on all search requests. For performance reasons the server will not return the full PDF payload during polling. Under _summary=true the presentedForm.data field (the base64-encoded PDF) is excluded; only metadata such as contentType and title is returned.
  • _include=Observation:result — instructs the server to return the associated Observation resources as sibling entries in the same Bundle, avoiding a second round-trip to retrieve discrete results.

The response is a SenaiteResultsBundle containing the SenaiteDiagnosticReport entries and any associated SenaiteObservation entries. A response can contain both per-sample reports and, where the laboratory has published one, a combined report covering several samples — see Combined reports.

  1. PDF report fetch: After discovering a new report in the polling response, the Consumer retrieves the full PDF by performing a direct read of the DiagnosticReport by id — without _summary:

    GET {fhir_api_root}/DiagnosticReport/{id}
    

    The response is the complete DiagnosticReport resource with presentedForm.data populated as a base64-encoded PDF attachment.

Request Notes

Identifying Resources in a Request Bundle

Entry fullUrl values are urn:uuid placeholders used to resolve references between entries; they do not become logical ids (transaction processing rules).

Resource.id must be absent from every entry. The base specification says a server SHALL ignore a supplied id; SENAITE instead rejects the Bundle, so that a consumer under the impression it controls the id space finds out immediately rather than silently.

Reference form follows entry presence, not resource type:

Target Reference form Example
Has an entry in this Bundle that entry's urn:uuid urn:uuid:ddaf107d-a44d-4b7b-966b-65d82de495cc
Already exists in SENAITE ResourceType/{id} Patient/7f3c1e02-9a4b-4d18-b6e1-0f5a2c9d4471

​Both forms can appear in the same resource: a repeat order may reference an existing Patient as Patient/{id} while referencing the Specimen in the same Bundle as urn:uuid:…. See the repeat order example.

Conditional Create

Patient, Practitioner and Organization entries may carry request.ifNoneExist, keyed on an identifier, so a repeat submission matches the existing resource rather than creating a duplicate:

"request": {
  "method": "POST",
  "url": "Patient",
  "ifNoneExist": "identifier=https://ehr.example.org/mrn|MRN-20394857"
}

ServiceRequest and Specimen never carry it — both are created for every request. A consequence worth designing around: re-POSTing an identical Bundle after a network timeout will produce a second order, even though the patient, clinician and client are matched rather than duplicated.

Constraints specific to this IG:

  • The key must be identifier=<system>|<value>. A system is mandatory; see Identifiers for why.
  • Either identifier may be the key. The consumer's own external ID (use = #secondary) is the usual choice, since the consumer owns the value from the outset. The internal ID (use = #usual) also works once SENAITE has returned it from an earlier order — matching reads an existing resource rather than creating one.
  • The internal ID must not appear in the resource body. It is generated by SENAITE, and an entry carrying it is rejected by the no-internal-id-on-create invariant. Using it as an ifNoneExist key is a different thing from supplying it as data. The ServiceRequest carries no identifier; its only identifier is the optional requisition, which groups requests and is not an ifNoneExist key (see Multi-tube orders).
  • A match discards the submitted body. If a patient's address has changed since the last order, SENAITE keeps the value it already holds and the consumer receives a 200 OK with no indication the update was ignored.
  • Resources with no identifier cannot be matched at all. Create the resource once, store the logical id from the transaction response, and reference it thereafter. This is the normal path for a Client Organisation with no formal ID, and for deployments that provision Clients administratively.

Note that conditional create is trial use in FHIR R5, unlike the transaction machinery around it.

Multi-tube orders

In SENAITE each sample type is a separate Sample, so each is a separate request: a SenaiteRequestBundle always carries exactly one ServiceRequest and one Specimen, and an order spanning several tubes is submitted as one Bundle per tube. The tubes are tied together by ServiceRequest.requisition.

The requisition (Sample Group ID). Supply the same requisition on the ServiceRequest of every tube in the order. Its system is fixed by this IG to the Sample Group ID namespace (https://fhir.senaite.org/NamingSystem/sample-group-id); you choose the value, which must be unique within your organisation, for example your placer order number. It is optional and a grouping label, not a contract: SENAITE cannot know that an order is complete, does not require the value to be unique per sample, and does not reject a second ServiceRequest that reuses a sample type under the same value. The server scopes every search on it to the Client(s) you are authorised for. See Sample Group ID.

One request per sample type. Within a requisition, the sample type is the natural key: a single sample type is always contained in a single ServiceRequest. Several panels that run on the same sample type (for example CBC and ESR, both EDTA) therefore go in one ServiceRequest, using the default panel code and enumerating the tests in orderDetail. This is a convention and not enforced, because the same sample type can legitimately recur under one requisition: a recollection after a rejected sample, serial timed draws, or several blood-culture sets.

Example workflow of request/results exchange

Sequence. Submit the tubes of an order one after another, not in parallel:

  1. First tube. A full Bundle, with ifNoneExist on the Patient, Practitioner and Organization entries as usual. Store the logical ids from the response.
  2. ​Later tubes. Omit those three entries and reference the stored ids as Patient/{id}, Practitioner/{id} and extension[SenaiteClient] → Organization/{id}, exactly as for a repeat order.

One Patient and one Client per Sample Group ID. Every request that shares a Sample Group ID must be for the same Patient and the same Client. The server checks this when it processes each Bundle, against the requests already recorded for that value within the Clients the caller is authorised for. If a Bundle's Patient or Client differs, the whole Bundle is rejected with 422 Unprocessable Entity and an OperationOutcome (issue code business-rule) whose expression points at the offending reference, and nothing is created. The response does not identify the other Patient or Client. See the Patient example and the Client example. Correct the reference, or use a different Sample Group ID if the requests are not in fact one order.

Failure and recovery. Each Bundle is atomic by itself, and a failure in one tube does not roll back the others. There is no atomicity across tubes: if the second Bundle fails after the first succeeds, the order exists in part. A failed Bundle creates nothing, so resend just that tube.

Results. Each tube produces its own per-sample DiagnosticReport. Per-sample reports carry no Sample Group ID; see Combined reports for the optional single report that covers the whole order and carries it.

Response Shapes

A consumer must handle two shapes. On success, a transaction-response Bundle. On failure, an HTTP 4xx or 5xx carrying a single OperationOutcome and no Bundle at all — so Bundle.entry cannot be assumed present in order to read the outcome.

Versioning

SENAITE does not maintain meta.versionId for the resources in this workflow. Location headers and Bundle.entry.response.location carry [base]/[type]/[id] with no /_history/[vid] suffix, no ETag is returned, and no vread or history interactions are offered.

The single exception is the worksheet Task in the Instrument Integration workflow, where the PATCH interaction requires If-Match to prevent two instruments claiming the same worksheet.

Panel and orderDetail Behaviour

The ServiceRequest.code element identifies the ordered panel. The ServiceRequest.orderDetail element enumerates the individual tests to run and is governed by the following rules:

Scenario code orderDetail Server behaviour
Defer to panel Panel code Empty (omitted) Sample is created for all tests defined in the panel
Full elaboration Panel code All tests in the panel enumerated Sample is created for exactly the tests listed in orderDetail
Panel plus extras Panel code All panel tests enumerated, plus additional test codes Sample is created for exactly the tests listed in orderDetail
Partial subset ❌ Panel code One or more panel tests are missing Request is rejected — 400 Bad Request with an OperationOutcome
Defer to order detail Default panel code (30954-2) One or more test codes Sample is created for exactly the tests listed in orderDetail; no panel validation is performed
Default panel, no tests ❌ Default panel code (30954-2) Empty (omitted) Request is rejected — 400 Bad Request with an OperationOutcome

When a named panel code is supplied, orderDetail is treated as a complete elaboration of the order: the server validates that all tests belonging to the panel are present, then creates the sample for exactly those tests — plus any additional tests listed beyond the panel's definition. Omitting orderDetail entirely defers to the panel's own definition. Supplying a partial subset is always rejected, as the server cannot infer which panel tests were intentionally excluded.

Note: This design intentionally diverges from the strict R5 multi-ServiceRequest pattern for requesting multiple procedures. Rather than requiring one ServiceRequest per test, this server uses orderDetail as a structured elaboration of the order, keeping the request self-contained and aligned with SENAITE's internal model of a single Sample with a list of analyses. See orderDetail Encoding below for the R5-conformant structure used.

If the consumer supplies a named panel code with an orderDetail that omits tests from the panel, the request is rejected. The OperationOutcome will identify the missing codes, for example:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "business-rule",
    "details": {
      "text": "orderDetail is a partial subset of panel 57021-8 (CBC). Missing tests: [4544-3 Platelets [#/volume] in Blood]. Either omit orderDetail to use the full panel definition, or include all panel tests."
    }
  }]
}

To order the full panel without customisation, omit orderDetail entirely. To order a specific set of tests within or extending a panel, enumerate all intended tests in orderDetail. To order an arbitrary collection of individual tests without reference to any panel, use the default panel code (30954-2) and enumerate the desired tests in orderDetail. Ordering multiple named panels in a single ServiceRequest is not supported; consumers requiring tests from multiple panels should instead enumerate the individual tests using the default panel code.

orderDetail Encoding

In FHIR R5, orderDetail is a backbone element comprising an optional parameterFocus and one or more parameter entries, each with a typed code and a value[x]. This server uses one orderDetail entry per test, with a single parameter carrying the LOINC test code as a valueCodeableConcept. The parameter.code identifies the parameter type using the SenaiteOrderDetailParameterCS code system defined in this IG:

"orderDetail": [
  {
    "parameter": [{
      "code": {
        "coding": [{
          "system": "http://fhir.senaite.org/CodeSystem/senaite-order-detail-parameter-cs",
          "code": "test-code",
          "display": "Test Code"
        }]
      },
      "valueCodeableConcept": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "718-7",
          "display": "Hemoglobin [Mass/volume] in Blood"
        }]
      }
    }]
  }
]
The Default Panel Code

Because ServiceRequest.code is required when orderDetail is present in FHIR R5, consumers ordering a free-form selection of tests rather than a named panel must supply a sentinel value. The server recognises LOINC code 30954-2 (Relevant diagnostic tests/laboratory data note) as this sentinel:

"code": {
  "concept": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "30954-2",
      "display": "Relevant diagnostic tests/laboratory data note"
    }],
    "text": "Relevant diagnostic tests/laboratory data note"
  }
}

When this code is present, the server bypasses panel validation entirely and creates the Sample for exactly the tests listed in orderDetail. Individual test codes should be LOINC-coded where available. Omitting or leaving orderDetail empty when using the default panel code is an error, as there is no panel definition to fall back on.

Default Panel Code on DiagnosticReport

The same default panel code appears on outbound DiagnosticReport resources when the underlying SENAITE Sample does not correspond to exactly one named panel. This covers three cases:

  • Individual tests only — the Sample was created from a ServiceRequest using the default panel code.
  • Multiple panels — the Sample has more than one panel assigned in SENAITE, which can occur when a sample is managed directly within SENAITE rather than via an inbound ServiceRequest.
  • Combined report — the report covers several Samples (see Combined reports), so more than one panel is always involved.

In all three cases, DiagnosticReport.code is set to 30954-2 and the individual test results carried as Observation resources (referenced via DiagnosticReport.result) are the authoritative record of what was ordered and resulted. Consumers should treat the Observation entries as the primary source of test identity in these reports, using DiagnosticReport.code only to recognise that a single named panel does not apply.

Reference Ranges

Where SENAITE has a normal range configured for the analyte, a resulted Observation returned to the consumer carries it in Observation.referenceRange, stripped back to a plain low/high Quantity pair:

"referenceRange": [
  {
    "low":  { "value": 4.5,  "unit": "10*3/uL", "system": "http://unitsofmeasure.org", "code": "10*3/uL" },
    "high": { "value": 11.0, "unit": "10*3/uL", "system": "http://unitsofmeasure.org", "code": "10*3/uL" }
  }
]

referenceRange is only meaningful for numeric (valueQuantity) results and is never present on an Observation POSTed by an instrument — see Instrument Integration — since SENAITE, not the instrument, owns the configured range. It is absent whenever no range is configured for the analyte, and low or high may each be absent independently for an open-ended range.

Combined Reports

SENAITE can publish a single multi-sample report. The laboratory can use this to produce one PDF for all the samples that share a ServiceRequest.requisition. It is exposed as a SenaiteDiagnosticReport that is based on several ServiceRequests.

Two kinds of report.

  Per-sample report Combined report
Represents One Sample A multi-sample report published for one requisition
basedOn At most one ServiceRequest (none for a Sample created inside SENAITE) Every ServiceRequest it covers — more than one
Sample ID identifiers One One for each covered Sample
Client Sample ID identifiers If supplied (one) One for each covered Sample that has one
Sample Group ID identifier Absent Required (exactly one)
specimen The Sample's Specimen (one) The Specimen of each covered Sample — one for each ServiceRequest in basedOn
result That Sample's Observations The Observations of all covered ServiceRequests
presentedForm That Sample's PDF The single combined PDF
code The panel, or 30954-2 30954-2
status From the Sample state (see Status Mappings) final at creation

basedOn.count() > 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.

​They coexist. Publishing or republishing a combined report never removes or replaces a per-sample report. A search can therefore return both for the same Sample — for example GET DiagnosticReport?identifier=https://fhir.senaite.org/NamingSystem/sample-id|<sample id> returns that Sample's per-sample report together with any combined report that covers it, because a combined report carries one Sample ID for each Sample it covers. The same holds for the Client Sample ID. GET DiagnosticReport?identifier=https://fhir.senaite.org/NamingSystem/sample-group-id|<value> returns the combined report(s) for the group alone. The identifier lists on a combined report are unordered and carry no pairing between a Sample ID and a Client Sample ID; read the Specimens the combined report references in specimen (each carries its own Sample ID and Client Sample ID) or use the per-sample report to pair them. _include=DiagnosticReport:specimen is not supported in this version. Consumers should ingest per-sample reports as the results and treat a combined report as a document. See the combined report example and the results bundle containing both kinds.

Observations. Each Observation's own basedOn identifies the ServiceRequest it belongs to, so the result list of a combined report can always be split by sample.

Lifecycle.

  • When it exists. A combined report is created when the laboratory publishes the multi-sample report, which requires every covered Sample to be published, so it is final at creation. The server cannot create one on its own: the requisition is only a label.
  • Membership is fixed at publication. basedOn records the ServiceRequests covered at that moment. It is not re-evaluated if more samples later join the requisition; a late tube is delivered by publishing a new combined report.
  • Corrections. If a covered Sample is invalidated or retracted, or the combined report is republished, the superseded combined report is marked entered-in-error and the new one is a new DiagnosticReport. There is no automatic supersession.
  • Same Client and Patient. A combined report never spans different Clients or Patients. The server refuses to build one rather than merge them, because the Sample Group ID value is consumer-owned and two consumers could reuse one. Searches on it, and this check, are scoped to the Client(s) the caller is authorised for.

Polling. Both kinds are returned by the same search described in step 5, and both are retrieved by id for the PDF as in step 6. Nothing about polling changes; consumers need only distinguish the two kinds by basedOn as above.

Secondary Workflow: Revoke Lab Request

Revoke lab request sequence diagram
  1. The External Consumer first submits the ServiceRequest Bundle to the SENAITE FHIR API and receives a transaction response bundle.
  2. When a lab request must be revoked, the Consumer then POSTs to ServiceRequest/{id}/$revoke with optional reason(s) as to why this is being revoked as the body, for example:
    {
      "resourceType": "Parameters",
      "parameter": [
     {
       "name": "reason",
       "valueString": "Sample lost in transit"
     },
     {
       "name": "reason",
       "valueString": "Patient requested revocation of processing"
     }
      ]
    }
    
  3. The SENAITE FHIR API forwards this revoke action to the SENAITE Application, which withdraws the associated sample and updates its state to Cancelled, and notifies downstream systems as needed.
  4. The application confirms the revocation and the FHIR API returns 200 OK with the updated ServiceRequest resource set to status: revoked and an incremented versionId.

$revoke acts on a single ServiceRequest and therefore on a single Sample, which is the correct granularity for a multi-tube order: revoke the tubes you no longer want, one by one. There is no order-level revoke. Once results are published $revoke returns 409 Conflict, so a published combined report is immutable; a correction is delivered as a new report (see Combined reports).

In the diagram, this revoke workflow is effectively a conditional branch from the sample processing stage: the main workflow continues toward result publication, while the revoke workflow terminates the request cleanly and signals the external consumer that the ServiceRequest has been revoked.

Status Mappings

Inbound: POST ServiceRequest → SENAITE Sample

A posted ServiceRequest can only ever create a Sample in the sample_received (Received) state. The registered and sample_due states are therefore unreachable via this workflow.

FHIR ServiceRequest Status SENAITE Transition Side Effects Condition Notes
active (none) → sample_received New Sample created    
$revoke sample_received → cancelled Sample cancelled No reason included This transition is configurable per deployment
$revoke sample_received → rejected Sample rejected Reason included This transition is configurable per deployment
$revoke to_be_verified | verified → rejected Sample rejected    

Outbound: SENAITE Sample → GET DiagnosticReport

When a consumer fetches a DiagnosticReport, its status is derived from the current SENAITE Sample state. Because Samples in this workflow are always created via an inbound ServiceRequest, the registered and sample_due states are not reachable and have no mapping.

SENAITE Sample State Label FHIR DiagnosticReport Status
sample_received Received preliminary
to_be_verified To be Verified preliminary
verified Verified preliminary
published Published final
invalid Invalid entered-in-error
rejected Rejected cancelled
cancelled Cancelled cancelled
retracted Retracted entered-in-error
dispatched Dispatched (previous valid state)

Note on dispatched: Dispatched is a configurable state indicating that the sample has been sent from the lab. Because a sample can be dispatched from multiple upstream states, the DiagnosticReport.status is derived from the sample's last valid state prior to dispatch rather than being fixed. For example, a sample dispatched after published will yield a final report.

Combined reports. A combined report has no Sample state of its own. It is created only once every covered Sample is published, so it is final at creation; if a covered Sample later becomes invalid or retracted, the combined report is marked entered-in-error. See Combined reports.