Lab:V1.0 FHIR Lab2Patient: verschil tussen versies
(→Health professional retrieves lab results) |
k (→FHIR Profile Package: adding a disclaimer that the FHIR package is not yet developed for Lab2Patient) |
||
(33 tussenliggende versies door 2 gebruikers niet weergegeven) | |||
Regel 1: | Regel 1: | ||
{{Vdraft/InformationBox|This IG is currently under development and can not be considered stable and ready for use.}} | {{Vdraft/InformationBox|This IG is currently under development and can not be considered stable and ready for use.}} | ||
− | {{DISPLAYTITLE:FHIR Lab2patient V1.0.0}} | + | {{DISPLAYTITLE:FHIR Implementation Guide Lab2patient V1.0.0 - alpha}} |
<!--{{underconstruction}}--> | <!--{{underconstruction}}--> | ||
Regel 15: | Regel 15: | ||
[[Bestand:Functioneel-02.png|link=Lab:V1.0_Ontwerp_Lab2Patient|100px|rechts|Functional design|Go to functional design]] | [[Bestand:Functioneel-02.png|link=Lab:V1.0_Ontwerp_Lab2Patient|100px|rechts|Functional design|Go to functional design]] | ||
− | This page describes the technical design of Lab2patient ( | + | This page describes the technical design of Lab2patient (L2P) as a subset of the '''[[Lab:V3.0.0 Ontwerp Laboverdacht|Information standard lab exchange]]''' (Dutch: Labuitwisseling or abbreviated to LU). This technical specification is implementer centric and complements the '''[[Lab:V1.0_Ontwerp_Lab2Patient|functional design]]'''. This page uses various terms as defined in the [[Lab:V3.0.0 Ontwerp Laboverdacht#Begrippenlijst|glossary]]. |
− | + | ==Disclaimers== | |
+ | This page implements general principles applicable to FHIR as outlined by a central [[FHIR:V1.0_FHIR_IG_R4|FHIR IG for R4]]. Please make sure you familiarize yourself with both the functional design and the FHIR IG for full appreciation of the context of this page. | ||
− | + | This FHIR Implementation Guide assumes that systems (XIS) are able to make a connection to the right systems. It does not provide information on finding the right XIS nor does it provide information about security including authentication and authorization. Finding the right system, and security aspects of the connection, are dealt with by the infrastructure. Any relevant infrastructure is expected to have a framework in place to deal with this. The only assumption/requirement for an infrastructure is that this allows RESTful FHIR-based exchange as specified here. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | This FHIR | ||
=Boundaries and relationships= | =Boundaries and relationships= | ||
+ | ==Overview of relationships between FHIR resources== | ||
+ | [[Bestand:LaboratoryInFHIRR4Overview.png||Laboratory results in FHIR R4 overview]] | ||
==Mappings between profiles and data set== | ==Mappings between profiles and data set== | ||
− | Each transaction starts with links to the functional definition in an ART-DECOR publication and references one or several FHIR profiles. Where the functional definition contains all specific data elements for the transaction (prefixed with ‘lu-concept-v2’), the FHIR profiles only contain a mapping to these data elements that do not have a dependency on a zib counterpart. For example: ‘lu-concept-v2-4266’ (Specimen) has a relation with the zib element with id ‘NL-CM-13.1.2’, therefore no mapping with ‘lu-concept-v2-4266’ can be found in the profiles. On the other hand, ‘lu-concept-v2-4296’ (LaboratoryResultIdentification) has no relation with a zib element, therefore a mapping can be found in the relevant FHIR profile. | + | Each transaction starts with links to the [https://decor.nictiz.nl/ad/#/lu-/scenarios/scenarios/2.16.840.1.113883.2.4.3.11.60.25.3.5/2024-09-16T00:00:00 functional definition in an ART-DECOR publication] and references one or several FHIR profiles. Where the functional definition contains all specific data elements for the transaction (prefixed with ‘lu-concept-v2’), the FHIR profiles only contain a mapping to these data elements that do not have a dependency on a zib counterpart. For example: ‘lu-concept-v2-4266’ (Specimen) has a relation with the zib element with id ‘NL-CM-13.1.2’, therefore no mapping with ‘lu-concept-v2-4266’ can be found in the profiles. On the other hand, ‘lu-concept-v2-4296’ (LaboratoryResultIdentification) has no relation with a zib element, therefore a mapping can be found in the relevant FHIR profile. |
− | + | Cardinalities in FHIR profiles may be less strict than the ART-DECOR definitions. In this IG, transaction-level cardinalities take precedence. For example: in the nl-core-LaboratoryTestResult profile, {{fhir|.performer}} has a core cardinality of 0..*, while in both the 'Send laboratory results' and ‘Serve laboratory results’ ART-DECOR transactions, the Performer element has a cardinality of 1..1 M. Therefore, {{fhir|.performer}} is expected to be filled with a reference to an nl-core-HealthcareProvider-Organization resource. | |
Each transaction contains a Patient building block with cardinality 1..1 M. This patient is the subject of all other building blocks in the transaction, although no explicit relation exists in the data set. Therefore, a reference to a Patient resource conforming to the nl-core-Patient profile is expected in {{fhir|.subject}} of each FHIR instance of each building block. | Each transaction contains a Patient building block with cardinality 1..1 M. This patient is the subject of all other building blocks in the transaction, although no explicit relation exists in the data set. Therefore, a reference to a Patient resource conforming to the nl-core-Patient profile is expected in {{fhir|.subject}} of each FHIR instance of each building block. | ||
− | |||
− | |||
The single zib LaboratoryTestResult consists of objects that in FHIR are represented using different (instances of) resources: | The single zib LaboratoryTestResult consists of objects that in FHIR are represented using different (instances of) resources: | ||
Regel 49: | Regel 40: | ||
* ''NL-CM:13.1.29 SpecimenSource'' maps into profile {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult.Specimen.Source|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-LaboratoryTestResult.Specimen.Source}} {{fhir|Device}}. This is a special case where the specimen did not come from the Patient directly. | * ''NL-CM:13.1.29 SpecimenSource'' maps into profile {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult.Specimen.Source|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-LaboratoryTestResult.Specimen.Source}} {{fhir|Device}}. This is a special case where the specimen did not come from the Patient directly. | ||
− | == | + | ==FHIR relationship structures== |
− | + | Many laboratory results have important relationships to other observations and need to be grouped together. [http://hl7.org/fhir/r4/observation.html#10.1.4.1 The FHIR specification] defines several structures to do this: | |
− | + | * {{fhir|Observation.hasMember}} | |
− | + | ** Each {{fhir|.hasMember}} element references another Observation and the Observation with {{fhir|.hasMember}} elements thus serves as grouper for all Observations it references. Each Observation can be accessed individually. This is useful for panels and/or batteries of tests. | |
− | * | + | ** Note that while FHIR Observation also allows references to resource types MolecularSequence and QuestionnaireResponse, there is no identified use case for that at the time of writing. |
− | * Observation | + | ** An Observation without {{fhir|.hasMember}} elements is expected to be an individual result and has a value when one can be/is determined. |
− | + | * {{fhir|Observation.derivedFrom}} | |
− | An example of | + | ** Each {{fhir|.derivedFrom}} element references another Observation references related measurements the observation is made from. |
− | + | ** Note that while FHIR Observation also allows references to resource types DocumentReference, ImagingStudy, Media, QuestionnaireResponse and MolecularSequence, there is no identified use case for those at the time of writing. | |
− | + | * {{fhir|Observation.component}} | |
+ | ** {{fhir|.component}} elements of an Observation are not accessible individually. Whenever you access the Observation, you also access all its components. This is mostly useful when certain context is provided around the result. For lab observations this is expected to be less common. An example outside of the lab realm could be BloodPressure where systolic, diastolic, and cuff size are all in one Observation with 3 components. | ||
==Resource identification== | ==Resource identification== | ||
− | + | ART-DECOR transactions define a stricter cardinality of 1..1 R for resource identifiers. Therefore: | |
+ | * A stable identifier SHOULD be provided for each resource. | ||
+ | * If no identifier value is available, [[FHIR:V0.9_FHIR_IG_R4#Missing_information|the DataAbsentReason extension]] SHOULD be used. | ||
+ | * Identifiers SHALL contain both a {{fhir|.system}} and a {{fhir|.value}}. | ||
− | + | For compatibility with HL7v3 (CDA), where identifiers can only be represented as [[Hoofdpagina#Object_IDentifiers_.28OIDs.29|OIDs]]: | |
+ | * The {{fhir|.system}} SHALL be an OID to ensure compatibility in transformations to and from FHIR. | ||
+ | * The {{fhir|.system}} SHALL have a maximum of 128 characters. | ||
+ | * The {{fhir|.value}} SHALL have a maximum of 64 characters. | ||
− | Systems that encounter or resolve references, either logical or literal, in resources they receive, SHALL NOT rewrite these references to a copy of these resources (with {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/ext-CopyIndicator|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2}} present) they may store. This means that [https://hl7.org/fhir/r4/references.html relative literal references] | + | Regarding reference handling: |
+ | * Systems that encounter or resolve references, either logical or literal, in resources they receive, SHALL NOT rewrite these references to a copy of these resources (with {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/ext-CopyIndicator|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2}} present) they may store. | ||
+ | * This means that [https://hl7.org/fhir/r4/references.html relative literal references] MAY need to be rewritten to absolute ones. | ||
+ | * The same applies to [[FHIR:V1.0_FHIR_IG_R4#Including_.22secondary.22_resources_when_sending_information|included secondary resources in transactions]]. | ||
==FHIR Profile Package== | ==FHIR Profile Package== | ||
− | All use cases in this specification depend on the same set of FHIR profiles. The table below lists profiles that represent applicable zibs for laboratory result information exchange. | + | <!-- If you change this section title, also change the links to it on the pages ... --> |
+ | All use cases in this specification depend on the same set of FHIR profiles. FHIR profile package for Lab2Patient is currently in development. The table below lists profiles used within the framework of Lab2Zorg (Lab2Healthcare) that represent applicable zibs for laboratory result information exchange. | ||
{{NoteBoxNictizR4Package|p1=nictiz.fhir.nl.r4.labexchange|v1=3.0.0-beta.2|p2=nictiz.fhir.nl.r4.nl-core|v2=0.8.0-beta.1|p3=nictiz.fhir.nl.r4.zib2020|v3=0.6.0-beta.2}} | {{NoteBoxNictizR4Package|p1=nictiz.fhir.nl.r4.labexchange|v1=3.0.0-beta.2|p2=nictiz.fhir.nl.r4.nl-core|v2=0.8.0-beta.1|p3=nictiz.fhir.nl.r4.zib2020|v3=0.6.0-beta.2}} | ||
− | {| class="wikitable" style=" | + | {| class="wikitable" |
− | + | ! style="text-align:left;" | FHIR Profile | |
− | + | ! style="text-align:left;" | FHIR Resource | |
− | |FHIR Resource | + | ! style="text-align:left;" | Based on zib |
− | |||
|- | |- | ||
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-LaboratoryTestResult}} | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-LaboratoryTestResult}} | ||
| Observation | | Observation | ||
− | | rowspan="3" | | + | | rowspan="3" | [https://zibs.nl/wiki/LaboratoryTestResult-v4.6(2020EN) LaboratoryTestResult] |
|- | |- | ||
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult.Specimen|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-LaboratoryTestResult.Specimen}} | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult.Specimen|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-LaboratoryTestResult.Specimen}} | ||
Regel 90: | Regel 91: | ||
|- | |- | ||
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-Patient}} | | {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.6.0-beta.2|title=nl-core-Patient}} | ||
− | |Patient | + | | Patient |
− | |Patient | + | | [https://zibs.nl/wiki/Patient-v3.2(2020EN) Patient] |
|- | |- | ||
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization|nictiz.fhir.nl.r4.nl-core|title=nl-core-HealthcareProvider-Organization}} | | {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization|nictiz.fhir.nl.r4.nl-core|title=nl-core-HealthcareProvider-Organization}} | ||
− | |Organization | + | | Organization |
− | |HealthcareProvider | + | | [https://zibs.nl/wiki/HealthcareProvider-v3.4(2020EN) HealthcareProvider] |
|} | |} | ||
Regel 128: | Regel 129: | ||
==Patient retrieves laboratory results in their PGO== | ==Patient retrieves laboratory results in their PGO== | ||
===Introduction=== | ===Introduction=== | ||
− | + | This FHIR Implementation Guide assumes that the PHR system is able to make a connection to the right LIS that contains the patient's information. It does not provide information on finding the right LIS nor does it provide information about security. Moreover, each transaction is performed in the context of a specific authenticated patient, for whose context (token) has been established using the authentication mechanisms described in the [https://www.medmij.nl/afsprakenstelsel/ 'Afsprakenstelsel']. Each XIS Gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | Each | ||
− | |||
− | |||
===Actors=== | ===Actors=== | ||
− | {| class="wikitable | + | {| class="wikitable" |
− | ! style="text-align:left;"| | + | ! style="text-align:left;" | Transaction group |
− | ! style="text-align:left;"| | + | ! style="text-align:left;" | Transaction |
− | ! style="text-align:left;"| | + | ! style="text-align:left;" | Actor |
− | ! style="text-align:left;"| | + | ! style="text-align:left;" | Role |
|- | |- | ||
− | | | + | | rowspan="2" | Retrieve laboratory results (PULL) |
− | + | | Retrieve laboratory results request | |
− | + | | LaboratoriumresultaatResultaatRaadplegend Systeem [LAB-LRR-PGO] | |
− | + | | Send a query to the LAB-LRB-PGO to retrieve lab results | |
|- | |- | ||
− | + | | Retrieve laboratory results response | |
− | + | | LaboratoriumresultaatResultaatBeschikbaarstellend Systeem [LAB-LRB-PGO] | |
− | + | | Respond to a query from the LAB-LRR-PGO to retrieve lab results | |
|} | |} | ||
===Invocations=== | ===Invocations=== | ||
− | ====LAB-LRR: request message==== | + | ====LAB-LRR-PGO: request message==== |
− | The request message represents an HTTP GET parameterized query from the | + | The request message represents an HTTP GET parameterized query from the PHR (LAB-LRR-PGO) to the LIS (LAB-LRB-PGO). |
=====Trigger events===== | =====Trigger events===== | ||
− | When the | + | When the PHR wants to obtain laboratory results, it issues a retrieve laboratory results request message. |
=====Message semantics===== | =====Message semantics===== | ||
− | The | + | The PHR (LAB-LRR-PGO) executes an HTTP GET conforming to the FHIR [http://hl7.org/fhir/r4/http.html RESTful] and [http://hl7.org/fhir/r4/search.html search] specification against the LIS's Observation endpoint. Laboratory results are all under the {{fhir|.category}} ''observation'', using query parameter {{fhir|category}} as token. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
'''Basic query syntax''' | '''Basic query syntax''' | ||
− | <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory</pre> |
'''Examples''' | '''Examples''' | ||
Regel 186: | Regel 165: | ||
Parameter values have not been uri escaped in these examples for readability. This is likely necessary in practice. | Parameter values have not been uri escaped in these examples for readability. This is likely necessary in practice. | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get all lab results of type 14683-7 (LOINC) |
− | + | |- | |
+ | | <pre> | ||
+ | GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7 | ||
+ | </pre> | ||
+ | |} | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get all lab results of type 14683-7 (LOINC) since March 12, 2022 |
− | + | |- | |
+ | | <pre> | ||
+ | GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7&date=gt2022-03-12 | ||
+ | </pre> | ||
+ | |} | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get all lab results of type 14683-7 (LOINC) since March 12, 2022 but before June 7, 2022 |
− | + | |- | |
+ | | <pre> | ||
+ | GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7&date=gt2022-03-12&date=lt2022-06-07 | ||
+ | </pre> | ||
+ | |} | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get all lab results of type 14683-7 (LOINC) and/or 3583 (NHG) |
− | + | |- | |
+ | | <pre> | ||
+ | GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7,https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|3583 | ||
+ | </pre> | ||
+ | |} | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get latest lab result of type 14683-7 (LOINC) |
− | + | |- | |
+ | | <pre> | ||
+ | GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7 | ||
+ | </pre> | ||
+ | |} | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get latest 5 lab results of type 14683-7 (LOINC) |
− | + | |- | |
+ | | <pre> | ||
+ | GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7 | ||
+ | </pre> | ||
+ | |} | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed; |
− | <pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | + | ! style="text-align: left;" | Get latest lab result of any type |
− | + | |- | |
− | + | | <pre> | |
− | + | GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory | |
− | + | </pre> | |
− | + | |} | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
======Expected actions====== | ======Expected actions====== | ||
− | The | + | The LIS (LAB-LRB-PGO) SHALL process the query to retrieve laboratory results. |
− | ====LAB-LRB: response message==== | + | ====LAB-LRB-PGO: response message==== |
− | The | + | The LIS (LAB-LRB-PGO) returns an HTTP Status code appropriate to the processing as well as a FHIR Bundle including the matching information. Refer to the generic [[FHIR:V1.0_FHIR_IG_R4|FHIR IG]] for more information on handling errors and status codes. Not finding a match based on stated parameters does not constitute an error. |
=====Trigger events===== | =====Trigger events===== | ||
− | The | + | The LIS (LAB-LRB-PGO) completed the processing of the retrieve laboratory results request message. |
=====Message semantics===== | =====Message semantics===== | ||
− | The | + | The LIS (LAB-LRB-PGO) SHALL process the request and, unless an error is found, respond with a Bundle resource of type ''searchset''. Each Observation matching the request SHALL be marked with {{fhir|.entry.search.mode}}={{term|match}}. Each otherwise included resource SHALL be marked with {{fhir|.entry.search.mode}}={{term|include}}. If the searchset bundle contains less '''matching''' resources than the actual total set, then: |
* the {{fhir|Bundle.link}} that holds the self link, SHOULD include the {{fhir|_count}} parameter to inform the client of what max was applied | * the {{fhir|Bundle.link}} that holds the self link, SHOULD include the {{fhir|_count}} parameter to inform the client of what max was applied | ||
* an OperationOutcome SHOULD be included marked with {{fhir|.entry.search.mode}}={{term|outcome}}. | * an OperationOutcome SHOULD be included marked with {{fhir|.entry.search.mode}}={{term|outcome}}. | ||
Regel 254: | Regel 239: | ||
'''Example searchset Bundle''' | '''Example searchset Bundle''' | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed;" |
− | <syntaxhighlight lang="xml"> | + | ! style="text-align: left;" | XML contents for searchset Bundle |
+ | |- | ||
+ | | <syntaxhighlight lang="xml"> | ||
<Bundle xmlns="http://hl7.org/fhir"> | <Bundle xmlns="http://hl7.org/fhir"> | ||
<id value="1"/> | <id value="1"/> | ||
Regel 334: | Regel 321: | ||
</Bundle> | </Bundle> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | + | |} | |
'''Example OperationOutcome''' | '''Example OperationOutcome''' | ||
− | { | + | {| class="wikitable mw-collapsible mw-collapsed" style="width:100%; table-layout:fixed;" |
− | <syntaxhighlight lang="xml"> | + | ! style="text-align: left;" | XML contents for OperationOutcome |
+ | |- | ||
+ | | <syntaxhighlight lang="xml"> | ||
<OperationOutcome xmlns="http://hl7.org/fhir"> | <OperationOutcome xmlns="http://hl7.org/fhir"> | ||
<id value="size-exceeded-1"/> | <id value="size-exceeded-1"/> | ||
Regel 351: | Regel 340: | ||
</OperationOutcome> | </OperationOutcome> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | + | |} | |
− | |||
− | |||
− | |||
− | = | + | =====LAB-LRB-PGO: Expected actions===== |
− | + | The LIS (LAB-LRB-PGO) SHALL process the response Bundle in accordance with the intentions of the trigger event that caused the retrieve. Actions may include discrete rendering on screen or in context with other information, triggering alerts on trends, ordering of (other) tests and more. |
Huidige versie van 8 jul 2025 om 09:55
|
This IG is currently under development and can not be considered stable and ready for use. |

Inhoud
[verbergen]1 Introduction
This page describes the technical design of Lab2patient (L2P) as a subset of the Information standard lab exchange (Dutch: Labuitwisseling or abbreviated to LU). This technical specification is implementer centric and complements the functional design. This page uses various terms as defined in the glossary.
1.1 Disclaimers
This page implements general principles applicable to FHIR as outlined by a central FHIR IG for R4. Please make sure you familiarize yourself with both the functional design and the FHIR IG for full appreciation of the context of this page.
This FHIR Implementation Guide assumes that systems (XIS) are able to make a connection to the right systems. It does not provide information on finding the right XIS nor does it provide information about security including authentication and authorization. Finding the right system, and security aspects of the connection, are dealt with by the infrastructure. Any relevant infrastructure is expected to have a framework in place to deal with this. The only assumption/requirement for an infrastructure is that this allows RESTful FHIR-based exchange as specified here.
2 Boundaries and relationships
2.1 Overview of relationships between FHIR resources
2.2 Mappings between profiles and data set
Each transaction starts with links to the functional definition in an ART-DECOR publication and references one or several FHIR profiles. Where the functional definition contains all specific data elements for the transaction (prefixed with ‘lu-concept-v2’), the FHIR profiles only contain a mapping to these data elements that do not have a dependency on a zib counterpart. For example: ‘lu-concept-v2-4266’ (Specimen) has a relation with the zib element with id ‘NL-CM-13.1.2’, therefore no mapping with ‘lu-concept-v2-4266’ can be found in the profiles. On the other hand, ‘lu-concept-v2-4296’ (LaboratoryResultIdentification) has no relation with a zib element, therefore a mapping can be found in the relevant FHIR profile.
Cardinalities in FHIR profiles may be less strict than the ART-DECOR definitions. In this IG, transaction-level cardinalities take precedence. For example: in the nl-core-LaboratoryTestResult profile, .performer
has a core cardinality of 0..*, while in both the 'Send laboratory results' and ‘Serve laboratory results’ ART-DECOR transactions, the Performer element has a cardinality of 1..1 M. Therefore, .performer
is expected to be filled with a reference to an nl-core-HealthcareProvider-Organization resource.
Each transaction contains a Patient building block with cardinality 1..1 M. This patient is the subject of all other building blocks in the transaction, although no explicit relation exists in the data set. Therefore, a reference to a Patient resource conforming to the nl-core-Patient profile is expected in .subject
of each FHIR instance of each building block.
The single zib LaboratoryTestResult consists of objects that in FHIR are represented using different (instances of) resources:
- NL-CM:13.1.1 LaboratoryTestResult maps into profile nl-core-LaboratoryTestResult
Observation
and has.hasMember
relationships with individual NL-CM:13.1.3 LaboratoryTests.- Note that this level only exists when LaboratoryTestResult contains NL-CM:13.1.4 PanelOrBattery. The concepts NL-CM:13.1.7 ResultType, NL-CM:13.1.5 Comment, and NL-CM:13.1.6 ResultStatus are not mapped in the absence of NL-CM:13.1.4 PanelOrBattery.
- NL-CM:13.1.3 LaboratoryTest also maps into profile nl-core-LaboratoryTestResult
Observation
and MAY be referenced by a differentObservation.hasMember
containing NL-CM:13.1.1 LaboratoryTestResult. - NL-CM:13.1.2 Specimen maps into profile nl-core-LaboratoryTestResult.Specimen
Specimen
.- Note that there could be multiple instances of Specimen: one for the main NL-CM:13.1.16 SpecimenMaterial, and one per isolated NL-CM:13.1.22 Microorganism with a
.parent
relationship to the main specimen.
- Note that there could be multiple instances of Specimen: one for the main NL-CM:13.1.16 SpecimenMaterial, and one per isolated NL-CM:13.1.22 Microorganism with a
- NL-CM:13.1.29 SpecimenSource maps into profile nl-core-LaboratoryTestResult.Specimen.Source
Device
. This is a special case where the specimen did not come from the Patient directly.
2.3 FHIR relationship structures
Many laboratory results have important relationships to other observations and need to be grouped together. The FHIR specification defines several structures to do this:
Observation.hasMember
- Each
.hasMember
element references another Observation and the Observation with.hasMember
elements thus serves as grouper for all Observations it references. Each Observation can be accessed individually. This is useful for panels and/or batteries of tests. - Note that while FHIR Observation also allows references to resource types MolecularSequence and QuestionnaireResponse, there is no identified use case for that at the time of writing.
- An Observation without
.hasMember
elements is expected to be an individual result and has a value when one can be/is determined.
- Each
Observation.derivedFrom
- Each
.derivedFrom
element references another Observation references related measurements the observation is made from. - Note that while FHIR Observation also allows references to resource types DocumentReference, ImagingStudy, Media, QuestionnaireResponse and MolecularSequence, there is no identified use case for those at the time of writing.
- Each
Observation.component
.component
elements of an Observation are not accessible individually. Whenever you access the Observation, you also access all its components. This is mostly useful when certain context is provided around the result. For lab observations this is expected to be less common. An example outside of the lab realm could be BloodPressure where systolic, diastolic, and cuff size are all in one Observation with 3 components.
2.4 Resource identification
ART-DECOR transactions define a stricter cardinality of 1..1 R for resource identifiers. Therefore:
- A stable identifier SHOULD be provided for each resource.
- If no identifier value is available, the DataAbsentReason extension SHOULD be used.
- Identifiers SHALL contain both a
.system
and a.value
.
For compatibility with HL7v3 (CDA), where identifiers can only be represented as OIDs:
- The
.system
SHALL be an OID to ensure compatibility in transformations to and from FHIR. - The
.system
SHALL have a maximum of 128 characters. - The
.value
SHALL have a maximum of 64 characters.
Regarding reference handling:
- Systems that encounter or resolve references, either logical or literal, in resources they receive, SHALL NOT rewrite these references to a copy of these resources (with http://nictiz.nl/fhir/StructureDefinition/ext-CopyIndicator present) they may store.
- This means that relative literal references MAY need to be rewritten to absolute ones.
- The same applies to included secondary resources in transactions.
2.5 FHIR Profile Package
All use cases in this specification depend on the same set of FHIR profiles. FHIR profile package for Lab2Patient is currently in development. The table below lists profiles used within the framework of Lab2Zorg (Lab2Healthcare) that represent applicable zibs for laboratory result information exchange.
Nictiz uses the FHIR Packaging mechanism. This conveniently bundles all profiles, terminology, example material and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages:
Note: packages use Semantic Versioning. Other versions can be used at will as long as they have the same major.minor number or a minor number higher than the stated version. |
FHIR Profile | FHIR Resource | Based on zib |
---|---|---|
nl-core-LaboratoryTestResult | Observation | LaboratoryTestResult |
nl-core-LaboratoryTestResult.Specimen | Specimen | |
nl-core-LaboratoryTestResult.Specimen.Source | Device | |
nl-core-Patient | Patient | Patient |
nl-core-HealthcareProvider-Organization | Organization | HealthcareProvider |
3 Actors involved
Actors | Systems | FHIR CapabilityStatements | |||
---|---|---|---|---|---|
Name | Description | Name | Description | Name | Description |
Patient | The user of a personal healthcare environment. | PHR | Personal health record | CapabilityStatement: Lab2Healthcare-Results-RetrieveServe | Retrieve [LAB-LRR-PGO]/serve [LAB-LRB-PGO] lab results requirements. |
Lab Professional | The user of a LIS | LIS | Laboratory information system |
4 Use cases
4.1 Patient retrieves laboratory results in their PGO
4.1.1 Introduction
This FHIR Implementation Guide assumes that the PHR system is able to make a connection to the right LIS that contains the patient's information. It does not provide information on finding the right LIS nor does it provide information about security. Moreover, each transaction is performed in the context of a specific authenticated patient, for whose context (token) has been established using the authentication mechanisms described in the 'Afsprakenstelsel'. Each XIS Gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification.
4.1.2 Actors
Transaction group | Transaction | Actor | Role |
---|---|---|---|
Retrieve laboratory results (PULL) | Retrieve laboratory results request | LaboratoriumresultaatResultaatRaadplegend Systeem [LAB-LRR-PGO] | Send a query to the LAB-LRB-PGO to retrieve lab results |
Retrieve laboratory results response | LaboratoriumresultaatResultaatBeschikbaarstellend Systeem [LAB-LRB-PGO] | Respond to a query from the LAB-LRR-PGO to retrieve lab results |
4.1.3 Invocations
4.1.3.1 LAB-LRR-PGO: request message
The request message represents an HTTP GET parameterized query from the PHR (LAB-LRR-PGO) to the LIS (LAB-LRB-PGO).
4.1.3.1.1 Trigger events
When the PHR wants to obtain laboratory results, it issues a retrieve laboratory results request message.
4.1.3.1.2 Message semantics
The PHR (LAB-LRR-PGO) executes an HTTP GET conforming to the FHIR RESTful and search specification against the LIS's Observation endpoint. Laboratory results are all under the .category
observation, using query parameter category
as token.
Basic query syntax
GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
Examples
Parameter values have not been uri escaped in these examples for readability. This is likely necessary in practice.
UitvouwenGet all lab results of type 14683-7 (LOINC) |
---|
UitvouwenGet all lab results of type 14683-7 (LOINC) since March 12, 2022 |
---|
UitvouwenGet all lab results of type 14683-7 (LOINC) since March 12, 2022 but before June 7, 2022 |
---|
UitvouwenGet all lab results of type 14683-7 (LOINC) and/or 3583 (NHG) |
---|
UitvouwenGet latest lab result of type 14683-7 (LOINC) |
---|
UitvouwenGet latest 5 lab results of type 14683-7 (LOINC) |
---|
UitvouwenGet latest lab result of any type |
---|
4.1.3.1.2.1 Expected actions
The LIS (LAB-LRB-PGO) SHALL process the query to retrieve laboratory results.
4.1.3.2 LAB-LRB-PGO: response message
The LIS (LAB-LRB-PGO) returns an HTTP Status code appropriate to the processing as well as a FHIR Bundle including the matching information. Refer to the generic FHIR IG for more information on handling errors and status codes. Not finding a match based on stated parameters does not constitute an error.
4.1.3.2.1 Trigger events
The LIS (LAB-LRB-PGO) completed the processing of the retrieve laboratory results request message.
4.1.3.2.2 Message semantics
The LIS (LAB-LRB-PGO) SHALL process the request and, unless an error is found, respond with a Bundle resource of type searchset. Each Observation matching the request SHALL be marked with .entry.search.mode
=match. Each otherwise included resource SHALL be marked with .entry.search.mode
=include. If the searchset bundle contains less matching resources than the actual total set, then:
- the
Bundle.link
that holds the self link, SHOULD include the_count
parameter to inform the client of what max was applied - an OperationOutcome SHOULD be included marked with
.entry.search.mode
=outcome.
The resources in the response Bundle SHALL be a valid instance of their stated profile. All resources SHALL include their related profile canonical URL in the .meta.profile
element in order to show compliance. The exception is the OperationOutcome resource for which there is no profile in this specification.
Example searchset Bundle
UitvouwenXML contents for searchset Bundle |
---|
Example OperationOutcome
UitvouwenXML contents for OperationOutcome |
---|
4.1.3.2.3 LAB-LRB-PGO: Expected actions
The LIS (LAB-LRB-PGO) SHALL process the response Bundle in accordance with the intentions of the trigger event that caused the retrieve. Actions may include discrete rendering on screen or in context with other information, triggering alerts on trends, ordering of (other) tests and more.