Brontekst bekijken van MedMij:Vprepub-2019.01 FHIR IG

{{#customtitle:MedMij FHIR Implementation Guide}}
{{MedMij:V2019.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:V2019.01_Ontwerpen|Functioneel]]                
circle 1787 230 212 [[MedMij:V2019.01_FHIR_IG|Technisch]]                
desc none                    
</imagemap>
__TOC__

{{large|Quick links}}
----
{|  
! [[Bestand:BGZ_icoon.png |link=MedMij:V2019.01_FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]] 
!  &nbsp;&nbsp;
! [[Bestand:Medication_Icoon.png |link=MedMij:V2019.01_FHIR_MedicationProcess|100px |Medication Process]]
!  &nbsp;&nbsp;
! [[Bestand:AllergyIntolerance.png |link=MedMij:V2019.01_FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
!  &nbsp;&nbsp;
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:V2019.01_FHIR_VitalSigns|105px |Self-Measurements]]
! &nbsp;&nbsp;
! [[Bestand:LabResults@2x.png |link=MedMij:V2019.01_FHIR_LaboratoryResults |100px|Laboratory Results]]
! &nbsp;&nbsp;
|}

{|  
! [[Bestand:PDF-A icoon.png|link=MedMij:V2019.01_FHIR_PDFA |100px |PDF/A - Health Documents]]
! &nbsp;&nbsp;
! [[Bestand:EAfspraak_-_text.png |link=MedMij:V2019.01_FHIR_eAfspraak |98px |eAfspraak - Appointments]]
! &nbsp;&nbsp;
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:V2019.01_FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
! &nbsp;&nbsp;&nbsp;
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:V2019.01_FHIR_GGZ |105px |GGZ]]
! &nbsp;&nbsp;
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:V2019.01_FHIR_Images |105px |Images]]
|}

=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:V2019.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 ([http://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 ZIB's) for The Netherlands. ZIB's contain definitions of healthcare concepts. MedMij information standards contain mappings to these ZIB's. MedMij creates FHIR profiles based on ZIB's 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 [http://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 “Authorization”. 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:V2019.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:V2019.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 implemenation 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:V2019.01_FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]] 
!  &nbsp;&nbsp;
! [[Bestand:Medication_Icoon.png |link=MedMij:V2019.01_FHIR_MedicationProcess|100px |Medication Process]]
!  &nbsp;&nbsp;
! [[Bestand:AllergyIntolerance.png |link=MedMij:V2019.01_FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
!  &nbsp;&nbsp;
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:V2019.01_FHIR_VitalSigns|105px |Self-Measurements]]
! &nbsp;&nbsp;
! [[Bestand:LabResults@2x.png |link=MedMij:V2019.01_FHIR_LaboratoryResults |100px|Laboratory Results]]
! &nbsp;&nbsp;
|}

{|  
! [[Bestand:PDF-A icoon.png|link=MedMij:V2019.01_FHIR_PDFA |100px |PDF/A - Health Documents]]
! &nbsp;&nbsp;
! [[Bestand:EAfspraak_-_text.png |link=MedMij:V2019.01_FHIR_eAfspraak |98px |eAfspraak - Appointments]]
! &nbsp;&nbsp;
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:V2019.01_FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
! &nbsp;&nbsp;&nbsp;
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:V2019.01_FHIR_GGZ |105px |GGZ]]
! &nbsp;&nbsp;
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:V2019.01_FHIR_Images |105px |Images]]
|}

=Use case overarching principles=
==Content Types and encodings==
MedMij uses the [http://hl7.org/fhir/http.html#mime-type FHIR RESTful framework]. This framework defines at least three content-types to send/retrieve information. Clients may ask servers specifically for information in a given content-type. Servers SHALL support server-driven content negotiation as described in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12 section 12]  of the HTTP specification.

* XML: application/fhir+xml
* JSON: application/fhir+json
* RDF: text/turtle - Not supported in MedMij

Servers in MedMij SHALL support both XML and JSON. Clients MAY negotiate using the HTTP standard which they prefer. If a client does not request a specific content-type, then it is server discretion if they respond using XML or JSON content-type.

FHIR uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1) defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set the character encoding to UTF-8 using the charset parameter of the MIME-type in the Content-Type header. Requests MAY also specify this charset parameter in the Accept header and/or use the Accept-Charset header.

==Retrieve information: what's new==
Retrieving information that was added, changed, deleted relative to a date may be done using the search parameter <code>_lastUpdated</code> available for any resource. Using the parameter <code>_lastUpdated</code> a system may query for data that is ''new'' since the previous query. Any FHIR server is expected to support this parameter <code>_lastUpdated</code>.

The search parameter _lastUpdated can be used to select resources based on the last time they were changed:

 GET [base]/Observation?_lastUpdated=gt2018-10-01

This search finds any observations changed since Oct 1, 2018. More information may be found in the section _lastUpdated in the FHIR specification: http://hl7.org/fhir/STU3/search.html#lastUpdated. 

An example search request is shown below.

 <pre>GET [base]/Consent?category=http://snomed.info/sct|11291000146105&_lastUpdated=gt2018-10-01</pre>

This search finds all Consent resources with a category SNOMED code 11291000146105 that have been changed since Oct 1, 2018.

