Brontekst bekijken van MedMij:V2020.01/FHIR IG

__NUMBEREDHEADINGS__
{{DISPLAYTITLE:MedMij FHIR Implementation Guide}}
{{MedMij:V2020.01/Issuebox_FHIR_IG}}

[[Bestand:MedMij2.png |link=https://www.medmij.nl/|rechts|Naar medmij.nl]]
<imagemap>Bestand:Leeswijzer-technisch-banner 03 white.png|center|400px|alt=Afspraken-Functioneel-Technisch   
circle 241 216 211 [https://www.medmij.nl/afsprakenstelsel Afsprakenstelsel]                
circle 1013 224 212 [[MedMij:V2020.01/Ontwerpen|Functioneel]]                
circle 1787 230 212 [[MedMij:V2020.01/FHIR_IG|Technisch]]                
desc none                    
</imagemap>
__TOC__

{{large|Quick links}}
----
{|  
! [[Bestand:BGZ_icoon.png |link=MedMij:V2020.01/FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]] 
!  &nbsp;&nbsp;
! [[Bestand:Medication_Icoon.png |link=MedMij:V2020.01/FHIR_MedicationProcess|100px |Medication Process]]
!  &nbsp;&nbsp;
! [[Bestand:AllergyIntolerance.png |link=MedMij:V2020.01/FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
!  &nbsp;&nbsp;
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:V2020.01/FHIR_VitalSigns|105px |Self-Measurements]]
! &nbsp;&nbsp;
! [[Bestand:LabResults@2x.png |link=MedMij:V2020.01/FHIR_LaboratoryResults |100px|Laboratory Results]]
! &nbsp;&nbsp;
! [[Bestand:BgLZ-icon-text.png|link=MedMij:V2020.01/FHIR_BGLZ|105px| BgLZ]]
|}

{|  
! [[Bestand:PDF-A icoon.png|link=MedMij:V2020.01/FHIR_PDFA |100px |PDF/A - Health Documents]]
! &nbsp;&nbsp;
! [[Bestand:EAfspraak_-_text.png |link=MedMij:V2020.01/FHIR_eAfspraak |98px |eAfspraak - Appointments]]
! &nbsp;&nbsp;
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:V2020.01/FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
! &nbsp;&nbsp;
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:V2020.01/FHIR_GGZ |105px |GGZ]]
! &nbsp;&nbsp;
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:V2020.01/FHIR_Images |105px |Images]]
! &nbsp;&nbsp;
! [[Bestand:Vragenlijsten_-_EN_dikkere_rand.png|link=MedMij:V2020.01/FHIR_Questionnaire_and_Questionnaire_Response_(Vragenlijsten)|108px| Questionnaire]]
|}

=About the IG=
This is the technical MedMij FHIR implementation guide based on '''HL7® FHIR® version STU3'''. 

==Purpose==
An implementation guide for making use of FHIR in the Dutch context. This guide is developed specifically for the use of HL7® FHIR® between personal health records(PHR) and healthcare provider systems (XIS). PHR and XIS vendors that participate in MedMij conform to a framework of agreements, in Dutch this is called the 'afsprakenstelsel.' HL7 FHIR, or just 'FHIR', plays an important role among those agreements and is used as a standard to exchange health information between the involved parties. The purpose of this guide is to describe use cases and provide technical guidance on how to implement FHIR  in these situations. This guide outlines the FHIR building blocks, or profiles, involved in these use cases. Moreover, this guide provides a textual explanation of these building blocks and describes their relationship and boundaries.

==Scope==
The scope of this guide includes requirements to enable PHR and XIS in the Dutch realm to use standardized structured data in a defined inter-organizational transaction. Health is a vast domain. Therefore, MedMij has made scoping choices for its roadmap. MedMij starts with a limited number of medical subdomains but has the vision to elaborate on more domains later. In scope domains are first described in the [[MedMij:V2020.01/Ontwerpen|functional design]] that underlies this technical design.

