Brontekst bekijken van Lab:TO DRAFT metlab2labels

<!--__NOINDEX__-->
{{DISPLAYTITLE:LET OP DIT IS EEN DRAFT Technical Design Lab Exchange V4.0.0}}
{{underconstruction}}

<imagemap>Bestand:functioneel-technisch-banner_00_alle.png|center|240px|alt=Functioneel-Technisch   
circle 204 216 215 [[Lab:FO_DRAFT_metlab2labels|Functional]]
circle 990 216 215 [[Lab:TO_DRAFT_metlab2labels|Technical]]
desc none                         
</imagemap>

<big>For an overview of all current documentation [[Lab:V3.0.0_Ontwerp_Laboverdacht| see information standard lab exchange main page]]</big>

__NUMBEREDHEADINGS__

==Introduction==
[[Bestand:Functioneel-02.png|link=Lab:FO_DRAFT_metlab2labels|100px|rechts|Functional design|Go to functional design]]

This is the technical design (TO) for the information standard (IS) Lab Exchange. This TO must be used together with the IS functional design, see [[Lab:FO_DRAFT_metlab2labels| functional design Lab 4.0.0]]. The data exchange format used in this version is: FHIR R4.

=== Support ===
For questions, feedback, or change requests, please contact our support team at [https://nictiz.atlassian.net/servicedesk/customer/portal/4 Nictiz Servicemanagement].

=== Boundaries ===
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:FO_DRAFT_metlab2labels| functional design Lab 4.0.0]].

=== Prerequisite knowledge ===
The following background information is required for understanding this TO:
* The [[Lab:FO_DRAFT_metlab2labels| functional design Lab 4.0.0]] 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]].

== Relationships ==

The diagrams below show the relationships between different FHIR profiles. The arrows indicate an “is referenced in” relationship.

For example, Patient → Laboratory Test means that the Patient is referenced within the Laboratory Test resource.

===Model overview for usecases without the request===

[[Bestand:FHIR-model-overview-L2Z-SLR-BLR.png]]

===Model overview for usecase with the request===

[[Bestand:FHIR-model-overview-L2P-LOA.png]]

==Components==

HL7 FHIR is used to accommodate the Dutch Clinical Information Models (zibs) used in the IS.

=== 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-labtrial.1|p3=nictiz.fhir.nl.r4.zib2020|v3=0.12.0-beta.1}}

==== Artifacts ====

The artifacts of the information standard are presented in the following table:
{| style="text-align: left; background-color: white;" cellpadding=5px;

|- style="color: white; background-color: #e7844b;"
! zib 
! FHIR resource
! FHIR profile

|- style="background-color: #fcf0e9;"
| 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}}

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

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

|- style="background-color: #fcf0e9;"
| 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}}

|- style="background-color: #fcf0e9;"
| Observation
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-LaboratoryTestResult|nictiz.fhir.nl.r4.nl-core|pkgVersion=0.12.0-labtrial.1|title=nl-core-LaboratoryTestResult}}

|- style="background-color: #fcf0e9;"
| 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}}

|- style="background-color: #fcf0e9;"
| Patient 
| Patient
| {{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}}

|- style="background-color: #fcf0e9;"
| 
| 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}}

|- style="background-color: #fcf0e9;"
| 
| ServiceRequest
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/lu-OrderData|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.4|title=lu-OrderData}}
|}

==== Examples of FHIR instances ====
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/3.0.0 <nowiki>Lab exchange HL7-mappings repository</nowiki>].

== Transactions ==
=== Lab2Healthcare (Lab2Zorg) ===
==== Health professional orders lab tests and receives results ====
===== Involved actors =====
{| style="text-align: left;" cellpadding=5px;

|- style="color: white; background-color: #e7844b;"
! Transaction group || Transaction || Actor || System role code || FHIR CapabilityStatement

|- style="background-color: #fcf0e9;"
| rowspan="2" | Send laboratory results based on a request
| Send laboratory results based on a request || Client || LAB-LAS || rowspan="2" |{{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-SendReceive|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.4|title=Lab2Healthcare_Results_SendReceive}}

|- style="background-color: #fcf0e9;"
| Receive laboratory results || Server || LAB-LAO

|+ style="align: bottom; caption-side: bottom; text-align: left;" | ''Abbreviations: LAB = Laboratorium, LAS = Laboratoriumresultaat antwoord sturend (systeem), LAO = Laboratoriumresultaat antwoord ontvangend (systeem).''
|}

