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
SENAITE uses FHIR identifier elements to carry business identifiers for key resources. This page describes the identifier conventions used across this IG.
Four resources — SenaitePatient, SenaitePractitioner, SenaiteOrganization and SenaiteSpecimen — follow one consistent pattern: a paired internal and external identifier, distinguished by Identifier.use. Alongside the FHIR logical id, that gives three levels:
Resource.id) — Every FHIR resource has a logical id, which SENAITE assigns. This is not an identifier element and is never supplied by the consumer: a POST entry carrying Resource.id is rejected. In a transaction Bundle, entry.fullUrl holds a urn:uuid placeholder used only to resolve references between entries in the same Bundle — it does not become the logical id and has no persistence. See Identifying Resources in a Request Bundle.use = #usual, sliced as senaiteId) — A human-readable identifier generated by SENAITE when the resource is created. It cannot be supplied on an external create: an entry carrying it in a POSTed SenaiteRequestBundle is rejected by the no-internal-id-on-create invariant. Once created it is available to identify the resource on reads, on subsequent updates, and as a request.ifNoneExist key.use = #secondary, slice name varies — see Slice naming) — A human-readable business identifier originating in the API consumer's system. Unlike the internal ID it may be supplied on the initial create. Preserved as-is by SENAITE.| Internal ID | External ID | |
|---|---|---|
use |
#usual (fixed) |
#secondary (fixed) |
| Slice | senaiteId |
varies — mrn, clientSampleId or externalId |
| Cardinality | 0..1 |
0..1 |
| Assigned by | SENAITE | API consumer |
| Supplied on create? | No — rejected | Yes, optionally |
| Present on read? | Yes, once assigned | Yes, if supplied |
system required? |
Yes | Yes |
Usable as ifNoneExist key? |
Yes | Yes |
The pattern above applies to SenaitePatient, SenaitePractitioner, SenaiteOrganization and SenaiteSpecimen. Other resources in this IG carry identifiers on their own terms:
| Resource | Identifiers |
|---|---|
SenaiteServiceRequest |
No identifier (0..0), but an optional requisition, which carries the Sample Group ID — see Sample Group ID and ServiceRequest below |
SenaiteDiagnosticReport |
A per-sample report mirrors the two Specimen identifiers — same slice names, same values. A combined report carries one Sample ID and, where present, one Client Sample ID for each Sample it covers, plus the Sample Group ID — see DiagnosticReport below |
SenaiteDevice |
Internal device ID (#usual) and external asset ID (#secondary) |
SenaiteInstrumentServiceRequest |
Analysis ID (#usual) only |
SenaiteWorksheetTask |
Worksheet ID (#usual) only |
SenaiteObservation |
None |
Identifier.use carries the pattern, not the slice name. The internal slice is senaiteId on all four resources, but the external slice is named differently on each:
| Resource | Internal slice | External slice | Default external namespace |
|---|---|---|---|
SenaitePatient |
senaiteId |
mrn |
.../NamingSystem/patient-mrn |
SenaitePractitioner |
senaiteId |
externalId |
.../NamingSystem/practitioner-external-id |
SenaiteOrganization |
senaiteId |
externalId |
.../NamingSystem/organization-external-id |
SenaiteSpecimen |
senaiteId |
clientSampleId |
.../NamingSystem/client-sample-id (fixed) |
SenaiteDiagnosticReport |
senaiteId |
clientSampleId |
.../NamingSystem/client-sample-id (fixed) |
This is deliberate. MRN and Client Sample ID are the names these fields already carry in SENAITE, and renaming them in the IG would put the specification at odds with the application it describes. Where a resource has no established SENAITE-side name for its external identifier, the generic externalId is used.
The namespace URI follows the same rule as the slice name, so the two always agree: mrn is served by .../NamingSystem/patient-mrn, clientSampleId by .../NamingSystem/client-sample-id, and externalId by .../NamingSystem/{resource}-external-id. Resources sharing an identifier share its slice name: the Specimen and DiagnosticReport both call the Client Sample ID clientSampleId.
Two consequences worth being explicit about:
use = #secondary, a mandatory system, and the same create/read semantics. Nothing about the behaviour of the pattern varies with the slice name.use (or, on SenaiteDiagnosticReport, on system), never on the slice name, so a consumer reading these resources matches on use and system. Slice names appear in the profile definitions and the rendered StructureDefinitions in this IG; they do not appear in instance JSON or XML, and no consumer needs to know them to interoperate.All identifier values are restricted to alphanumeric characters and hyphens. Spaces, quotes, and other special characters are not permitted.
A system is mandatory on both the internal and the external identifier (system 1..1 on every slice). Slicing is discriminated on use rather than system, precisely so that the system URI can vary by deployment without breaking slice resolution. (SenaiteDiagnosticReport is the exception: its three identifiers — the two Sample identifiers and the Sample Group ID — all have fixed systems, so it slices on system — see DiagnosticReport.)
For Patient, Practitioner and Organization, neither system is pinned to a fixed value by this IG. Each is configurable per deployment, with a default declared as a NamingSystem for deployments and consumers that have no URI of their own:
| Resource | Internal ID default | External ID default |
|---|---|---|
| Patient | https://fhir.senaite.org/NamingSystem/patient-id |
https://fhir.senaite.org/NamingSystem/patient-mrn |
| Practitioner | https://fhir.senaite.org/NamingSystem/practitioner-id |
https://fhir.senaite.org/NamingSystem/practitioner-external-id |
| Organization | https://fhir.senaite.org/NamingSystem/organization-id |
https://fhir.senaite.org/NamingSystem/organization-external-id |
| Specimen | https://fhir.senaite.org/NamingSystem/sample-id (fixed) |
https://fhir.senaite.org/NamingSystem/client-sample-id (fixed) |
In practice a deployment substitutes its own URI for the internal namespaces, and the consumer supplies its own registry URI for the external ones — an MRN namespace, a provider directory, an organisation register — agreed at integration time. The defaults exist so that a client with no namespace of its own still has a well-known URI to use, rather than omitting the system.
Each default external URI mirrors the slice name it serves, so patient-mrn rather than patient-external-id — see Slice naming.
The default external namespaces are shared, and that carries a risk. They are safe where a SENAITE instance serves a single consumer. Where two or more consumers submit to the same instance and both fall back to a default, they occupy one namespace: two unrelated patients both carrying MRN-20394857 would match each other under request.ifNoneExist, returning 200 OK against the wrong record with no error. Any deployment serving multiple consumers should agree a distinct external URI per consumer at integration time and not rely on the default.
Specimen is the exception. Both of its namespaces are fixed rather than configurable, because a per-sample SenaiteDiagnosticReport carries the same two identifiers with the same values, and correlating a Specimen with its DiagnosticReport by system + value — without traversing references — only works if both resources use an identical system. Making these configurable would require reopening SenaiteDiagnosticReport to match.
request.ifNoneExist matches on system and value. A bare value would match across every consumer's namespace, so two unrelated organisations both using MRN-20394857 would collide. Note also that the FHIR identifier search parameter ignores Identifier.use: the system URI is the only thing scoping a consumer's query to its own external identifiers rather than SENAITE's internal ones. See Conditional Create.
ifNoneExistEither identifier may key a conditional create, and the form is always identifier=<system>|<value>:
Supplying the internal ID as an ifNoneExist key is not the same as supplying it in the resource body, which stays prohibited. ServiceRequest and Specimen never carry ifNoneExist at all — both are created for every request.
In SENAITE, the Sample is the unit of work. It carries both the physical specimen and the analysis request and result processing that surrounds it. FHIR splits that single object across SenaiteSpecimen and SenaiteDiagnosticReport, so the identifiers on those two resources are shared, and are both identifiers of the Sample.
Two identifiers apply:
| Name | Use | Slice | System | Assigned by |
|---|---|---|---|---|
| Sample ID | #usual |
senaiteId |
https://fhir.senaite.org/NamingSystem/sample-id |
SENAITE (server-assigned) |
| Client Sample ID | #secondary |
clientSampleId |
https://fhir.senaite.org/NamingSystem/client-sample-id |
API consumer or laboratory staff |
The Specimen and DiagnosticReport use these same two slice names for these same two values.
#usual) — the internal IDThe Sample ID is the internal SENAITE Object ID, generated by SENAITE at the moment the Sample is created. This is true regardless of how creation was triggered:
SenaiteRequestBundle is POSTed and SENAITE creates the Sample as part of processing the transaction.In both cases SENAITE owns the value. It is never supplied by the client, and a POST that attempts to set it will be rejected.
This is the Internal ID level of the General Pattern above.
#secondary) — the external IDThe Client Sample ID is an external identifier for the same Sample, originating outside SENAITE. It is optional. It may be assigned:
SenaiteRequestBundle.SENAITE preserves the value as-is and does not validate it beyond the value format rules. A deployment may configure it as the value encoded in the specimen container barcode — see Barcode.
This is the External ID level of the General Pattern.
The barcode attached to the specimen container encodes one of the two Sample identifiers, chosen per deployment:
SENAITE returns the label where generated — on reads - in the SenaiteSpecimenBarcode extension, as a base64-encoded PDF or image a consumer can print as a pre-label. Like the Sample ID, it is generated by SENAITE and must not be supplied on create: a SenaiteRequestBundle whose Specimen entry carries it is rejected.
| Resource | Sample ID (#usual) |
Client Sample ID (#secondary) |
|---|---|---|
SenaiteServiceRequest |
Not present | Not present |
SenaiteSpecimen |
Present | Present if supplied |
SenaiteDiagnosticReport (per-sample) |
Present | Present if supplied |
SenaiteDiagnosticReport (combined) |
Present — one for each covered Sample | Present if supplied — one for each covered Sample that has one |
SenaiteServiceRequest carries no identifier — see ServiceRequest below. The Specimen is therefore the only place a consumer can supply a Client Sample ID through the API.
Where the Sample ID and Client Sample ID appear on more than one resource, the values are identical. A Specimen and its per-sample DiagnosticReport can therefore be correlated by comparing system + value, without traversing references (the DiagnosticReport also references its Specimen in specimen). A combined DiagnosticReport covers several Samples and so carries one Sample ID for each, each matching the Specimen of that Sample, and one Client Sample ID for each covered Sample that has one. These lists are unordered and carry no pairing between a Sample ID and a Client Sample ID, so a consumer must not infer it from list position. To pair them, read the Specimens the report references in specimen — each carries its own Sample ID and Client Sample ID — or use the corresponding per-sample report or the Specimen returned in the transaction response.
A Sample Group ID groups the requests of one order that is submitted as several SenaiteRequestBundle transactions — normally one per sample type (tube). It identifies a group of Samples, not a Sample, so it is deliberately separate from the two Sample identifiers above and is not part of the General Pattern. It is carried on ServiceRequest.requisition, the FHIR element for exactly this: a shared identifier common to the requests of one composite order.
| Namespace | https://fhir.senaite.org/NamingSystem/sample-group-id — fixed by this IG, not deployment-configurable |
| Carried on | SenaiteServiceRequest.requisition (0..1); and as identifier[sampleGroupId] on a combined SenaiteDiagnosticReport (never on a per-sample report) |
| Value assigned by | API consumer — the consumer chooses the value and supplies the same value on every ServiceRequest in the order |
system required? |
Yes, and fixed: requisition.system must be the namespace above |
| Required? | No. A single-tube order needs none, and a request without one is unaffected |
| Unique per sample? | No, and not enforced. It is a label: SENAITE cannot know that an order is complete, and the same sample type can legitimately recur under one value (a recollection, serial draws, several culture sets) |
| Same Patient and Client? | Yes — enforced. Every request sharing a value must be for the same Patient and Client; a Bundle that differs is rejected with 422. See Multi-tube orders |
| Unique per consumer? | Yes — this is the consumer's responsibility. See below |
| Search | On DiagnosticReport only: DiagnosticReport?identifier=https://fhir.senaite.org/NamingSystem/sample-group-id\|<value>, which returns the combined report(s) for the group. There is no search by requisition on ServiceRequest |
Why the system is fixed, and what that costs. Like the Client Sample ID, the Sample Group ID has an IG-defined system rather than a deployment-configurable one. That gives every consumer the same, copy-and-paste search and lets the DiagnosticReport carry it as an ordinary named slice. The cost is that the system no longer separates one consumer's values from another's: two consumers who both use ORD-123 are in the same namespace. Two things follow:
Why the system is named for the concept, not the element. In base FHIR the system of ServiceRequest.requisition is unconstrained: any system is valid there. This IG fixes it to one, and names the namespace for what it identifies (a group of Samples) rather than for the element that carries it. The same value appears on the DiagnosticReport, which has no requisition element, so tying the name to ServiceRequest.requisition would mislead.
On the DiagnosticReport it is identifier[sampleGroupId], carried by a combined report only, so the standard identifier search finds the combined report(s) of one order. Per-sample reports do not carry it. The value format rules apply.
See Multi-tube orders for how it is used, and Combined reports for the report that covers a whole group.
| Slice | Use | System | Description | Assigned by |
|---|---|---|---|---|
senaiteId |
#usual |
Deployment-configurable; default https://fhir.senaite.org/NamingSystem/patient-id |
Internal SENAITE Patient ID, generated on creation | SENAITE (server-assigned) |
mrn |
#secondary |
The consumer's own registry URI; default https://fhir.senaite.org/NamingSystem/patient-mrn |
External Patient ID — the Medical Record Number from the consumer's system | API consumer |
The internal ID must not be supplied on create. The external ID may be, and is the usual request.ifNoneExist key. A system is mandatory on both. The external slice is named mrn after the SENAITE field, as is its default namespace URI — see Slice naming.
Additional identifier types (e.g. passport number, national health ID) are permitted — Patient slicing is open — but are not explicitly constrained by this IG. Deploying organisations may add further identifier slices as needed.
| Slice | Use | System | Description | Assigned by |
|---|---|---|---|---|
senaiteId |
#usual |
Deployment-configurable; default https://fhir.senaite.org/NamingSystem/practitioner-id |
Internal SENAITE Practitioner ID, generated on creation | SENAITE (server-assigned) |
externalId |
#secondary |
The consumer's own registry URI; default https://fhir.senaite.org/NamingSystem/practitioner-external-id |
External Practitioner ID — e.g. national provider number, hospital staff ID | API consumer |
The internal ID must not be supplied on create. A system is mandatory on both. Practitioner slicing is closed: no identifiers beyond these two.
| Slice | Use | System | Description | Assigned by |
|---|---|---|---|---|
senaiteId |
#usual |
Deployment-configurable; default https://fhir.senaite.org/NamingSystem/organization-id |
Internal SENAITE Client ID, generated on creation for the submitting client organisation | SENAITE (server-assigned) |
externalId |
#secondary |
The consumer's own registry URI; default https://fhir.senaite.org/NamingSystem/organization-external-id |
External Organization ID — e.g. national organisation ID, internal client code | API consumer |
The internal ID must not be supplied on create. A system is mandatory on both. Organization slicing is closed: no identifiers beyond these two.
An Organization with no external ID cannot be reached by request.ifNoneExist at all. Create it once, store the logical id from the transaction response, and reference it thereafter — the normal path for deployments that provision Clients administratively.
The Specimen represents the physical material of a SENAITE Sample and carries both Sample identifiers. The values match those on the corresponding DiagnosticReport.
| Slice | Use | System | Description | Assigned by |
|---|---|---|---|---|
senaiteId |
#usual |
https://fhir.senaite.org/NamingSystem/sample-id (fixed) |
Sample ID — the internal SENAITE Object ID, matching the DiagnosticReport | SENAITE (server-assigned) |
clientSampleId |
#secondary |
https://fhir.senaite.org/NamingSystem/client-sample-id (fixed) |
Client Sample ID — the consumer's own reference; encoded in the barcode where the deployment is so configured | API consumer |
The Sample ID must not be supplied by the client on create; it is generated by SENAITE on sample creation. The Client Sample ID may be supplied externally, either on the Specimen entry of a POSTed SenaiteRequestBundle or by laboratory staff against the Sample in the web application.
Both systems are fixed rather than deployment-configurable — see System URIs for why. The external slice is named clientSampleId after the SENAITE field, as it is on SenaiteDiagnosticReport — see Slice naming.
Notes on references: Specimens are referenced from SenaiteInstrumentServiceRequest.specimen (linking the instrument request to the intended sample). These references use the FHIR logical id. Identifier-based correlation should use the Sample ID, which is shared with the DiagnosticReport.
A SenaiteDiagnosticReport is either a per-sample report or a combined report (one whose basedOn lists more than one ServiceRequest) — see Combined reports. The identifiers differ between the two.
All three identifiers have fixed systems, so the identifier slicing is by system and closed.
| Slice | Use | System | Description | Assigned by |
|---|---|---|---|---|
senaiteId |
#usual |
https://fhir.senaite.org/NamingSystem/sample-id |
Sample ID — the SENAITE Object ID, matching the Specimen. One on a per-sample report; one for each covered Sample (0..*) on a combined report |
SENAITE (server-assigned) |
clientSampleId |
#secondary |
https://fhir.senaite.org/NamingSystem/client-sample-id |
Client Sample ID — matching the Specimen, if one was supplied. One on a per-sample report; one for each covered Sample that has one (0..*) on a combined report |
API consumer |
sampleGroupId |
— | https://fhir.senaite.org/NamingSystem/sample-group-id |
Sample Group ID — the value of ServiceRequest.requisition, grouping the Samples a combined report covers. Combined reports only. See Sample Group ID |
API consumer |
Per-sample report. It represents the results of a SENAITE Sample and carries senaiteId and, if supplied, clientSampleId, with the same values as on the corresponding Specimen. Slice names, use, system and value of those two are identical to the Specimen's, which is what lets a consumer holding both resources correlate them without traversing references. It carries no sampleGroupId.
Combined report. It covers several Samples, so it carries one senaiteId for each Sample it covers — as many as ServiceRequests in basedOn, each matching that Sample's Specimen, so a consumer can find the report by searching on any covered Sample ID — and exactly one sampleGroupId. It also carries a clientSampleId for each covered Sample that has one, so it can equally be found by searching on a Client Sample ID. These identifier lists are unordered and carry no pairing — nothing says which Client Sample ID belongs to which Sample ID, and consumers must not infer it from position (the same is true of the Sample IDs, the specimen references and the basedOn references). To pair them, read the referenced Specimens, each of which carries its own Sample ID and Client Sample ID, or use the per-sample report. The specimen element carries one reference per covered Sample, and _include=DiagnosticReport:specimen is not supported in this version, so read each Specimen by id. The invariant dr-identifier-shape enforces the counts here and the per-sample rules above.
Instruments registered in SENAITE carry two explicit identifiers:
| Slice | Use | System | Description | Assigned by |
|---|---|---|---|---|
senaiteId |
#usual |
https://fhir.senaite.org/NamingSystem/device-id |
Device ID — the internal identifier assigned by SENAITE | SENAITE (server-assigned) |
externalId |
#secondary |
Agreed per-integration | External ID — the asset register number or identifier from the consumer's system | API consumer |
The #usual identifier must not be supplied by the client on POST.
Device predates the general pattern above and is not fully aligned with it: system is not currently mandatory on the external identifier, and no default namespace is declared for it. This is noted rather than changed, since instrument registration is a distinct workflow — see Instrument Integration.
SenaiteServiceRequest carries no identifier. ServiceRequest.identifier is constrained to 0..0 and is therefore absent on both write and read. The one identifier it may carry is the optional requisition, which groups the requests of one multi-tube order.
The reasoning is that sample identity belongs to the Sample. SENAITE holds no stored ServiceRequest object: a ServiceRequest is POST input within a SenaiteRequestBundle, and thereafter a projection over the AnalysisRequest that Bundle created. At submission time no Sample ID exists yet, and once the Sample does exist its identifiers live on the resources that represent it — the Specimen and the DiagnosticReport. Carrying a copy on the ServiceRequest would give the same value three homes with no additional meaning. A requisition is different: it identifies an order, which is a thing no other resource represents.
Practical consequences for consumers:
$revoke.identifier search on ServiceRequest, and no search by requisition. A consumer finds the combined report of a multi-sample order by searching DiagnosticReport on the Sample Group ID — see Sample Group ID.