==Background==
MedMij aims to stimulate electronic information exchange between patients and caregivers. Caregivers generally have access to software applications to help them support their work in treating patients. Software applications for patients are evolving as we speak, but patients typically are not yet enabled to be regarded as a true partner in the care process. MedMij delivers an agreements scheme to enable patients to become that true partner. The section [[#Afsprakenstelsel]] describes the relation to this implementation guide.

Information standards have a functional and technical component. The functional part contains definitions of relevant concepts (dataset) and scenario’s that define when to exchange which of those concepts. The technical part translates the functional scenario’s in an exchange format (such as HL7v3 or FHIR). The stakeholders in MedMij have chosen to introduce FHIR as a modern standard to exchange information in MedMij. A dutch factsheet that explains why FHIR is chosen is available on the [https://www.medmij.nl/wp-content/uploads/2017/06/Factsheet-MedMij-FHIR.pdf MedMij website]. MedMij delivers a FHIR representation ([https://hl7.org/fhir/STU3/profiling.html profiles]) for each domain in scope. 

The program ‘Registratie aan de bron’ (Data capture at the point of Care) has defined [https://zibs.nl/wiki/HCIM_Mainpage| Health and Care Information models] (zorginformatiebouwstenen or zibs) for The Netherlands. zibs contain definitions of healthcare concepts. MedMij information standards contain mappings to these zibs. MedMij creates FHIR profiles based on zibs which include mappings to the relevant zib concepts. As a result, the created profiles enable context-free implementation. Therefore, these profiles are applicable in a broader context than the described use cases or the MedMij context. Reuse of these profiles enables interoperability for health information.

==Audience==
The main target audience of this implementation guide is software vendors and developers that will implement FHIR as part of electronic information exchange under MedMij. This IG is intended for developers of PHR as well as XIS vendors.
Users of this guide are expected to be familiar with the [https://hl7.org/fhir/STU3 FHIR specification] and resource processing. This guide provides links to relevant sections of the FHIR specification. This implementation guide is not intended to be a tutorial on that subject.

==Language==
This implementation guide is written in English, even though the majority of the documentation in MedMij is in Dutch. A Dutch translation of this document may become available. However, the English version is and remains leading. The rationale for choosing English is as follows. Implementers in healthcare are in many cases foreign, e.g., through outsourcing or because the company is a multinational. But even if they are Dutch native speakers, the educational tracks, their programming language of choice, and the implementer communities they are part of will largely be based on the English language. In creating the documentation for the target audience, we have received overwhelming preference from the MedMij implementer community for English. English documentation saves them investments and risks in getting a translation agency on a per vendor basis for each version of the documentation, while at the same time not alienating the native Dutch speaking audience. As a side effect it also helps Nictiz in the international realm in discussions with relevant initiatives such as Argonaut (US), Patients Know Best (UK), the Finnish PHR, and the HL7/FHIR community at large.

=Afsprakenstelsel=
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]
The 'afsprakenstelsel' references the MedMij information standards. In addition, the  MedMij information standards are specified in the context of the 'afsprakenstelsel.' This applies to the implementation guidance of the use cases described in this implementation guide.

For example, all use cases performed in the context of a specific authenticated patient, for which an OAuth2 token has been retrieved using the Authentication mechanisms described in the [https://www.medmij.nl/afsprakenstelsel/ 'afsprakenstelsel']. This token must be passed in each call in the HTTP header named <code>Authorization</code>. Each XIS Gateway is required to perform filtering based on the patient associated with the OAuth2 token received for the request so that only the records associated with the authenticated patient are returned.

=Functional design=
[[Bestand:Functioneel-02.png|link=MedMij:V2020.01/Ontwerpen |100px|rechts|Functional design|Go to functional design]]

All use cases described in this implementation guide have a functional counterpart. The functional design pages are written in Dutch. The main overarching wiki page of the functional designs can be found at [[MedMij:V2020.01/Ontwerpen|here]]. From this page, you can link to the specific use case through the patient journey image or the table index. It is possible to link to the specific functional design page from the technical use case pages in this wiki by clicking on the functional circle in the top image.

=Use cases=
Implementation guidance is provided per use case on separate wiki pages. The next section provides implementation guidance that apply for all use cases. The green circles represent the available use cases. Click on the circle to go to the use case page. 


{|  
! [[Bestand:BGZ_icoon.png |link=MedMij:V2020.01/FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]] 
!  &nbsp;&nbsp;
! [[Bestand:Medication_Icoon.png |link=MedMij:V2020.01/FHIR_MedicationProcess|100px |Medication Process]]
!  &nbsp;&nbsp;
! [[Bestand:AllergyIntolerance.png |link=MedMij:V2020.01/FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
!  &nbsp;&nbsp;
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:V2020.01/FHIR_VitalSigns|105px |Self-Measurements]]
! &nbsp;&nbsp;
! [[Bestand:LabResults@2x.png |link=MedMij:V2020.01/FHIR_LaboratoryResults |100px|Laboratory Results]]
! &nbsp;&nbsp;
! [[Bestand:BgLZ-icon-text.png|link=MedMij:V2020.01/FHIR_BGLZ|105px| BgLZ]]
|}

{|  
! [[Bestand:PDF-A icoon.png|link=MedMij:V2020.01/FHIR_PDFA |100px |PDF/A - Health Documents]]
! &nbsp;&nbsp;
! [[Bestand:EAfspraak_-_text.png |link=MedMij:V2020.01/FHIR_eAfspraak |98px |eAfspraak - Appointments]]
! &nbsp;&nbsp;
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:V2020.01/FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
! &nbsp;&nbsp;
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:V2020.01/FHIR_GGZ |105px |GGZ]]
! &nbsp;&nbsp;
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:V2020.01/FHIR_Images |105px |Images]]
! &nbsp;&nbsp;
! [[Bestand:Vragenlijsten_-_EN_dikkere_rand.png|link=MedMij:V2020.01/FHIR_Questionnaire_and_Questionnaire_Response_(Vragenlijsten)|108px| Questionnaire]]
|}
{{NoteBox|1= When considering an implementation of (parts of) BgLZ, please contact [mailto:standaarden@medmij.nl standaarden@medmij.nl].}}
<section start="UseCaseOverarchingPrinciples"/>
=Use case overarching principles=
<section begin="OverarchingPrinciples" />{{#lst:FHIR:V1.0_FHIR_IG_STU3|ContentTypesAndEncodings}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|UseOfCodedConcepts}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|UseOfTheReferenceDataType}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|RelatingFHIRProfilesWithTheirFunctionalDefinitions}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|ProfileUseAndDeclaration}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|TheNarrative}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|Search}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|Identification}}
== Handling errors==
Errors in FHIR interactions are usually communicated using the combination of an appropriate HTTP status code in the 4xx-5xx range, and an [https://hl7.org/fhir/STU3/operationoutcome.html OperationOutcome] resource providing more details regarding the error. The OperationOutcome resource contains mandatory elements to indicate the overall type and severity of the error (respectively {{fhir|.code}} and {{fhir|.severity}}) and MAY express the location (using {{fhir|.location}} or {{fhir|.expression}}) and a free-form or coded description of the error (using the {{fhir|.diagnostics}} or {{fhir|.detail}} element). Although these latter elements are not required, their usage is strongly encouraged.

For the most common errors, the expected handling is listed in the table below. This should be interpreted as a guideline, as the nature of an error is not always unambiguous and various FHIR reference implementations will make different choices. The FHIR specification provides more detail [https://www.hl7.org/fhir/stu3/http.html on error handling in general], [https://www.hl7.org/fhir/stu3/security.html#AccessDenied access denied responses] and [https://www.hl7.org/fhir/stu3/search.html#errors for search operations specifically].

In general, most FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues) will result in one of these HTTP status codes:
* 400 Bad Request - resource could not be parsed, search could not be processed or basic FHIR validation rules failed
* 401 Unauthorized - authorization is required for the interaction that was attempted (usually emitted by the authorization server)
* 403 Forbidden - the server was unable to execute the search, due to an authorization failure (usually emitted by the resource server)
* 404 Not Found - resource type not supported, or not a FHIR endpoint
* 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules

{| class="wikitable"  
|- 
! Interaction 
! Error 
! Expected action 
! Example 
|-
| rowspan=3 |All 
| Not authorized, absent or expired access token
|
* HTTP 401 Unauthorized
* <del>OperationOutcome with {{fhir|.code}} set to {{term|security}}.</del><br />Please note: the MedMij Afsprakenstelsel explicitly forbids that servers divulge additional information in case of an authorization failure, so servers SHOULD NOT send an OperationOutcome within the MedMij context
| <del>[[FHIR:V1.0 FHIR_Error_handling_examples#Not_authorized|Example]]</del>
|-
| Invalid authorization, scope of the access token is not sufficient for the request
| 
* HTTP 403 Forbidden
* OperationOutcome with {{fhir|.code}} set to {{term|security}}.
| [[FHIR:V1.0 FHIR_Error_handling_examples#Invalid_authorization|Example]]
|-  
| Resource is not supported
|
* HTTP 404 Not Found
* OperationOutcome with {{fhir|.code}} set to {{term|not-supported}}.
| [[FHIR:V1.0 FHIR_Error_handling_examples#Resource_is_not_supported|Example]]
|- 
| rowspan=4 |search
| No match for the given search parameters
| colspan="2" |''This is not considered an error, but a normal search without results.''
|-
| Unknown search parameter
| colspan="2" | ''This is not considered an error. See the [[#unknown_search_parameter_handling|guidance in the section on searching]].''
|- 
| Syntactically incorrect parameter
| 
* HTTP 400 Bad Request
* OperationOutcome. There are various issue type codes that could be used, depending on the nature of the error.
| [[FHIR:V1.0 FHIR_Error_handling_examples#Syntactically_incorrect_parameter|Example]]
|-
| Known but unsupported value. This situation applies to non-supported HCIM profiles when the Resource endpoint itself is supported.
|
* HTTP 200 OK
* Empty Bundle of {{fhir|.type}} {{term|searchset}}.
* OperationOutcome in Bundle as an entry with {{fhir|Bundle.entry.search.mode}} set to {{term|outcome}}.
* OperationOutcome with {{fhir|.code}} set to {{term|not-found}} and {{fhir|.severity}} not set to {{term|fatal}} or {{term|error}}.
| [[FHIR:V1.0 FHIR_Error_handling_examples#Unkown_or_unsupported_search_parameter_value|Example]]
|- 
| read
| Read request with unknown id
| 
* HTTP 404 Not Found
* OperationOutcome with {{fhir|.code}} set to {{term|not-found}}.
| [[FHIR:V1.0 FHIR_Error_handling_examples#Request_on_an_unknown_id|Example]]
|- 
| update
|  No or incorrect Resource id 
|
* HTTP 400 Bad Request
* OperationOutcome with {{fhir|.code}} set to {{term|invalid}}.
| [[FHIR:V1.0 FHIR_Error_handling_examples#No_or_incorrect_Resource_id|Example]]
|- 
| create/update
| Resource syntax or data is incorrect, invalid or unsupported
| 
* HTTP 400 Bad Request or HTTP 422 Unprocessable Entity
* OperationOutcome with {{fhir|.code}} set to {{term|invalid}} or preferably a more specific child code.
| [[FHIR:V1.0 FHIR_Error_handling_examples#Resource_syntax_or_data_is_incorrect_or_invalid|Example]]
|}
{{#lst:FHIR:V1.0_FHIR_IG_STU3|CapabilityStatements}}{{#lst:FHIR:V1.0_FHIR_IG_STU3|ReferringOtherResources}}<section end="UseCaseOverarchingPrinciples"/>{{#lst:FHIR:V1.0_FHIR_IG_STU3|FHIRPackages}}<section end="OverarchingPrinciples" />

=Relevant links=
'''HL7 FHIR specification'''
* [https://hl7.org/fhir/STU3/index.html HL7 FHIR STU3]
* [https://confluence.hl7.org/ HL7 Confluence]

'''Repository of MedMij FHIR artefacts'''
* [https://simplifier.net/NictizSTU3-Zib2017 Simplifier.net]
** [https://github.com/Nictiz/Nictiz-STU3-Zib2017 GitHub] (similar to Simplifier.net)

=Contact=

'''MedMij'''

W: https://www.medmij.nl 

E: [mailto:standaarden@medmij.nl standaarden@medmij.nl]

T: [tel:+31703173434 +31-70 317 3434]

'''Nictiz'''

W: https://www.nictiz.nl

E: [mailto:hl7@nictiz.nl hl7@nictiz.nl]

T: [tel:+31703173450 +31-70 317 3450]

'''Relevant information'''
* [https://medmij.nl/informatiestandaarden/consultatiedocumenten/ Consultation documentation]
* [https://chat.fhir.org chat.fhir.org]
** The public channel for FHIR related questions and discussions

=Release notes=
Release notes can be found on the [[MedMij:V2020.01/Ontwerpen#Release_Notes|functional design page]].

=Releases=
{| class="wikitable" 
! Version !! Date !! Notes
|-
| [[MedMij:V2020.01/FHIR_IG|2020.01]] || 2020-08-11 || Summer release containing fixes for MedMij information standards
|-
| [[MedMij:V2019.01_FHIR_IG|2019.01]] || 2019-03-11 || Spring release containing fixes for all information standards
|-
| [[MedMij:V2018.06_FHIR_IG|2018.06]] || 2018-10-29 || Added GGZ
|-
| [[MedMij:V2018.05_FHIR_IG|2018.05]] || 2018-09-24 || Added GGZ for open consultation
|-
| [[MedMij:V2018.04_FHIR_IG|2018.04]] || 2018-08-29 || eAfspraak fase 2
|-
| [[MedMij:V2018.03_FHIR_IG|2018.03]] || 2018-05-07 || Published BgZ 2017 and GP Data
|-
| [[MedMij:V2018.02_FHIR_IG|2018.02]] || 2018-03-29 || Added BgZ 2017
|-
| [[MedMij:V2018.01_FHIR_IG|2018.01]] || 2018-02-21 || Added GP patient data
|-
| [[MedMij:V2017.04_FHIR_IG|2017.04]] || 2017-12-18 || Added Appointments, Medication, Laboratory results, AllergyIntolerance, Self-measurements
|-
| [[MedMij:V2017.03_FHIR_IG|2017.03]] || 2017-11-07 || Added PDF/A
|-
| [[MedMij:V2017.02_Ontwerpen|2017.02]] || 2017-10-11 || Unchanged. No wiki pages created for FHIR
|-
| [[MedMij:V2017.01_FHIR_IG|2017.01]] || 2017-10-02 || Initial version containing Patient Administration Resources, Patient Summary (BgZ), 
|}

{{MedMij:Sjabloon_Support}}