==== Health professional retrieves lab results ====
===== Involved actors =====
{| style="text-align: left;" cellpadding=5px;

|- style="color: white; background-color: #e7844b;"
! Transaction group || Transaction || Actor || System role code || FHIR CapabilityStatement

|- style="background-color: #fcf0e9;"
| rowspan="2" | Retrieve laboratory results (PULL)
| Retrieve laboratory results request || Client || LAB-LRR || rowspan="2" |{{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-RetrieveServe|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.4|title=Lab2Healthcare_Results_RetrieveServe}}

|- style="background-color: #fcf0e9;"
| Retrieve laboratory results response || Server || LAB-LRB

|+ style="align: bottom; caption-side: bottom; text-align: left;" | ''Abbreviations: LAB = Laboratorium, LRR = Laboratoriumresultaat raadplegend (systeem), LRB = Laboratoriumresultaat beschikbaarstellend (systeem).''
|}

===== Search parameters =====
The search interaction is performed by an HTTP GET in agreement with the [http://hl7.org/fhir/R4/search.html FHIR specification]. The table below lists search parameters that SHALL be supported for processing by servers and MAY be supported by clients.
For brevity of the table, the column names are not descriptive, hence a short explanation on what each column means:
* FHIR Search Parameter is the name of the parameter. We abuse terminology here, by including {{fhir|$lastn}} in this table, which technically is an operation on Observation.
* Data type refers to the data type of the value expected for a given parameter in a search request.
* Description is a short explanation of the purpose of the parameter in the context of this use case.
* Inclusion determines whether a parameter is required to appear within a single search request. SHALL means that it is mandatory to use this parameter for any search request in this use case. MAY means that it is optional.
* Repetition indicates whether a parameter may appear once or multiple times within a single search request.
* Combination logic describes how multiple occurrences of the same parameter are logically combined (AND/OR) when the parameter is repeated within a single search request. For general behavior regarding AND/OR logic, see [[FHIR:V1.0_FHIR_IG_R4#Search_URLs_and_search_parameters|the section about the use of search parameters in the IG.]]
* FHIR Resource refers to which resource the search parameter applies in this use case.
In some cases, a column is not applicable to a specific parameter. In that case we use the flag "n/a".
{| style="text-align: left;" cellpadding=5px; 
|- style="color: white; background-color: #e7844b;"
! FHIR Search Parameter || Data type || Description || Inclusion || Repetition || Combination logic || FHIR Resource

|- style="background-color: #fcf0e9;"
| {{fhir|category}} || {{fhir|CodeableConcept}} || Search on laboratory observations (the value is fixed to laboratory) || SHALL || no || n/a || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|patient:identifier}} || {{fhir|Identifier}} || Search in a specific patient context || SHALL || no || n/a || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|code}} || {{fhir|CodeableConcept}} || Search on test code (LOINC/NHG) || MAY || yes || with AND/OR || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|date}} (with prefix {{fhir|gt}}) || {{fhir|dateTime}} || Search on observation date later than the value || MAY || no || n/a || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|date}} (with prefix {{fhir|lt}}) || {{fhir|dateTime}} || Search on observation date earlier than the value || MAY || no || n/a || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|$lastn}} || n/a || Search for the most recent observation || MAY || no || n/a || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|max}} || {{fhir|positiveInt}} || Search for last n observations. Must be used as a parameter to operation {{fhir|$lastn}} || MAY || no || n/a || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|_include}} || {{fhir|Resource}} || Include linked resources (e.g. Specimen, Patient, Organization) in the response bundle || MAY || yes || with AND || Observation

