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
This page describes how SENAITE's internal object model relates to FHIR R5 resources as used in this Implementation Guide. Understanding this mapping is essential context before reading the workflow pages.
A key distinction in this IG is between representation (how a SENAITE object is expressed as a FHIR resource) and origin (how a SENAITE object may have been created). These are not always the same thing — see the AnalysisRequest section below for the most important example of this.
An AnalysisRequest is SENAITE's central object representing a laboratory sample and the tests requested against it. Depending on context, it is represented by two FHIR resources:
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| SENAITE → FHIR | AnalysisRequest |
DiagnosticReport |
The completed or in-progress result report for that one Sample (a per-sample report) |
| SENAITE → FHIR | AnalysisRequest |
Specimen |
The physical specimen associated with the sample |
An AnalysisRequest may be traceable to an inbound ServiceRequest, but this is not always the case:
SenaiteRequestBundle), SENAITE creates a new AnalysisRequest from the inbound ServiceRequest. In this case the per-sample DiagnosticReport.basedOn references the originating ServiceRequest, recording the chain of custody.AnalysisRequest objects created directly within SENAITE — for example, walk-in patients, paper requisition entry, or instrument-driven workflows — have no corresponding ServiceRequest. These are not exposed as ServiceRequest resources via this API.In short: ServiceRequest → creates → AnalysisRequest, but not every AnalysisRequest has a ServiceRequest. The relationship is one-to-one: one ServiceRequest creates exactly one AnalysisRequest, which is why a SenaiteRequestBundle carries exactly one ServiceRequest and one Specimen.
An order that spans several tubes is several AnalysisRequest objects, one per sample type, created from several SenaiteRequestBundle transactions. They are associated by the Sample Group ID: the consumer-owned value carried on ServiceRequest.requisition (in the fixed Sample Group ID namespace) and recorded against each Sample created from a ServiceRequest that supplied one. SENAITE does not model the order as an object of its own; the Sample Group ID is a grouping label. See Multi-tube orders.
SENAITE can also publish a single report spanning several Samples. That multi-sample report is represented as a combined DiagnosticReport — a different report from the per-sample ones, which continue to exist alongside it. Its basedOn lists the ServiceRequest of every Sample it contains. It is therefore a many-to-one mapping from AnalysisRequest to DiagnosticReport, in contrast to the one-to-one mapping of the per-sample report. See Combined reports.
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| Bidirectional | Specimen (physical object) |
Specimen |
Submitted inbound as part of a SenaiteRequestBundle; read back via the results API. Carries both Sample identifiers — see Identifiers. |
The Specimen represents the physical material of a SENAITE Sample. Because SENAITE models the Sample as a single object spanning the physical specimen and the analysis request around it, the Specimen shares its identifiers with the corresponding SenaiteDiagnosticReport:
#usual, the internal ID): The SENAITE Object ID, generated by SENAITE when the Sample is created — whether that creation was triggered by a POSTed SenaiteRequestBundle or performed directly in the web application. It must not be supplied on POST. The same value appears on the corresponding SenaiteDiagnosticReport.#secondary, the external ID): An optional external identifier owned by the requesting system. It may be supplied on POST on the Specimen entry within a SenaiteRequestBundle — the only place a consumer can supply it, since SenaiteServiceRequest carries no identifier — or entered against the Sample by laboratory staff in the web application. SENAITE preserves the value as-is. A deployment may configure it, in place of the default Sample ID, as the value encoded in the barcode attached to the specimen container, so staff can scan and track the specimen against the requesting system's own reference.SenaiteServiceRequest.specimen is required (1..1) on inbound requests and references the Specimen entry within the same Bundle. SenaiteDiagnosticReport.specimen references the Specimen of each Sample the report covers: one on a per-sample report, one per covered Sample on a combined report. A per-sample report can also be correlated to its specimen by matching the Sample ID, which both resources share, and a combined report carries one Sample ID per covered Sample. _include=DiagnosticReport:specimen is not supported in this version; the Specimens are read by id.
SENAITE returns the barcode label on Specimen if they are generated, as a base64-encoded PDF or image in the SenaiteSpecimenBarcode extension. Barcode-enabled specimen tracking is essential for laboratory automation and quality assurance workflows, where physical specimens must be unambiguously tracked and correlated with requests and results across system boundaries.
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| Bidirectional | Patient |
Patient |
Submitted inbound as part of a SenaiteRequestBundle; read back via the results API |
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| Bidirectional | Client Contact |
Practitioner |
A Practitioner submitted in a request bundle is used to derive or match a SENAITE Client Contact representing the ordering clinician; Client Contact records are also readable as Practitioner resources via the API |
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| Bidirectional | Client |
Organization |
An Organization submitted in a request bundle is used to derive or match the SENAITE Client; Client records are also readable as Organization resources via the API. Identified on the ServiceRequest via the SenaiteClient extension. |
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| SENAITE → FHIR | Analysis |
Observation |
Each individual test result within a sample maps to an Observation, grouped under a DiagnosticReport |
| Direction | SENAITE Object | FHIR Resource | Notes |
|---|---|---|---|
| SENAITE → FHIR | Instrument |
Device |
SENAITE Instrument records are represented as Device resources; instruments are managed within SENAITE and identified in outbound instrument integration bundles |
| SENAITE Object | FHIR Resource | Relationship |
|---|---|---|
AnalysisRequest |
DiagnosticReport (per-sample) |
Represented as, one-to-one |
Several AnalysisRequest objects (one multi-sample report) |
DiagnosticReport (combined) |
Represented as, many-to-one |
AnalysisRequest |
Specimen |
Represented as |
Specimen |
Specimen |
Represented as |
Patient |
Patient |
Bidirectional |
Client Contact |
Practitioner |
Bidirectional |
Client |
Organization |
Bidirectional |
Analysis |
Observation |
Represented as |
Instrument |
Device |
Represented as |
(new AnalysisRequest) |
ServiceRequest |
Created from inbound |
Note:
ServiceRequestappears in the table as a trigger for creation, not as a direct representation of an existing SENAITE object. AServiceRequestarriving via the API causes SENAITE to create anAnalysisRequest; not allAnalysisRequestobjects have a correspondingServiceRequest.