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
Actors:
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:
See:
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.
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.
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.
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.
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.
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.
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.
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.
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:
identifier=<system>|<value>. A system is mandatory; see Identifiers for why.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.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).200 OK with no indication the update was ignored.Note that conditional create is trial use in FHIR R5, unlike the transaction machinery around it.
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.
Sequence. Submit the tubes of an order one after another, not in parallel:
ifNoneExist on the Patient, Practitioner and Organization entries as usual. Store the logical ids from the response.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.
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.
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.
orderDetail BehaviourThe 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-
ServiceRequestpattern for requesting multiple procedures. Rather than requiring oneServiceRequestper test, this server usesorderDetailas 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. SeeorderDetailEncoding 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 EncodingIn 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"
}]
}
}]
}
]
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.
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:
ServiceRequest using the default panel code.ServiceRequest.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.
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.
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.
final at creation. The server cannot create one on its own: the requisition is only a label.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.entered-in-error and the new one is a new DiagnosticReport. There is no automatic supersession.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.
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"
}
]
}
Cancelled, and notifies downstream systems as needed.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.
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 |
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, theDiagnosticReport.statusis derived from the sample's last valid state prior to dispatch rather than being fixed. For example, a sample dispatched afterpublishedwill yield afinalreport.
Combined reports. A combined report has no Sample state of its own. It is created only once every covered Sample is
published, so it isfinalat creation; if a covered Sample later becomesinvalidorretracted, the combined report is markedentered-in-error. See Combined reports.