Lab:V3.0.0 FHIR Lab2zorg: verschil tussen versies

Uit informatiestandaarden
Ga naar: navigatie, zoeken
 
(22 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
__NOINDEX__
+
{{DISPLAYTITLE:FHIR Lab2zorg V3.0.0-beta.1}}
  
{{DISPLAYTITLE:FHIR Lab2zorg V2.0.0}}
+
<imagemap>Bestand:functioneel-technisch-banner_00_alle.png|center|240px|alt=Functioneel-Technisch   
{{underconstruction}}
+
circle 204 216 215 [[Lab:V3.0.0 Ontwerp Lab2zorg|Functional]]
 
+
circle 990 216 215 [[Lab:V3.0.0 FHIR Lab2zorg|Technical]]
<imagemap>Bestand:functioneel-technisch-banner_00_alle.png|center|500px|alt=Functioneel-Technisch   
+
desc none                        
circle 241 216 211 [[Lab:V2.0.0_Ontwerp_Lab2zorg|Functional]]
 
circle 1013 224 212 [[FHIR:Vdraft_FHIR_IG_R4|Technical]]
 
desc none                  
 
 
</imagemap>
 
</imagemap>
  
Regel 13: Regel 10:
  
 
=Introduction=
 
=Introduction=
[[Bestand:Functioneel-02.png|link=Lab:V2.0.0_Ontwerp_Lab2zorg|100px|rechts|Functional design|Go to functional design]]
+
[[Bestand:Functioneel-02.png|link=Lab:V3.0.0_Ontwerp_Lab2zorg|100px|rechts|Functional design|Go to functional design]]
  
This page describes the technical design of Lab2Zorg (Lab2Healthcare) as a subset of the '''[[Lab:V3.0.0 Ontwerp Laboverdacht|Information standard lab exchange]]'''. This technical specification is implementer centric and complements the '''[[Lab:V2.0.0_Ontwerp_Lab2zorg|functional design]]'''. This page uses various terms as defined in the [[Lab:V3.0.0 Ontwerp Laboverdacht#Begrippenlijst|glossary]] (NL: Begrippenlijst). This page implements general principles applicable to FHIR as outlined by a central [[FHIR:Vdraft_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 page describes the technical design of Lab2zorg (Lab2healthcare) as a subset of the '''[[Lab:V3.0.0 Ontwerp Laboverdacht|Information standard lab exchange]]'''. This technical specification is implementer centric and complements the '''[[Lab:V3.0.0_Ontwerp_Lab2zorg|functional design]]'''. This page uses various terms as defined in the [[Lab:V3.0.0 Ontwerp Laboverdacht#Begrippenlijst|glossary]] (Dutch: Begrippenlijst). 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.
  
 
Many laboratory results have important relationships to other observations and need to be grouped together. [http://hl7.org/fhir/observation.html#10.1.4.1 The FHIR specification] defines several structures to do this:  
 
Many laboratory results have important relationships to other observations and need to be grouped together. [http://hl7.org/fhir/observation.html#10.1.4.1 The FHIR specification] defines several structures to do this:  
  
 
* {{fhir|Observation}} and one or more {{fhir|Observation.hasMember}} elements.
 
* {{fhir|Observation}} and one or more {{fhir|Observation.hasMember}} elements.
** Each {{fhir|.hasMember}} element references another Observation and the Observation with {{fhir|.hasMember}} elements thus serves as grouper for all Observation it references. Each Observation can be accessed individually. This is useful for panels and/or batteries of tests. This is what [https://zibs.nl/wiki/LaboratoryTestResult-v4.6(2020EN)#12870 NL-CM:13.1.3 LaboratoryTest] maps into.
+
** 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. This is what [https://zibs.nl/wiki/LaboratoryTestResult-v4.6(2020EN)#12870 NL-CM:13.1.3 LaboratoryTest] maps into.
** Note that while FHIR Observation also allows reference of resource types MolecularSequence | QuestionnaireResponse, there is no identified use case for that at time of writing.
+
** Note that while FHIR Observation also allows references to resource types MolecularSequence and QuestionnaireResponse, there is no identified use case for that at time of writing.
 
** An Observation without {{fhir|.hasMember}} elements is expected to be an individual result and has a value when one can be/is determined.
 
** 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}} and one or more {{fhir|Observation.derivedFrom}} elements.
 
* {{fhir|Observation}} and one or more {{fhir|Observation.derivedFrom}} elements.
 
** Each {{fhir|.derivedFrom}} element references another Observation references related measurements the observation is made from. This is what [https://zibs.nl/wiki/LaboratoryTestResult-v4.6(2020EN)#12849 NL-CM:13.1.33 RelatedResult::LaboratoryTestResult] maps into.
 
** Each {{fhir|.derivedFrom}} element references another Observation references related measurements the observation is made from. This is what [https://zibs.nl/wiki/LaboratoryTestResult-v4.6(2020EN)#12849 NL-CM:13.1.33 RelatedResult::LaboratoryTestResult] maps into.
** Note that while FHIR Observation also allows reference of resource types DocumentReference | ImagingStudy | Media | QuestionnaireResponse | MolecularSequence, there is no identified use case for those at time of writing.
+
** 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 time of writing.
 
* {{fhir|Observation}} and one or more {{fhir|Observation.component}} elements.
 
* {{fhir|Observation}} and one or more {{fhir|Observation.component}} elements.
** components 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 1 Observation with 3 components.
+
** {{fhir|.component}}s 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.
 +
 
 +
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.
 +
 
 +
=Boundaries and relationships=
 +
==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.
 +
 
 +
Because of [[FHIR:V1.0_FHIR_Profiling_Guidelines_R4#Open_vs._closed_world_modeling|open world modeling]], the cardinality of elements in the FHIR profiles can be less strict than the cardinalities in the ART-DECOR transactions. However, the latter cardinality is leading when it comes to exchanging building blocks in the context of a specific transaction. 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 either 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.
 +
 
 +
[[Bestand:LaboratoryInFHIRR4Overview.png|miniatuur|Laboratory results in FHIR R4 overview]]
  
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.
+
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 {{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}} {{fhir|Observation}} and has {{fhir|.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 {{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}} {{fhir|Observation}} and MAY be referenced by a different {{fhir|Observation.hasMember}} containing ''NL-CM:13.1.1 LaboratoryTestResult''.
 +
* ''NL-CM:13.1.2 Specimen'' maps into profile {{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}} {{fhir|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 {{fhir|.parent}} relationship to the main specimen.
 +
* ''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.
 +
 
 +
==Patient identification==
 +
This implementation guide assumes that the client system is able to make a connection to the right server that contains the patient's information. It does not provide information on finding the right server nor does it provide information about security. Moreover, each transaction is performed in the context of a specific (authenticated) patient, whose context might have been established using the authentication mechanisms described in external specifications such as the MedMij 'Afsprakenstelsel' or through the usage of search parameters for patient identification. Each server is required to perform filtering based on the patient associated with the context for the request or based on the patient identification search parameters, so only the records associated with the authenticated patient are returned.
 +
 
 +
When patient identification requires the use of search parameters, the following search parameters SHALL be supported:
 +
 
 +
* Patient: {{fhir|identifier}}
 +
* Observation: {{fhir|patient}}
 +
 
 +
An example of a request that retrieves all Observation resources of a patient with a fake BSN of 11122233:
 +
 
 +
<pre>GET [base]/Observation?patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
 +
 
 +
==Resource identification==
 +
All profiles used within the information standard contain {{fhir|.identifier}} elements with a cardinality of 0..* because of open world modeling. However, all ART-DECOR transactions referenced within this IG assign a 1..1 R cardinality, meaning a stable identifier SHOULD be provided, or [[FHIR:V0.9_FHIR_IG_R4#Missing_information|the DataAbsentReason extension if a value is missing]]. Identifiers SHALL contain both a {{fhir|.system}} and a {{fhir|.value}}.
 +
 
 +
Because in HL7v3 (CDA) an identifier can only be composed using [[Hoofdpagina#Object_IDentifiers_.28OIDs.29|OIDs]], the {{fhir|.system}} SHALL be an OID to accommodate compatibility in transformations to and from FHIR. The [https://www.hl7.nl/wiki/index.php?title=DatatypesR1:II Netherlands HL7v3 datatype II] also defines additional restrictions on the maximum length of both <code>@root</code> and <code>@extension</code> (equivalent to respectively {{fhir|.system}} and {{fhir|.value}} in FHIR). For the same compatibility reasons, {{fhir|.system}} SHALL have a maximum of 128 characters and {{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] may need to be rewritten to absolute ones. This also goes for [[FHIR:V1.0_FHIR_IG_R4#Including_.22secondary.22_resources_when_sending_information|included secondary resources in transactions]].
 +
 
 +
==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.
 +
 
 +
{{NoteBoxNictizR4Package|p1=nictiz.fhir.nl.r4.labexchange|v1=3.0.0-beta.1|p2=nictiz.fhir.nl.r4.nl-core|v2=0.6.0-beta.2|p3=nictiz.fhir.nl.r4.zib2020|v3=0.6.0-beta.2}}
 +
 
 +
{| class="wikitable" style="min-width:90%;"
 +
|-style="background-color:#1F497D; color:white; font-weight:bold;"
 +
|FHIR Profile
 +
|FHIR Resource
 +
|style="min-width:150px;"|Based on zib (EN)
 +
|-
 +
| {{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
 +
| rowspan="3" | LaboratoryResult
 +
|-
 +
| {{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}}
 +
| Specimen
 +
|-
 +
| {{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}}
 +
| Device
 +
|-
 +
| {{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
 +
|-
 +
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization|nictiz.fhir.nl.r4.nl-core|title=nl-core-HealthcareProvider-Organization}}
 +
|Organization
 +
|HealthcareProvider
 +
|}
  
 
=Actors involved=
 
=Actors involved=
Regel 48: Regel 112:
 
| rowspan="2" | LIS
 
| rowspan="2" | LIS
 
| rowspan="2" | Laboratory information system
 
| rowspan="2" | Laboratory information system
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/lab2healthcare-labclientcapabilities|nictiz.fhir.nl.r4.zib2020|title=CapabilityStatement: Lab Client}}
+
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-RetrieveServe|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.1|title=CapabilityStatement: Lab2Healthcare-Results-RetrieveServe}}
| Lab2Healthcare LIS client requirements
+
| Retrieve [LAB-LRR]/serve [LAB-LRB] lab results requirements. A LIS is only expected to serve results in the context of Lab2zorg.
 
|-
 
|-
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/lab2healthcare-labservercapabilities|nictiz.fhir.nl.r4.zib2020|title=CapabilityStatement: Lab Server}}
+
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-SendReceive|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.1|title=CapabilityStatement: Lab2Healthcare-Results-SendReceive}}
| Lab2Healthcare LIS server requirements
+
| Send [LAB-LRS]/receive [LAB-LRO] lab results requirements. A LIS is only expected to send results in the context of Lab2zorg.
 
|-
 
|-
 
| rowspan="2" | Healthcare professional
 
| rowspan="2" | Healthcare professional
Regel 58: Regel 122:
 
| rowspan="2" | XIS
 
| rowspan="2" | XIS
 
| rowspan="2" | (Any) Healthcare information system
 
| rowspan="2" | (Any) Healthcare information system
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/lab2healthcare-xisclientcapabilities|nictiz.fhir.nl.r4.zib2020|title=CapabilityStatement: XIS Client}}
+
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-RetrieveServe|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.1|title=CapabilityStatement: Lab2Healthcare-Results-RetrieveServe}}
| Lab2Healthcare XIS client requirements
+
| Retrieve [LAB-LRR]/serve [LAB-LRB] lab results requirements. A XIS may both retrieve results and serve copies of results in the context of Lab2zorg.
 
|-
 
|-
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/lab2healthcare-xisservercapabilities|nictiz.fhir.nl.r4.zib2020|title=CapabilityStatement: XIS Server}}
+
| [[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-SendReceive|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.1|title=CapabilityStatement: Lab2Healthcare-Results-SendReceive}}
| Lab2Healthcare XIS server requirements
+
| Send [LAB-LRS]/receive [LAB-LRO] lab results requirements. A XIS may both send copies of results and receive (copies of) results in the context of Lab2zorg.
 
|}
 
|}
  
=Use case: Health professional sends order to lab and receives result from lab=
+
=Use cases=
'''TODO'''
+
==Health professional orders lab tests and receives results==
 +
''This use case will be added in a future release.''
 +
==Health professional retrieves lab results==
 +
===Introduction===
 +
Healthcare professionals need to be able to retrieve laboratory results directly from a lab (LIS) or a secondary healthcare provider (XIS). Different healthcare professionals may have different needs and/or authorizations. The core FHIR specification offers support for a lot of use cases. This specification only outlines options for the identified scope and associated minimal expectations. As such it is ''not'' intended to be limiting to said expectations. Servers SHALL use the CapabilityStatement to advertise their implementation and clients SHOULD use this as means to discover the servers capabilities as per the FHIR specification, as well as publish their own capabilities. <nowiki>[</nowiki>[http://hl7.org/fhir/R4/http.html#3.1.0 FHIR RESTful]<nowiki>]</nowiki> / <nowiki>[</nowiki>[http://hl7.org/fhir/R4/capabilitystatement.html#notes CapabilityStatement]<nowiki>]</nowiki>.
  
=Use case: Health professional retrieves lab results=
+
The identified use cases within the scope of this implementation guide are very broad:
'''DO'''
 
  
=Use case: Health professional sends lab results to other health professional=
+
* Get latest X results for one or more specific {{fhir|Observation.code}}s
The functional design distinguishes two use cases where lab results may be sent with something else or separate. The process of 'sending' things in FHIR works by means of a [http://hl7.org/fhir/r4/http.html#create RESTful 'create'] action. You could create a single Observation on another system using {{fhir|POST Observation}} and the appropriate Observation in the request body. When you have multiple Observations to create, you could do that for every single Observation, or by means of a Bundle with all resources. This same Bundle approach works for one Observation too.  
+
* Get latest X results for any {{fhir|Observation.code}}s
 +
* Get results on/before/after date X
 +
* Get results on/before/after date X for one or more specific {{fhir|Observation.code}}s
 +
 
 +
Each server SHALL perform filtering based on the patient, and results associated with the request context and patient identification search parameters, so only the records are returned that the requesting party is authorized for. Example expectations are that any ordering provider will have access to results related to his orders, and any requesting party interested in medication related results only has access to those.
  
The added benefit from a Bundle lies in having a solution for all other resources you may want to send, e.g. MedicationRequest, and referenced resources, e.g. Patient and PractitionerRole | Practitioner | Organization. Sending the Observation without the things it references would only work if the receiving server can resolve those. They should then already exist on that server, with references to them or they should be accessible on the source. Without access to the references in the Observation, the target server may not know which patient is involved or what lab this result came from.
+
A special word of caution about volume. It has been proven hard to impossible to define an optimum on how much history should be supported. For example some genetic tests are done once at age 15, and are still valid at age 80. Returning ''all'' results for someone age 80 could take an enormous toll on both server and client and is seldom relevant. Clients are therefore encouraged to be as specific as possible, by using both {{fhir|code}} and/or {{fhir|date}} and/or [https://www.hl7.org/fhir/search.html#count {{fhir|_count}}] whenever possible. Servers SHOULD implement [https://www.hl7.org/fhir/search.html#count {{fhir|_count}}], and SHOULD implement an OperationOutcome that informs the client of a partial result set when the total number exceeds what a server will handle.
  
==Actors==
+
===Actors===
 
{| class="wikitable" "cellpadding="10"
 
{| class="wikitable" "cellpadding="10"
 
! style="text-align:left;"| '''Transaction group'''
 
! style="text-align:left;"| '''Transaction group'''
Regel 83: Regel 154:
 
! style="text-align:left;"| '''Role'''
 
! style="text-align:left;"| '''Role'''
 
|-
 
|-
|style="background-color: white;vertical-align:top;" rowspan="2"|Send Laboratory Results(PUSH)
+
|style="background-color: white;vertical-align:top;" rowspan="2"|Retrieve laboratory results (PULL)
|style="background-color: white;vertical-align:top;"|Send laboratory results
+
|style="background-color: white;vertical-align:top;"|Retrieve laboratory results request
|style="background-color: white;vertical-align:top;"|Healthcare professional (using an XIS)
+
|style="background-color: white;vertical-align:top;"|LaboratoriumresultaatResultaatRaadplegend Systeem [LAB-LRR]
|style="background-color: white;vertical-align:top;"|Send laboratory results to another XIS
+
|style="background-color: white;vertical-align:top;"|Send a query to the LAB-LRB to retrieve lab results
 
|-
 
|-
|style="background-color: white;vertical-align:top;"|Send laboratory results
+
|style="background-color: white;vertical-align:top;"|Retrieve laboratory results response
|style="background-color: white;vertical-align:top;"|Healthcare professional (using an XIS)
+
|style="background-color: white;vertical-align:top;"|LaboratoriumresultaatResultaatBeschikbaarstellend Systeem [LAB-LRB]
|style="background-color: white;vertical-align:top;"|Receive laboratory results from another XIS
+
|style="background-color: white;vertical-align:top;"|Respond to a query from the LAB-LRR to retrieve lab results
 
|}
 
|}
  
==Invocations==
+
===Invocations===
===XIS: request message===
+
====LAB-LRR: request message====
The send lab results request message uses the HTTP POST method on the target XIS's base. Note that lab results may or may not be sent in tandem with other resources like MedicationRequest. The same principles apply with or without these other resources. The server can only process the incoming request correctly if it understands what is being sent which includes being able to resolve references.
+
The request message represents an HTTP GET parameterized query from the XIS (LAB-LRR) to the XIS/LIS (LAB-LRB).
 +
 
 +
=====Trigger events=====
 +
When the healthcare professional wants to obtain laboratory results, it issues a retrieve laboratory results request message.
 +
 
 +
=====Message semantics=====
 +
The XIS (LAB-LRR) executes an HTTP GET conforming to the FHIR [http://hl7.org/fhir/http.html RESTful] and [http://hl7.org/fhir/search.html search] specification against the XIS/LIS's Observation endpoint.  
  
====Trigger Events====
+
* Laboratory results are all under the {{fhir|.category}} ''observation'', using query parameter {{fhir|category}} as token.
This message is invoked when the XIS needs to send one or more lab results observations to another XIS.
+
* Requesting data for a specific {{fhir|.subject}} is done using query parameter {{fhir|patient}} as reference, or on some network infrastructures with an authorization token. The FHIR query parameter type [https://www.hl7.org/fhir/R4/search.html#reference reference] can take on many forms.
 +
** If you know what the {{fhir|Patient.id}} is, e.g. from previous interactions with the same endpoint, you may use:
 +
*** {{fhir|<nowiki>patient=[id]</nowiki>}}
 +
*** {{fhir|<nowiki>patient=[type]/[id]</nowiki>}}
 +
*** {{fhir|<nowiki>patient=[url]</nowiki>}}
 +
** If you don't know what the {{fhir|Patient.id}} is, but you know the {{fhir|Patient.identifier}}, e.g. the Burgerservicenummer (BSN), you may use:
 +
*** {{fhir|<nowiki>patient:identifier=[system]|[value]</nowiki>}}
 +
* Requesting laboratory results of a specific type is done using query parameter {{fhir|code}} as token.
 +
* Requesting laboratory results of a specific date (range) is done using query parameter {{fhir|date}} as token.
  
====Message Semantics====
+
'''Basic query syntax'''
Because sending laboratory results will most likely consist of multiple Observations, a {{fhir|batch}} operation is used. This allows for creating a set of resources in a single interaction and makes it possible to [[FHIR:Vdraft_FHIR_IG_R4#Referring_other_resources_when_sending_information|include referenced secondary resources]] if needed.
+
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory{&patient=Patient/[id] | &patient:identifier=[system]|[value]}{&[parameter(s)]&_include=[resource(s)]}</pre>
  
A {{term|batch}} interaction is performed by an HTTP POST command as shown:
+
'''Examples'''
  
<pre>POST [base]</pre>
+
Parameter values have not been uri escaped in these examples for readability. This is likely necessary in practice.
 +
 
 +
{{Collapse top|Get all lab results of type 14683-7 (LOINC) for patient with BSN 111222333}}
 +
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
 +
{{Collapse bottom}}
 +
 
 +
{{Collapse top|Get all lab results of type 14683-7 (LOINC) for patient with BSN 111222333 since March 12, 2022}}
 +
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-03-12</pre>
 +
{{Collapse bottom}}
 +
 
 +
{{Collapse top|Get all lab results of type 14683-7 (LOINC) for patient with BSN 111222333 since March 12, 2022 but before June 7, 2022}}
 +
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-03-12&date=lt2022-06-07</pre>
 +
{{Collapse bottom}}
 +
 
 +
{{Collapse top|Get all lab results of type 14683-7 (LOINC) and/or 3583 (NHG) for patient with BSN 111222333}}
 +
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7,https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|3583</pre>
 +
{{Collapse bottom}}
 +
 
 +
{{Collapse top|Get latest lab result of type 14683-7 (LOINC) for patient with BSN 111222333}}
 +
<pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
 +
{{Collapse bottom}}
 +
 
 +
{{Collapse top|Get latest 5 lab results of type 14683-7 (LOINC) for patient with BSN 111222333}}
 +
<pre>GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
 +
{{Collapse bottom}}
 +
 
 +
{{Collapse top|Get latest lab result of any type for patient with BSN 111222333}}
 +
<pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
 +
{{Collapse bottom}}
 +
 
 +
'''Query parameters overview'''
 +
 
 +
Servers SHALL at minimum support all stated parameters and modifiers, and MAY support additional parameters and modifiers. Clients SHALL support required parameters, and MAY support optional parameters.
 +
* {{fhir|category}} - token - 1..1 required - fixed value ''<nowiki>http://terminology.hl7.org/CodeSystem/observation-category|laboratory</nowiki>''
 +
* {{fhir|patient}} - token - 0..1 conditional - required if not solved using an alternative method like an authorization token
 +
** Modifier {{fhir|:identifier}} - 0..1 optional - required when searching by identifier
 +
* {{fhir|code}} - token - 0..1 optional
 +
* {{fhir|date}} - date - 0..1 optional
 +
** Prefix {{fhir|eq}} - 0..1 optional - required when searching for results with {{fhir|.effective}} on exact date
 +
** Prefix {{fhir|lt}} - 0..1 optional - required when searching for results with {{fhir|.effective}} before date
 +
** Prefix {{fhir|le}} - 0..1 optional - required when searching for results with {{fhir|.effective}} on or before date
 +
** Prefix {{fhir|gt}} - 0..1 optional - required when searching for results with {{fhir|.effective}} after date
 +
** Prefix {{fhir|ge}} - 0..1 optional - required when searching for results with {{fhir|.effective}} on or after date
 +
* {{fhir|_count}} - positiveInt - 0..1 optional
 +
* {{fhir|_include}} - reference - 0..* optional - useful for request to include secondary related resources, e.g.:<br/>{{fhir|<nowiki>_include=Observation:patient,Observation:performer,Observation:has-member,Observation:specimen</nowiki>}}
 +
** Note that servers MAY, depending on their read capabilities, choose to implement inclusion of resources regardless of a client requesting this to satisfy the [[FHIR:V1.0_FHIR_IG_R4|generic requirement]] that references SHALL be resolvable.
 +
 
 +
'''Operations'''
 +
 
 +
* [https://www.hl7.org/fhir/R4/observation-operation-lastn.html {{fhir|lastn}}] - shortcut FHIR core operation for getting the latest X results of specified types, or 'any' type
 +
** Parameter {{fhir|max}} - positiveInt - optional - default is {{fhir|<nowiki>max=1</nowiki>}}
 +
 
 +
======Expected actions======
 +
The XIS/LIS (LAB-LRB) SHALL process the query to retrieve laboratory results.
 +
 
 +
====LAB-LRB: response message====
 +
The XIS/LIS (LAB-LRB) 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=====
 +
The XIS/LIS (LAB-LRB) completed the processing of the retrieve laboratory results request message.
 +
 
 +
=====Message semantics=====
 +
The XIS/LIS (LAB-LRB) 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
 +
* an OperationOutcome SHOULD be included marked with {{fhir|.entry.search.mode}}={{term|outcome}}.
 +
 
 +
The resources in the response Bundle SHALL be a valid instance of their stated [[#FHIR_Profile_Package|profile]]. All resources SHALL include their related profile canonical URL in the {{fhir|.meta.profile}} element in order to show compliance. The exception is the OperationOutcome resource for which there is no profile in this specification.
  
The body of the post submission is a Bundle with {{fhir|Bundle.type}}={{term|batch}}. Each entry carries request details ({{fhir|Bundle.entry.request}}) that provides the HTTP details of the action in order to inform the system processing the batch or what to do for the entry. (Note: {{fhir|.request}} SHALL be present, even for the resources which aren't Observations. See [[FHIR:Vdraft_FHIR_IG_R4#Referring_other_resources_when_sending_information|the overarching principles]] for more information.)
+
'''Example searchset Bundle'''
  
'''Identification:'''
+
{{Collapse top|XML contents for searchset Bundle}}
 +
<syntaxhighlight lang="xml">
 +
<Bundle xmlns="http://hl7.org/fhir">
 +
    <id value="1"/>
 +
    <type value="searchset"/>
 +
    <total value="3"/>
 +
    <link>
 +
        <relation value="self"/>
 +
        <url value="http://example.org/fhir?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&amp;patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&amp;code=http://loinc.org|14683-7"/>
 +
    </link>
 +
    <entry>
 +
        <fullUrl value="https://example.org/fhir/Observation/1"/>
 +
        <resource>
 +
            <Observation>
 +
                <!--  -->
 +
            </Observation>
 +
        </resource>
 +
        <search>
 +
            <mode value="match"/>
 +
        </search>
 +
    </entry>
 +
    <entry>
 +
        <fullUrl value="https://example.org/fhir/Observation/2"/>
 +
        <resource>
 +
            <Observation>
 +
                <!--  -->
 +
            </Observation>
 +
        </resource>
 +
        <search>
 +
            <mode value="match"/>
 +
        </search>
 +
    </entry>
 +
    <entry>
 +
        <fullUrl value="https://example.org/fhir/Observation/3"/>
 +
        <resource>
 +
            <resource>
 +
                <Observation>
 +
                    <!--  -->
 +
                </Observation>
 +
            </resource>
 +
        </resource>
 +
        <search>
 +
            <mode value="match"/>
 +
        </search>
 +
    </entry>
 +
    <entry>
 +
        <fullUrl value="https://example.org/fhir/Specimen/1"/>
 +
        <resource>
 +
            <Specimen>
 +
                <!--  -->
 +
            </Specimen>
 +
        </resource>
 +
        <search>
 +
            <mode value="include"/>
 +
        </search>
 +
    </entry>
 +
    <entry>
 +
        <fullUrl value="https://example.org/fhir/Patient/1"/>
 +
        <resource>
 +
            <Patient>
 +
                <!--  -->
 +
            </Patient>
 +
        </resource>
 +
        <search>
 +
            <mode value="include"/>
 +
        </search>
 +
    </entry>
 +
    <entry>
 +
        <fullUrl value="https://example.org/fhir/Organization/1"/>
 +
        <resource>
 +
            <Organization>
 +
                <!--  -->
 +
            </Organization>
 +
        </resource>
 +
        <search>
 +
            <mode value="include"/>
 +
        </search>
 +
    </entry>
 +
</Bundle>
 +
</syntaxhighlight>
 +
{{Collapse bottom}}
  
Sending systems SHALL have a stable identifier in the {{fhir|.identifier}} element for all Observation resources. Having stable identification is essential in detection of duplicates and potential clinical decision making issues deriving from duplicates. For more information on dealing with identifiers, see the [[FHIR:Vdraft_FHIR_IG_R4#Usage_of_the_.id.2C_.identifier_and_.fullUrl_elements_in_FHIR_instances|general FHIR IG]].
+
'''Example OperationOutcome'''
  
'''Links:'''
+
{{Collapse top|XML contents for OperationOutcome}}
 +
<syntaxhighlight lang="xml">
 +
<OperationOutcome xmlns="http://hl7.org/fhir">
 +
    <id value="size-exceeded-1"/>
 +
    <issue>
 +
        <severity value="warning"/>
 +
        <code value="too-costly"/>
 +
        <details>
 +
            <text value="Resultaat was 3000, wat meer is dan het maximum van 1000"/>
 +
        </details>
 +
    </issue>
 +
</OperationOutcome>
 +
</syntaxhighlight>
 +
{{Collapse bottom}}
  
* [http://hl7.org/fhir/R4/http.html#batch batch]
+
=====LAB-LRR: Expected actions=====
* [http://hl7.org/fhir/R4/http.html#create create]
+
The XIS/LIS (LAB-LRR) 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.
  
The laboratory result data sent to the XIS SHALL conform to the matching LaboratoryResult based profile. The table below lists profiles that represent applicable zibs for laboratory result information exchange.
+
==Health professional sends lab results to other health professional==
 +
===Introduction===
 +
The functional design distinguishes two use cases where lab results may be sent with something else or separate. The process of 'sending' things in FHIR works by means of a [http://hl7.org/fhir/r4/http.html#create RESTful 'create'] action. You could create a single Observation on another system using {{fhir|POST Observation}} and the appropriate Observation in the request body. When you have multiple Observations to create, you could do that for every single Observation, or by means of a Bundle with all resources. This same Bundle approach works for one Observation too.  
  
{{MedMij:V2020.01/NoteBoxPackage|p1=nictiz.fhir.nl.r4.zib2020}}
+
The added benefit of a Bundle lies in having a solution for all other resources you may want to send, e.g. MedicationRequest, and referenced resources like Patient, PractitionerRole, Practitioner and Organization. Sending the Observation without the resources it references would only work if the receiving server can resolve those. They should then already exist on that server, with references to them or they should be accessible on the source. Without access to the references in the Observation, the target server may not know which patient is involved or what lab this result came from.
  
{| class="wikitable"  
+
===Actors===
|-style="background-color: #1F497D; color: white; font-weight: bold; "
+
{| class="wikitable" "cellpadding="10"
|style="width:150px;"|Zib NL||style="width:150px;"|HCIM EN||style="width:150px;"|FHIR Resource||style="width:450px;"|FHIR Profile
+
! style="text-align:left;"| '''Transaction group'''
|-style="vertical-align:top; background-color: #E3E3E3;
+
! style="text-align:left;"| '''Transaction'''
 +
! style="text-align:left;"| '''Actor'''
 +
! style="text-align:left;"| '''Role'''
 
|-
 
|-
| Patiënt (M)||Patient||Patient||{{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient|nictiz.fhir.nl.r4.zib2020}}
+
|style="background-color: white;vertical-align:top;" rowspan="2"|Send laboratory results (PUSH)
|-
+
|style="background-color: white;vertical-align:top;"|Send laboratory results
| Zorgverlener (M)||HealthProfessional||Practitioner||{{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner|nictiz.fhir.nl.r4.zib2020}}<br/>{{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole|nictiz.fhir.nl.r4.zib2020}}
+
|style="background-color: white;vertical-align:top;"|LaboratoriumresultaatResultaatSturend Systeem [LAB-LRS]
 +
|style="background-color: white;vertical-align:top;"|Send lab results to the LAB-LRO
 
|-
 
|-
| LaboratoriumUitslag (based on) (M)||LaboratoryTestResult (based on)||Observation||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-laboratorytest|nictiz.fhir.nl.r4.zib2020}}
+
|style="background-color: white;vertical-align:top;"|Receive laboratory results
 +
|style="background-color: white;vertical-align:top;"|LaboratoriumresultaatResultaatOntvangend Systeem [LAB-LRO]
 +
|style="background-color: white;vertical-align:top;"|Respond to received lab results from the LAB-LRS
 
|}
 
|}
  
=====Expected Actions=====
+
===Invocations===
On receipt of the submission, the XIS SHALL:
+
====LAB-LRS: request message====
 +
The XIS/LIS (LAB-LRS) sends lab results using the HTTP POST method on the target XIS's (LAB-LRO) base. Note that lab results may or may not be sent in tandem with other resources like MedicationRequest. The same principles apply with or without these other resources. The server can only process the incoming request correctly if it understands what is being sent which includes being able to resolve references.
 +
 
 +
=====Trigger Events=====
 +
This message is invoked when the XIS needs to send one or more laboratory results to another XIS.
 +
 
 +
=====Message Semantics=====
 +
Because sending laboratory results will most likely consist of multiple Observations, a {{term|transaction}} interaction is used. This allows for creating a set of resources in a single interaction and makes it possible to [[FHIR:V1.0_FHIR_IG_R4#Referring_other_resources_when_sending_information|include referenced secondary resources]] if needed.
 +
 
 +
A {{term|transaction}} interaction is performed by an HTTP POST command as shown:
 +
 
 +
<pre>POST [base]</pre>
 +
 
 +
The body of the post submission is a Bundle with {{fhir|Bundle.type}}={{term|transaction}}. Each entry carries request details ({{fhir|Bundle.entry.request}}) that provides the HTTP details of the action in order to inform the system processing the transaction of what to do for the entry. (Note: {{fhir|.request}} SHALL be present, even for the resources which aren't Observations. See [[FHIR:V1.0_FHIR_IG_R4#Referring_other_resources_when_sending_information|the overarching principles]] for more information.)
 +
 
 +
'''Identification'''
 +
 
 +
Resources SHALL have a stable identifier in the {{fhir|.identifier}} element for all resources if such an identifier exists in the underlying data. Not all data, like individual results, are currently known to have identifiers in all source systems, but when they exist they are essential and where they do not exist yet they SHOULD be considered. Having stable identification is essential in detection of duplicates and potential clinical decision making issues deriving from duplicates. For more information on dealing with identifiers, see the [[FHIR:V1.0_FHIR_IG_R4#Usage_of_the_.id.2C_.identifier_and_.fullUrl_elements_in_FHIR_instances|general FHIR IG]].
 +
 
 +
'''Read more'''
 +
 
 +
* [http://hl7.org/fhir/R4/http.html#transaction transaction]
 +
* [http://hl7.org/fhir/R4/http.html#create create]
 +
* [http://hl7.org/fhir/R4/http.html#ops HTTP Prefer header]
 +
 
 +
The laboratory result data sent to the XIS SHALL conform to the matching profile(s) listed in the [[#FHIR_Profile_Package|profile]] table. That table contains profiles that represent applicable zibs for laboratory result information exchange.
 +
 
 +
======Expected Actions======
 +
On receipt of the submission, the XIS (LAB-LRO) SHALL:
  
* process creation of all Observation resources successfully or process no Observation
+
* process all contained requests successfully or process nothing.
* match Patient, Practitioner(Role), Organization to pre-existing resources on that server
+
* process creation of or updating all Observation resources.
** The server MAY update pre-existing information with the incoming information
+
** Updating might be in order e.g. when corrections are sent or when previously pending tests have been updated with results.
** The server MAY keep its pre-existing matching resources as-is
+
* match Patient, Practitioner(Role), Organization to pre-existing resources on its server.
** The server SHALL create new resources if no matching resource is found (unknown patient, new physician in otherwise known organization, etc.)
+
** The server MAY update pre-existing information with the incoming information.
* decide if any available Specimen resources are relevant
+
** The server MAY keep its pre-existing matching resources as-is.
** If the server decides to ignore Specimen information, it SHALL not keep the {{fhir|Observation.specimen}} reference
+
** The server SHALL create new resources if no matching resource is found (unknown patient, new physician in otherwise known organization, etc.).
* respond using HTTP 200 and a Bundle with detail in case of success. See [[FHIR:Vdraft_FHIR_IG_R4#Handling_errors|FHIR IG Handling Errors]] for response options in case of errors
+
* decide if any available Specimen and/or Device resources are relevant.
** Note that the response Bundle with type {{term|batch-response}} SHALL be specific about how the server handled the request Bundle.  
+
** If the server decides to ignore Specimen or Device information, it SHALL not keep the references to them.
 +
* respond using HTTP 200 and a Bundle with detail in case of success. See [[FHIR:V1.0_FHIR_IG_R4#Handling_errors|FHIR IG Handling Errors]] for response options in case of errors.
 +
** Note that the response Bundle with type {{term|transaction-response}} SHALL be specific about how the server handled the request Bundle.
  
===XIS: response message===
+
====LAB-LRO: response message====
The XIS returns an HTTP Status code appropriate to the processing outcome and returns a Bundle, of type {{term|batch-response}}, that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry.
+
The XIS (LAB-LRO) returns an HTTP Status code appropriate to the processing outcome and returns a Bundle with {{fhir|Bundle.type}}={{term|batch-response}}, that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry.
  
====Trigger Events====
+
=====Trigger Events=====
The XIS completed processing of the send laboratory results request message.
+
The XIS (LAB-LRO) completed processing of the send laboratory results message.
  
====Message Semantics====
+
=====Message Semantics=====
The XIS SHALL return a Bundle with type set to batch-response that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry.
+
The XIS (LAB-LRO) SHALL return a Bundle with {{fhir|Bundle.type}}={{term|batch-response}} that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry.
  
A client may use the returned Bundle to track the outcomes of processing the entry, and the identities assigned to the resources by the server. Each entry element SHALL contain a response element which details the outcome of processing the entry - the HTTP status code, and the location and ETag header values, which are used for identifying and versioning the resources. In addition, a resource may be included in the entry, as specified by the Prefer header.
+
A client may use the returned Bundle to track the outcomes of processing the entry, and the identities assigned to the resources by the server. Each entry element SHALL contain a response element which details the outcome of processing the entry - the HTTP status code, and the location and {{fhir|ETag}} header values, which are used for identifying and versioning the resources. In addition, a resource may be included in the entry, as specified by the {{fhir|Prefer}} header sent by the LAB-LRS.
  
 
Read more:
 
Read more:
[http://hl7.org/fhir/R4/http.html#create create]
+
* [http://hl7.org/fhir/R4/http.html#create create]
[http://hl7.org/fhir/R4/http.html#batch batch]
+
* [http://hl7.org/fhir/R4/http.html#batch batch]
 +
* [http://hl7.org/fhir/R4/http.html#ops HTTP Prefer header]
 +
* [http://hl7.org/fhir/http.html#versioning HTTP ETag header]
  
====Expected Actions====
+
=====Expected Actions=====
The XIS server processes the results according to application-defined rules.
+
The XIS/LIS (LAB-LRS) processes the results according to application-defined rules. The most basic of those rules would include marking the transaction as sent/processed successfully or flag a need for action like resending or contacting the LAB-LRO.
  
====Handling Errors====
+
=====Handling Errors=====
The server may be unable to accept a Bundle due to errors or because of business rules (e.g. because of an unsupported code value in an Observation resource). Refer to the [FHIR:Vdraft_FHIR_IG_R4#Handling_errors#Handling_errors Handling Errors section] in the FHIR IG for more information.
+
The XIS (LAB-LRO) may be unable to accept a Bundle due to errors or because of technical or business rules. Refer to the [[FHIR:V1.0_FHIR_IG_R4#Handling_errors#Handling_errors|Handling Errors section]] in the FHIR IG for more information.
  
=Use case: Health professional reports result leading into a notification "new lab results" for subscribed healthcare professional(s)=
+
==Health professional reports result leading into a notification "new lab results" for subscribed healthcare professional(s)==
'''DO'''
+
''This use case will be added in a future release.''

Huidige versie van 26 aug 2022 om 12:42


FunctionalTechnicalFunctioneel-Technisch


1 Introduction

Go to functional design

This page describes the technical design of Lab2zorg (Lab2healthcare) as a subset of the Information standard lab exchange. This technical specification is implementer centric and complements the functional design. This page uses various terms as defined in the glossary (Dutch: Begrippenlijst). 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.

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 and one or more Observation.hasMember elements.
    • 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. This is what NL-CM:13.1.3 LaboratoryTest maps into.
    • Note that while FHIR Observation also allows references to resource types MolecularSequence and QuestionnaireResponse, there is no identified use case for that at 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.
  • Observation and one or more Observation.derivedFrom elements.
    • Each .derivedFrom element references another Observation references related measurements the observation is made from. This is what NL-CM:13.1.33 RelatedResult::LaboratoryTestResult maps into.
    • 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 time of writing.
  • Observation and one or more Observation.component elements.
    • .components 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.

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 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.

Because of open world modeling, the cardinality of elements in the FHIR profiles can be less strict than the cardinalities in the ART-DECOR transactions. However, the latter cardinality is leading when it comes to exchanging building blocks in the context of a specific transaction. 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 either 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.

Laboratory results in FHIR R4 overview

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 different Observation.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.
  • 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.2 Patient identification

This implementation guide assumes that the client system is able to make a connection to the right server that contains the patient's information. It does not provide information on finding the right server nor does it provide information about security. Moreover, each transaction is performed in the context of a specific (authenticated) patient, whose context might have been established using the authentication mechanisms described in external specifications such as the MedMij 'Afsprakenstelsel' or through the usage of search parameters for patient identification. Each server is required to perform filtering based on the patient associated with the context for the request or based on the patient identification search parameters, so only the records associated with the authenticated patient are returned.

When patient identification requires the use of search parameters, the following search parameters SHALL be supported:

  • Patient: identifier
  • Observation: patient

An example of a request that retrieves all Observation resources of a patient with a fake BSN of 11122233:

GET [base]/Observation?patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333

2.3 Resource identification

All profiles used within the information standard contain .identifier elements with a cardinality of 0..* because of open world modeling. However, all ART-DECOR transactions referenced within this IG assign a 1..1 R cardinality, meaning a stable identifier SHOULD be provided, or the DataAbsentReason extension if a value is missing. Identifiers SHALL contain both a .system and a .value.

Because in HL7v3 (CDA) an identifier can only be composed using OIDs, the .system SHALL be an OID to accommodate compatibility in transformations to and from FHIR. The Netherlands HL7v3 datatype II also defines additional restrictions on the maximum length of both @root and @extension (equivalent to respectively .system and .value in FHIR). For the same compatibility reasons, .system SHALL have a maximum of 128 characters and .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 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. This also goes for included secondary resources in transactions.

2.4 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.

FHIR Profile FHIR Resource Based on zib (EN)
nl-core-LaboratoryTestResult Observation LaboratoryResult
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

Persons Systems FHIR Capability Statements
Name Description Name Description Name Description
Lab Professional The user of a LIS LIS Laboratory information system Verwijzing.png CapabilityStatement: Lab2Healthcare-Results-RetrieveServe Retrieve [LAB-LRR]/serve [LAB-LRB] lab results requirements. A LIS is only expected to serve results in the context of Lab2zorg.
Verwijzing.png CapabilityStatement: Lab2Healthcare-Results-SendReceive Send [LAB-LRS]/receive [LAB-LRO] lab results requirements. A LIS is only expected to send results in the context of Lab2zorg.
Healthcare professional The user of a XIS XIS (Any) Healthcare information system Verwijzing.png CapabilityStatement: Lab2Healthcare-Results-RetrieveServe Retrieve [LAB-LRR]/serve [LAB-LRB] lab results requirements. A XIS may both retrieve results and serve copies of results in the context of Lab2zorg.
Verwijzing.png CapabilityStatement: Lab2Healthcare-Results-SendReceive Send [LAB-LRS]/receive [LAB-LRO] lab results requirements. A XIS may both send copies of results and receive (copies of) results in the context of Lab2zorg.

4 Use cases

4.1 Health professional orders lab tests and receives results

This use case will be added in a future release.

4.2 Health professional retrieves lab results

4.2.1 Introduction

Healthcare professionals need to be able to retrieve laboratory results directly from a lab (LIS) or a secondary healthcare provider (XIS). Different healthcare professionals may have different needs and/or authorizations. The core FHIR specification offers support for a lot of use cases. This specification only outlines options for the identified scope and associated minimal expectations. As such it is not intended to be limiting to said expectations. Servers SHALL use the CapabilityStatement to advertise their implementation and clients SHOULD use this as means to discover the servers capabilities as per the FHIR specification, as well as publish their own capabilities. [FHIR RESTful] / [CapabilityStatement].

The identified use cases within the scope of this implementation guide are very broad:

  • Get latest X results for one or more specific Observation.codes
  • Get latest X results for any Observation.codes
  • Get results on/before/after date X
  • Get results on/before/after date X for one or more specific Observation.codes

Each server SHALL perform filtering based on the patient, and results associated with the request context and patient identification search parameters, so only the records are returned that the requesting party is authorized for. Example expectations are that any ordering provider will have access to results related to his orders, and any requesting party interested in medication related results only has access to those.

A special word of caution about volume. It has been proven hard to impossible to define an optimum on how much history should be supported. For example some genetic tests are done once at age 15, and are still valid at age 80. Returning all results for someone age 80 could take an enormous toll on both server and client and is seldom relevant. Clients are therefore encouraged to be as specific as possible, by using both code and/or date and/or _count whenever possible. Servers SHOULD implement _count, and SHOULD implement an OperationOutcome that informs the client of a partial result set when the total number exceeds what a server will handle.

4.2.2 Actors

Transaction group Transaction Actor Role
Retrieve laboratory results (PULL) Retrieve laboratory results request LaboratoriumresultaatResultaatRaadplegend Systeem [LAB-LRR] Send a query to the LAB-LRB to retrieve lab results
Retrieve laboratory results response LaboratoriumresultaatResultaatBeschikbaarstellend Systeem [LAB-LRB] Respond to a query from the LAB-LRR to retrieve lab results

4.2.3 Invocations

4.2.3.1 LAB-LRR: request message

The request message represents an HTTP GET parameterized query from the XIS (LAB-LRR) to the XIS/LIS (LAB-LRB).

4.2.3.1.1 Trigger events

When the healthcare professional wants to obtain laboratory results, it issues a retrieve laboratory results request message.

4.2.3.1.2 Message semantics

The XIS (LAB-LRR) executes an HTTP GET conforming to the FHIR RESTful and search specification against the XIS/LIS's Observation endpoint.

  • Laboratory results are all under the .category observation, using query parameter category as token.
  • Requesting data for a specific .subject is done using query parameter patient as reference, or on some network infrastructures with an authorization token. The FHIR query parameter type reference can take on many forms.
    • If you know what the Patient.id is, e.g. from previous interactions with the same endpoint, you may use:
      • patient=[id]
      • patient=[type]/[id]
      • patient=[url]
    • If you don't know what the Patient.id is, but you know the Patient.identifier, e.g. the Burgerservicenummer (BSN), you may use:
      • patient:identifier=[system]|[value]
  • Requesting laboratory results of a specific type is done using query parameter code as token.
  • Requesting laboratory results of a specific date (range) is done using query parameter date as token.

Basic query syntax

GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory{&patient=Patient/[id] | &patient:identifier=[system]|[value]}{&[parameter(s)]&_include=[resource(s)]}

Examples

Parameter values have not been uri escaped in these examples for readability. This is likely necessary in practice.

Query parameters overview

Servers SHALL at minimum support all stated parameters and modifiers, and MAY support additional parameters and modifiers. Clients SHALL support required parameters, and MAY support optional parameters.

  • category - token - 1..1 required - fixed value http://terminology.hl7.org/CodeSystem/observation-category|laboratory
  • patient - token - 0..1 conditional - required if not solved using an alternative method like an authorization token
    • Modifier :identifier - 0..1 optional - required when searching by identifier
  • code - token - 0..1 optional
  • date - date - 0..1 optional
    • Prefix eq - 0..1 optional - required when searching for results with .effective on exact date
    • Prefix lt - 0..1 optional - required when searching for results with .effective before date
    • Prefix le - 0..1 optional - required when searching for results with .effective on or before date
    • Prefix gt - 0..1 optional - required when searching for results with .effective after date
    • Prefix ge - 0..1 optional - required when searching for results with .effective on or after date
  • _count - positiveInt - 0..1 optional
  • _include - reference - 0..* optional - useful for request to include secondary related resources, e.g.:
    _include=Observation:patient,Observation:performer,Observation:has-member,Observation:specimen
    • Note that servers MAY, depending on their read capabilities, choose to implement inclusion of resources regardless of a client requesting this to satisfy the generic requirement that references SHALL be resolvable.

Operations

  • lastn - shortcut FHIR core operation for getting the latest X results of specified types, or 'any' type
    • Parameter max - positiveInt - optional - default is max=1
4.2.3.1.2.1 Expected actions

The XIS/LIS (LAB-LRB) SHALL process the query to retrieve laboratory results.

4.2.3.2 LAB-LRB: response message

The XIS/LIS (LAB-LRB) 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.2.3.2.1 Trigger events

The XIS/LIS (LAB-LRB) completed the processing of the retrieve laboratory results request message.

4.2.3.2.2 Message semantics

The XIS/LIS (LAB-LRB) 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

Example OperationOutcome

4.2.3.2.3 LAB-LRR: Expected actions

The XIS/LIS (LAB-LRR) 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.

4.3 Health professional sends lab results to other health professional

4.3.1 Introduction

The functional design distinguishes two use cases where lab results may be sent with something else or separate. The process of 'sending' things in FHIR works by means of a RESTful 'create' action. You could create a single Observation on another system using POST Observation and the appropriate Observation in the request body. When you have multiple Observations to create, you could do that for every single Observation, or by means of a Bundle with all resources. This same Bundle approach works for one Observation too.

The added benefit of a Bundle lies in having a solution for all other resources you may want to send, e.g. MedicationRequest, and referenced resources like Patient, PractitionerRole, Practitioner and Organization. Sending the Observation without the resources it references would only work if the receiving server can resolve those. They should then already exist on that server, with references to them or they should be accessible on the source. Without access to the references in the Observation, the target server may not know which patient is involved or what lab this result came from.

4.3.2 Actors

Transaction group Transaction Actor Role
Send laboratory results (PUSH) Send laboratory results LaboratoriumresultaatResultaatSturend Systeem [LAB-LRS] Send lab results to the LAB-LRO
Receive laboratory results LaboratoriumresultaatResultaatOntvangend Systeem [LAB-LRO] Respond to received lab results from the LAB-LRS

4.3.3 Invocations

4.3.3.1 LAB-LRS: request message

The XIS/LIS (LAB-LRS) sends lab results using the HTTP POST method on the target XIS's (LAB-LRO) base. Note that lab results may or may not be sent in tandem with other resources like MedicationRequest. The same principles apply with or without these other resources. The server can only process the incoming request correctly if it understands what is being sent which includes being able to resolve references.

4.3.3.1.1 Trigger Events

This message is invoked when the XIS needs to send one or more laboratory results to another XIS.

4.3.3.1.2 Message Semantics

Because sending laboratory results will most likely consist of multiple Observations, a transaction interaction is used. This allows for creating a set of resources in a single interaction and makes it possible to include referenced secondary resources if needed.

A transaction interaction is performed by an HTTP POST command as shown:

POST [base]

The body of the post submission is a Bundle with Bundle.type=transaction. Each entry carries request details (Bundle.entry.request) that provides the HTTP details of the action in order to inform the system processing the transaction of what to do for the entry. (Note: .request SHALL be present, even for the resources which aren't Observations. See the overarching principles for more information.)

Identification

Resources SHALL have a stable identifier in the .identifier element for all resources if such an identifier exists in the underlying data. Not all data, like individual results, are currently known to have identifiers in all source systems, but when they exist they are essential and where they do not exist yet they SHOULD be considered. Having stable identification is essential in detection of duplicates and potential clinical decision making issues deriving from duplicates. For more information on dealing with identifiers, see the general FHIR IG.

Read more

The laboratory result data sent to the XIS SHALL conform to the matching profile(s) listed in the profile table. That table contains profiles that represent applicable zibs for laboratory result information exchange.

4.3.3.1.2.1 Expected Actions

On receipt of the submission, the XIS (LAB-LRO) SHALL:

  • process all contained requests successfully or process nothing.
  • process creation of or updating all Observation resources.
    • Updating might be in order e.g. when corrections are sent or when previously pending tests have been updated with results.
  • match Patient, Practitioner(Role), Organization to pre-existing resources on its server.
    • The server MAY update pre-existing information with the incoming information.
    • The server MAY keep its pre-existing matching resources as-is.
    • The server SHALL create new resources if no matching resource is found (unknown patient, new physician in otherwise known organization, etc.).
  • decide if any available Specimen and/or Device resources are relevant.
    • If the server decides to ignore Specimen or Device information, it SHALL not keep the references to them.
  • respond using HTTP 200 and a Bundle with detail in case of success. See FHIR IG Handling Errors for response options in case of errors.
    • Note that the response Bundle with type transaction-response SHALL be specific about how the server handled the request Bundle.

4.3.3.2 LAB-LRO: response message

The XIS (LAB-LRO) returns an HTTP Status code appropriate to the processing outcome and returns a Bundle with Bundle.type=batch-response, that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry.

4.3.3.2.1 Trigger Events

The XIS (LAB-LRO) completed processing of the send laboratory results message.

4.3.3.2.2 Message Semantics

The XIS (LAB-LRO) SHALL return a Bundle with Bundle.type=batch-response that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry.

A client may use the returned Bundle to track the outcomes of processing the entry, and the identities assigned to the resources by the server. Each entry element SHALL contain a response element which details the outcome of processing the entry - the HTTP status code, and the location and ETag header values, which are used for identifying and versioning the resources. In addition, a resource may be included in the entry, as specified by the Prefer header sent by the LAB-LRS.

Read more:

4.3.3.2.3 Expected Actions

The XIS/LIS (LAB-LRS) processes the results according to application-defined rules. The most basic of those rules would include marking the transaction as sent/processed successfully or flag a need for action like resending or contacting the LAB-LRO.

4.3.3.2.4 Handling Errors

The XIS (LAB-LRO) may be unable to accept a Bundle due to errors or because of technical or business rules. Refer to the Handling Errors section in the FHIR IG for more information.

4.4 Health professional reports result leading into a notification "new lab results" for subscribed healthcare professional(s)

This use case will be added in a future release.