|
|
| (47 tussenliggende versies door 3 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.}} | + | <!--__NOINDEX__--> |
| | + | {| class="wikitable" "cellpadding="60" width="40%" |
| | + | {{Vdraft/InformationBox|'IsUitbesteed' and POC-test are not yet part of the Technical Design (TO). In the Functional Design (FO) they have already been described. These elements will also be included in TO beta.4.}} |
| | + | |} |
| | | | |
| − | {{DISPLAYTITLE:FHIR Lab2patient V1.0.0}} | + | {{DISPLAYTITLE:Technical Design Lab2patient V1.0.0-beta.1}} |
| | <!--{{underconstruction}}--> | | <!--{{underconstruction}}--> |
| | | | |
| − | <imagemap>Bestand:functioneel-technisch-banner_00_alle.png|center|240px|alt=Functioneel-Technisch | + | <imagemap>Bestand:Leeswijzer-technisch-banner 03 white.png|center|400px|alt=Afspraken-Functioneel-Technisch |
| − | circle 204 216 215 [[Lab:V1.0_Ontwerp_Lab2Patient|Functional]] | + | circle 241 216 211 [https://www.medmij.nl/afsprakenstelsel Afsprakenstelsel] |
| − | circle 990 216 215 [[Lab:V1.0_FHIR_Lab2Patient|Technical]] | + | circle 1013 224 212 [[Lab:V1.0_Ontwerp_Lab2Patient|Functional]] |
| | + | circle 1787 230 212 [[Lab:V1.0_FHIR_Lab2Patient|Technical]] |
| | desc none | | desc none |
| | </imagemap> | | </imagemap> |
| | + | |
| | + | <big>For an overview of all current documentation [[Lab:V3.0.0_Ontwerp_Laboverdacht| see information standard lab exchange main page]]</big> |
| | | | |
| | __NUMBEREDHEADINGS__ | | __NUMBEREDHEADINGS__ |
| | | | |
| − | =Introduction= | + | ==Introduction== |
| | [[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 (Lab2patient) 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:V1.0_Ontwerp_Lab2Patient|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. | + | This is the technical design (TO) for the information standard (IS) Lab2patient. This TO must be used together with the IS functional design, see [[Lab:V1.0_Ontwerp_Lab2Patient| functional design Lab2patient 1.0.0-beta.1]]. The data exchange format used in this version is: FHIR R4. |
| | | | |
| − | 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:
| + | === Support === |
| | + | For questions, feedback, or change requests, please contact our support team at [https://nictiz.atlassian.net/servicedesk/customer/portal/4 Nictiz Servicemanagement]. |
| | | | |
| − | * {{fhir|Observation}} and one or more {{fhir|Observation.hasMember}} elements.
| + | === Boundaries === |
| − | ** 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.
| + | This information standard may overlap with other standards related to identification, roles, and geographic classifications, requiring careful alignment to ensure consistency and avoid duplication. For more information, see [[Lab:V1.0_Ontwerp_Lab2Patient| functional design Lab2patient 1.0.0-beta.1]]. |
| − | ** 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.
| |
| − | * {{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.
| |
| − | ** 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|.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.
| + | === Prerequisite knowledge === |
| | + | The following background information is required for understanding this TO: |
| | + | * The [[Lab:V1.0_Ontwerp_Lab2Patient| functional design Lab2patient 1.0.0-beta.1]] accompanying this TO. |
| | + | * The data exchange format FHIR R4, which you can find here: |
| | + | ** [[FHIR:V1.0 FHIR IG R4|general FHIR R4 Implementation Guide]], |
| | + | ** [[FHIR:V1.0_FHIR_IG_R4#FHIR_Packages|FHIR packages]], |
| | + | ** [[FHIR:V1.0_FHIR_IG_R4#Usage_of_the_.id.2C_.identifier_and_.fullUrl_elements_in_FHIR_instances|usage of the .id, .identifier and .fullUrl]]. |
| | | | |
| − | =Boundaries and relationships= | + | == 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.
| + | The diagram below shows the relationships between different FHIR profiles. The arrows indicate an “is referenced in” relationship. |
| | | | |
| − | 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.
| + | For example, Patient → Laboratory Test means that the Patient is referenced within the Laboratory Test resource. |
| | | | |
| − | [[Bestand:LaboratoryInFHIRR4Overview.png|miniatuur|Laboratory results in FHIR R4 overview]] | + | [[Bestand:FHIR-model-overview-L2P.png]] |
| | | | |
| − | The single zib LaboratoryTestResult consists of objects that in FHIR are represented using different (instances of) resources:
| + | ==Components== |
| − | * ''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==
| + | HL7 FHIR is used to accommodate the Dutch Clinical Information Models (zibs) used in the IS. |
| − | 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:
| + | === HL7 FHIR R4 === |
| | + | {{NoteBoxNictizR4Package|p1=nictiz.fhir.nl.r4.labexchange|v1=3.0.0-beta.4|p2=nictiz.fhir.nl.r4.nl-core|v2=0.12.0-beta.1|p3=nictiz.fhir.nl.r4.zib2020|v3=0.12.0-beta.1}} |
| | | | |
| − | * Patient: {{fhir|identifier}}
| + | ==== Artifacts ==== |
| − | * Observation: {{fhir|patient}}
| |
| | | | |
| − | An example of a request that retrieves all Observation resources of a patient with a fake BSN of 11122233:
| + | The artifacts of the information standard are presented in the following table: |
| | + | {| style="text-align: left; background-color: white;" cellpadding=5px; |
| | | | |
| − | <pre>GET [base]/Observation?patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
| + | |- style="color: white; background-color: #e7844b;" |
| | + | ! zib |
| | + | ! FHIR resource |
| | + | ! FHIR profile |
| | | | |
| − | ==Resource identification== | + | |- style="background-color: #fcf0e9;" |
| − | 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}}.
| + | | HealthcareProvider |
| | + | | Organization |
| | + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-beta.1|title=nl-core-HealthcareProvider-Organization}} |
| | | | |
| − | 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 Dutch HL7v3 datatype variant of 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.
| + | |- style="background-color: #fcf0e9;" |
| | + | | rowspan="2" | HealthProfessional |
| | + | | Practitioner |
| | + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-Practitioner|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-beta.1|title=nl-core-HealthProfessional-Practitioner}} |
| | | | |
| − | 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]].
| + | |- style="background-color: #fcf0e9;" |
| | + | | PractitionerRole |
| | + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-PractitionerRole|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-beta.1|title=nl-core-HealthProfessional-PractitionerRole}} |
| | | | |
| − | ==FHIR Profile Package== | + | |- style="background-color: #fcf0e9;" |
| − | 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.
| + | | rowspan="3" | LaboratoryTestResult |
| | + | | Device |
| | + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult.Specimen.Source|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.7.0-beta.1|title=nl-core-LaboratoryTestResult.Specimen.Source}} |
| | | | |
| − | {{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}} | + | |- style="background-color: #fcf0e9;" |
| | + | | Observation |
| | + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-beta.1|title=nl-core-LaboratoryTestResult}} |
| | | | |
| − | {| class="wikitable" style="min-width:90%;"
| + | |- style="background-color: #fcf0e9;" |
| − | |-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 | | | Specimen |
| − | |-
| + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult.Specimen|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-beta.1|title=nl-core-LaboratoryTestResult.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=
| + | |- style="background-color: #fcf0e9;" |
| − | {| class="wikitable"
| + | | Patient |
| − | ! colspan="2" style="text-align:left;font-weight: bold;" | Actors
| |
| − | ! colspan="2" style="text-align:left;font-weight: bold;" | Systems
| |
| − | ! colspan="2" style="text-align:left;font-weight: bold;" | FHIR CapabilityStatements
| |
| − | |- | |
| − | ! style="text-align:left;" |Name
| |
| − | ! style="text-align:left;" |Description
| |
| − | ! style="text-align:left;" |Name
| |
| − | ! style="text-align:left;" |Description
| |
| − | ! style="text-align:left;" |Name
| |
| − | ! style="text-align:left;" |Description
| |
| − | |-
| |
| | | Patient | | | Patient |
| − | | The user of a personal healthcare environment.
| + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-beta.1|title=nl-core-Patient}} |
| − | | PHR
| |
| − | | Personal health record
| |
| − | | rowspan="2" | {{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}}
| |
| − | | rowspan="2" | Retrieve [LAB-LRR-PGO]/serve [LAB-LRB-PGO] lab results requirements.
| |
| − | |-
| |
| − | | Lab Professional
| |
| − | | The user of a LIS
| |
| − | | LIS
| |
| − | | Laboratory information system
| |
| − | |}
| |
| − | | |
| − | =Use cases=
| |
| | | | |
| − | ==Patient retrieves laboratory results in their PGO== | + | |- style="background-color: #fcf0e9;" |
| − | ===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.
| + | | DiagnosticReport |
| | + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/lu-LaboratoryTestResult-DiagnosticReport|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.4|title=lu-LaboratoryTestResult-DiagnosticReport}} |
| | | | |
| − | ===Actors===
| + | |- style="background-color: #fcf0e9;" |
| − | {| class="wikitable" "cellpadding="10"
| + | | |
| − | ! style="text-align:left;"| '''Transaction group'''
| + | | ServiceRequest |
| − | ! style="text-align:left;"| '''Transaction'''
| + | | {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/lu-OrderData|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.4|title=lu-OrderData}} |
| − | ! style="text-align:left;"| '''Actor'''
| |
| − | ! style="text-align:left;"| '''Role'''
| |
| − | |-
| |
| − | |style="background-color: white;vertical-align:top;" rowspan="2"|Retrieve laboratory results (PULL)
| |
| − | |style="background-color: white;vertical-align:top;"|Retrieve laboratory results request | |
| − | |style="background-color: white;vertical-align:top;"|LaboratoriumresultaatResultaatRaadplegend Systeem [LAB-LRR-PGO] | |
| − | |style="background-color: white;vertical-align:top;"|Send a query to the LAB-LRB-ORG to retrieve lab results | |
| − | |-
| |
| − | |style="background-color: white;vertical-align:top;"|Retrieve laboratory results response
| |
| − | |style="background-color: white;vertical-align:top;"|LaboratoriumresultaatResultaatBeschikbaarstellend Systeem [LAB-LRB-PGO] | |
| − | |style="background-color: white;vertical-align:top;"|Respond to a query from the LAB-LRR-ORG to retrieve lab results
| |
| | |} | | |} |
| | | | |
| − | ===Invocations=== | + | ==== Examples of FHIR instances ==== |
| − | ====LAB-LRR: request message==== | + | You can find examples of FHIR-instances (filled-in FHIR profiles) in the Nictiz GitHub repository: [https://github.com/Nictiz/HL7-mappings/tree/master/ada_2_fhir-r4/lab/1.0.0-alpha.1 <nowiki>Lab exchange HL7-mappings repository</nowiki>]. |
| − | The request message represents an HTTP GET parameterized query from the PHR (LAB-LRR-PGO) to the LIS (LAB-LRB-PGO).
| |
| | | | |
| − | =====Trigger events===== | + | == Transactions == |
| − | When the patient (PHR) wants to obtain laboratory results, it issues a retrieve laboratory results request message.
| + | === Patient retrieves laboratory results in their PGO === |
| | + | ==== Involved actors ==== |
| | + | {| style="text-align: left;" cellpadding=5px; |
| | | | |
| − | =====Message semantics===== | + | |- style="color: white; background-color: #e7844b;" |
| − | The XIS (LAB-LRR) 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 XIS/LIS's Observation endpoint.
| + | ! Transaction group || Transaction || Actor || System role code |
| | | | |
| − | * Laboratory results are all under the {{fhir|.category}} ''observation'', using query parameter {{fhir|category}} as token.
| + | |- style="background-color: #fcf0e9;" |
| − | * 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.
| + | | rowspan="2" | Retrieve laboratory results (PULL) |
| − | ** If you know what the {{fhir|Patient.id}} is, e.g. from previous interactions with the same endpoint, you may use:
| + | | Retrieve laboratory results request || Client || LAB-LRR-PGO |
| − | *** {{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.
| |
| | | | |
| − | '''Basic query syntax'''
| + | |- style="background-color: #fcf0e9;" |
| − | <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>
| + | | Retrieve laboratory results response || Server || LAB-LRB-PGO |
| | | | |
| − | '''Examples''' | + | |+ style="align: bottom; caption-side: bottom; text-align: left;" | ''Abbreviations: LAB = Laboratorium, LRR = Laboratoriumresultaat raadplegend (systeem), LRB = Laboratoriumresultaat beschikbaarstellend (systeem), PGO = Persoonlijke gezondheidsomgeving.'' |
| | + | |} |
| | | | |
| − | Parameter values have not been uri escaped in these examples for readability. This is likely necessary in practice. | + | ==== Search parameters ==== |
| | + | {| style="text-align: left;" cellpadding=5px; |
| | + | |- style="color: white; background-color: #e7844b;" |
| | + | ! FHIR Search Parameter || Description || FHIR Resource || Example |
| | | | |
| − | {{Collapse top|Get all lab results of type 14683-7 (LOINC) for patient with BSN 111222333}}
| + | |- style="color: white; background-color: #eda778;" |
| − | <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>
| + | ! colspan="4" | Retrieve laboratory results (Observation search) |
| − | {{Collapse bottom}}
| |
| | | | |
| − | {{Collapse top|Get all lab results of type 14683-7 (LOINC) for patient with BSN 111222333 since March 12, 2022}}
| + | |- style="background-color: #fcf0e9;" |
| − | <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> | + | | category || Restrict search to laboratory observations || Observation || <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory</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}}
| + | |- style="background-color: #fcf0e9;" |
| − | <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> | + | | code || Filter by laboratory test code (LOINC /NHG) || Observation || <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7</pre> |
| − | {{Collapse bottom}}
| |
| | | | |
| − | {{Collapse top|Get all lab results of type 14683-7 (LOINC) and/or 3583 (NHG) for patient with BSN 111222333}}
| + | |- style="background-color: #fcf0e9;" |
| − | <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> | + | | date || Filter results based on observation date || Observation || <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory& date= gt2022-03-12& date= lt2022- 06- 07</pre> |
| − | {{Collapse bottom}}
| |
| | | | |
| − | {{Collapse top|Get latest lab result of type 14683-7 (LOINC) for patient with BSN 111222333}}
| + | |- style="color: white; background-color: #eda778;" |
| − | <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>
| + | ! colspan="4" | Retrieve latest laboratory results ($lastn operation) |
| − | {{Collapse bottom}}
| |
| | | | |
| − | {{Collapse top|Get latest 5 lab results of type 14683-7 (LOINC) for patient with BSN 111222333}}
| + | |- style="background-color: #fcf0e9;" |
| − | <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> | + | | $lastn || Retrieve most recent lab results using the $lastn operation || Observation || <pre>GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&code=http://loinc.org|14683-7</pre> |
| − | {{Collapse bottom}}
| |
| | | | |
| − | {{Collapse top|Get latest lab result of any type for patient with BSN 111222333}}
| + | |- style="color: white; background-color: #eda778;" |
| − | <pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
| + | ! colspan="4" | Retrieve related resources |
| − | {{Collapse bottom}}
| |
| | | | |
| − | '''Query parameters overview'''
| + | |- style="background-color: #fcf0e9;" |
| | + | | _include || Include linked resources (Specimen, Patient, Organization) in the response bundle || Observation || <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&_include=Observation:specimen&_include=Observation:patient&_include=Observation:performer</pre> |
| | | | |
| − | 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.
| + | |+ style="align: bottom; caption-side: bottom; text-align: left;" | ''All queries are executed in the authenticated patient context as per MedMij Afsprakenstelsel; no patient search parameters are used.'' |
| − | * {{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.
| |
| − | | |
| − | '''Example searchset Bundle'''
| |
| − | | |
| − | {{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&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&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}}
| |
| − | | |
| − | '''Example OperationOutcome''' | |
| − | | |
| − | {{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}}
| |
| − | | |
| − | =====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.
| |
| − | | |
| − | =Release Notes=
| |
| − | Please note that we have gained new insights based on the developments in HL7 Europe and the HL7 WGM. The necessary changes based on this feedback will be addressed and released in the next release.
| |