|- style="background-color: #fcf0e9;"
| {{fhir|_include:iterate}} || {{fhir|Resource}} || Include linked resources iteratively || MAY || yes || with AND || Observation

|+ style="align: bottom; caption-side: bottom; text-align: left;" | 
|}

===== Search examples =====
{| class="mw-collapsible mw-collapsed wikitable"
! Show all laboratory results with test code 14683-7 (LOINC) of the 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>
|}
{| class="mw-collapsible mw-collapsed wikitable"
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 from 12 March 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-12-03</pre>
|}
{| class="mw-collapsible mw-collapsed wikitable"
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 between 12 March 2022 and 7 June 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-12-03&date=lt2022-07-06</pre>
|}
{| class="mw-collapsible mw-collapsed wikitable"
! Show all laboratory results with test code 14683-7 (LOINC) or 3583 (NHG) of the 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>
|}
{| class="mw-collapsible mw-collapsed wikitable"
! Show the most recent laboratory result with test code 14683-7 (LOINC) of the 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>
|}
{| class="mw-collapsible mw-collapsed wikitable"
! Show the five most recent laboratory results with test code 14683-7 (LOINC) of the 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>
|}
{| class="mw-collapsible mw-collapsed wikitable"
! Show the most recent laboratory result of the 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>
|}

==== Health professional sends lab results to other health professional ====
===== Involved actors =====
{| style="text-align: left;" cellpadding=5px;

|- style="color: white; background-color: #e7844b;"
! Transaction group || Transaction || Actor || System role code || FHIR CapabilityStatement

|- style="background-color: #fcf0e9;"
| rowspan="2" | Send laboratory results (PUSH)
| Send laboratory results || Client || LAB-LRS || rowspan="2" |{{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/Lab2Healthcare-Results-SendReceive|nictiz.fhir.nl.r4.labexchange|pkgVersion=3.0.0-beta.4|title=Lab2Healthcare_Results_SendReceive}}

|- style="background-color: #fcf0e9;"
| Receive laboratory results || Server || LAB-LRO

|+ style="align: bottom; caption-side: bottom; text-align: left;" | ''Abbreviations: LAB = Laboratorium, LRS = Laboratoriumresultaat sturend (systeem), LRO = Laboratoriumresultaat ontvangend (systeem).''
|}

=== Lab2Patient ===
==== Patient retrieves laboratory results in their PGO ====
===== Involved actors =====
{| style="text-align: left;" cellpadding=5px;

|- style="color: white; background-color: #e7844b;"
! Transaction group || Transaction || Actor || System role code

|- style="background-color: #fcf0e9;"
| rowspan="2" | Retrieve laboratory results (PULL)
| Retrieve laboratory results request || Client || LAB-LRR-PGO

|- style="background-color: #fcf0e9;"
| Retrieve laboratory results response || Server || LAB-LRB-PGO

|+ style="align: bottom; caption-side: bottom; text-align: left;" | ''Abbreviations: LAB = Laboratorium, LRR = Laboratoriumresultaat raadplegend (systeem), LRB = Laboratoriumresultaat beschikbaarstellend (systeem), PGO = Persoonlijke gezondheidsomgeving.''
|}

===== Search parameters =====
{| style="text-align: left;" cellpadding=5px; 
|- style="color: white; background-color: #e7844b;"
! FHIR Search Parameter || Description || FHIR Resource || Example

|- style="color: white; background-color: #eda778;"
! colspan="4"  | Retrieve laboratory results (Observation search)

|- style="background-color: #fcf0e9;"
| category || Restrict search to laboratory observations || Observation || <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory</pre>

|- style="background-color: #fcf0e9;"
| 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>

|- style="background-color: #fcf0e9;"
| 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>

|- style="color: white; background-color: #eda778;"
! colspan="4" | Retrieve latest laboratory results ($lastn operation)

|- style="background-color: #fcf0e9;"
| $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>

|- style="color: white; background-color: #eda778;"
! colspan="4" | Retrieve related resources

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

|+ 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.''
|}