==Use of the reference datatype==
FHIR resources act like the internet where resources point to each other through references. The [http://hl7.org/fhir/STU3/references.html#Reference reference datatype] is comparable to web pages pointing to other web pages, scripts and images. Each reference may be either '''internal''' or '''external'''. The datatype supports a display attribute, comparable to a link title in a web page, and an identifier. The identifier acts as a logical reference when the literal reference is not known. Literal references work based on the FHIR logical id, not the identifier, attribute.

{| class="wikitable"
|+MedMij constraints on [http://hl7.org/fhir/STU3/references.html#Reference FHIR STU3 reference datatype]
! Name !! Flags !! Card. || Type || Description & Constraints
|-
| Reference || Σ I || || Element || A reference from one resource to another<br/>''+ SHALL have a contained resource if a local reference is provided''<br/>'''+ SHALL have a reference or identifier unless specified otherwise''' *
|-
|&#160;&#160;&#160;&#160;reference || Σ || 0..1 || string || Literal reference, Relative, internal or absolute '''(not preferred)''' URL
|-
|&#160;&#160;&#160;&#160;identifier || Σ || 0..1 || Identifier || Logical reference, when literal reference is not known
|-
|&#160;&#160;&#160;&#160;display || Σ || '''1..1''' || string || Text alternative for the resource
|}

In loosely coupled context it is usually good practice to include information rather than have systems progressively retrieve it. When the FHIR servers are in fact a facade on non-FHIR systems, it may not be possible to build external references from the resource id, as non-FHIR systems may not support that concept. Example: a resource for the general practitioner will have an AGB and/or UZI identifier in any information system, the id for the same resource might not be known anywhere. The expectation within MedMij is therefore that the vast majority of references will be based on internal references or identifier.

The basic requirements for using references in MedMij are:

* The ''reference'', if used, SHALL be resolvable
** External references SHALL be regarded in the same context as the resource itself. For internal references, this is guaranteed by default. If the current security context is insufficient for retrieving the reference, then additional negotiation for appropriate privileges may be required.
** External references are preferably relative as opposed to absolute.
* The ''display'' attribute SHALL be used to provide a very short description of the target resource.

Note: there is a known weakness in the Reference datatype for FHIR STU3 which is fixed in FHIR R4. When the reference datatype element could point to multiple types of resources, e.g. Patient.generalPractitioner reference(Organization | Practitioner), you cannot know what type is meant when you only have an identifier for reference. For this reason:

<nowiki>*</nowiki> Note: the Reference datatype SHALL have a reference or identifier unless specified otherwise. There is a known limitation in some of the FHIR STU3 resources where the appropriate reference type is not available. Examples include PractitionerRole which is missing from Encounter.participant (prevents proper context of the attending physician) and Patient which is missing from Media.operator (prevents patient-generated Media). In such cases, an extension will contain the reference of the appropriate type. This leads to slight duplication: the original Reference.display will be duplicated into the Reference.extension.valueReference.display. Systems that do not know about the extension would thus still have access to the regular Reference.display. 

* Literal (internal/external) references are preferred over logical references when a choice in resource type is available.

==Use of coded concepts==
Coded information is extremely important for interoperability between systems. It enables systems to act on information rather than have human read everything. It enables medication related alerts, exercise encouragements because your weight increased and many more things. Coded information only works properly when codes are predictable, and in the HCIMs and the profiles we strive towards that. However it is likely that unknown codes present itself in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a now deprecated way. When this happens it is vital that the sender includes the semantics of the code in his communication.

The generic profiles may not always require the use of (CodeableConcept.)[http://hl7.org/fhir/datatypes.html#coding Coding.display] and/or [http://hl7.org/fhir/datatypes.html#codeableconcept CodeableConcept.text], because in closely coupled situations this may be overkill. Within the loosely coupled MedMij context however, systems SHALL include .display and/or .text for coded data in FHIR instances.

=FHIR Packages=
MedMij adopts the FHIR Packaging mechanism to support consistent versioning of profiles and related conformance resources such as OperationDefinitions. FHIR Packaging is based on the NPM Packaging mechanism and offers developers a convenient way to include the conformance resources in their favorite IDE. The relevant package version is indicated and linked in the information standards technical design page.

For even more background information:
* [https://blog.fire.ly/2017/11/28/versioning-and-canonical-urls/ What is the problem that packaging could address]
* [https://simplifier.net/organization/firely/news/55 Introducing the Simplifier FHIR Package Server] (includes what problem packaging addresses)
* [https://simplifier.net/organization/firely/news/56 Firely Torinox introduction] (this is one of the tools that's useful for working with FHIR packages)
* [http://wiki.hl7.org/index.php?title=FHIR_NPM_Package_Spec The HL7 wiki that outlines the base specification]

{{NoteBox|It is '''not''' required to implement FHIR based information standards using the packaging mechanism. It is still possible to download all or selected resources from Simplifier on as-needed basis. You are however encouraged to invest in dealing with packages.}}

=Relevant links=
'''HL7 FHIR specification'''
* [http://hl7.org/fhir/STU3/index.html HL7 FHIR STU3]
* [http://wiki.hl7.org/index.php?title=FHIR FHIR wiki]

'''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: http://www.medmij.nl 

E: standaarden@medmij.nl

'''Nictiz'''

W: https://www.nictiz.nl

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

'''Feedback on content in open consultation'''
* [https://www.medmij.nl/consultatiedocumenten/ Documentation]
* [https://bits.nictiz.nl/secure/BrowseProjects.jspa#all BITS for issues]

'''FHIR Questions and Discussions'''

* [http://chat.fhir.org chat.fhir.org]

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

=Releases=
{| class="wikitable" 
! Version !! Date !! Notes
|-
| [[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), 
|}