Brontekst bekijken van MedMij:Vprepub-2019.01 FHIR IG

__NOINDEX__
{{MedMij:Vprepub-2019.01_Issuebox}}
__NUMBEREDHEADINGS__
{{DISPLAYTITLE:MedMij FHIR Implementation Guide}}

[[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:Vprepub-2019.01_Ontwerpen|Functioneel]]                
circle 1787 230 212 [[MedMij:Vprepub-2019.01_FHIR_IG|Technisch]]                
desc none                    
</imagemap>
__TOC__

=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:Vprepub-2019.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://medmij.nl/media/factsheet-fhir 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 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 [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:Vprepub-2019.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:Vprepub-2019.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.

{| class="wikitable" 
| style="background-color: #4AB8A7;; color: white; font-weight: bold; text-align:center; border: 1px solid black;"   colspan="6" | Index raadplegen / beschikbaarstellen
|-style="background-color: #4AB8A7;; color: white; text-align:left; border: 1px solid black;" 
|style="width:200px; border: 1px solid black;" colspan="2"| Information standard
|style="width:20px; border: 1px solid black;"| Version
|style="width:600px; border: 1px solid black;"| Use case
|style="width:200px; border: 1px solid black;"| Functional 
|style="width:200px; border: 1px solid black;"| Technical
|-style="background-color: white;"
|[[Bestand:BGZ_icoon_zonder_tekst.png|link=https://www.nictiz.nl/standaarden/basisgegevensset-zorg|Basissetgegevens Zorg|49px]]||[https://www.nictiz.nl/standaarden/basisgegevensset-zorg BgZ]||||[https://www.nictiz.nl/standaarden/basisgegevensset-zorg BgZ], based on zibs release 2017||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>BgZ</s>]]||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>BgZ in FHIR</s>]]
|-
|[[Bestand:Lab.png|link=https://www.nictiz.nl/standaardisatie/informatiestandaarden/laboratoria|Labuitwisseling|49px]]||[https://www.nictiz.nl/standaardisatie/informatiestandaarden/laboratoria LaboratoryResults]||||LaboratoryResults||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>LaboratoryResults</s>]]||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>LaboratoryResults in FHIR</s>]]
|-style="background-color: white;" 
|rowspan="3"|[[Bestand:Medicatie.png|link=https://www.nictiz.nl/Paginas/Informatiestandaard-Medicatieproces.aspx|49px]]
|rowspan="3"|[https://www.nictiz.nl/Paginas/Informatiestandaard-Medicatieproces.aspx Medication Process]
|rowspan="3"|
||Medication Overview
||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Medication overview</s>]]
||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Medication overview in FHIR</s>]]
|-style="background-color: white;"
||Medication Information ||[[MedMij:Vprepub-2019.01_OntwerpMedicatie#Use_case:_Raadplegen_medicatiegegevens_door_pati.C3.ABnt|Medication Information]]
||[[MedMij:Vprepub-2019.01_FHIR_MedicationProcess#Use_case:_retrieve_medication_information |Medication Information in FHIR]]
|-style="background-color: white;"
||Dispense 6.12 Conversion||[[MedMij:Vprepub-2019.01_OntwerpMedicatie#Use_case:_Raadplegen_verstrekkingenvertaling_.28medicatieverstrekkingen_van_het_LSP.29_door_pati.C3.ABnt|Dispense 6.12 Conversion]]
||[[MedMij:Vprepub-2019.01_FHIR_MedicationProcess#Use_case:_retrieve_medication_information|Dispense612ToFHIRConversion]]
|-
|rowspan="2"|[[Bestand:Allergie.png|link=MedMij:Vprepub-2019.01_OntwerpAllergieIntolerantie| AllergieIntolerantie|49px]]
|rowspan="2"|[[MedMij:Vprepub-2019.01_OntwerpAllergieIntolerantie | AllergyIntolerance]]
|rowspan="2"|
||AllergyIntolerance ||[[MedMij:Vprepub-2019.01_VerlopenGD| <s>AllergyIntolerance</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>AllergyIntolerance in FHIR</s>]]
|-
||AllergyIntolerance from Medication Process 6.12 ||[[MedMij:Vprepub-2019.01_VerlopenGD| <s>AllergyIntolerance from Medication Process 6.12</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>AllergyIntolerance612ToFHIRConversion</s>]]
|-style="background-color: white;"
| [[Bestand:EAfspraak_icoon_zonder_tekst.png|link=MedMij:Vprepub-2019.01_VerlopenGD|49px]]
||eAfspraak
||||Retrieve appointments
||<s>[[MedMij:Vprepub-2019.01_VerlopenGD| eAfspraak]]</s>
||<s>[[MedMij:Vprepub-2019.01_VerlopenGD| eAfspraak in FHIR]]</s>
|-
|[[Bestand:Self-Measuements_zonder_tekst.png|link=MedMij:Vprepub-2019.01_OntwerpZelfmetingen|49px]]
||Vital Signs
||||Retrieve Vital Signs||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Vital Signs</s>]]||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Vital Signs in FHIR</s>]]
|-style="background-color: white;"
|[[Bestand:PDF-A_icoon_zonder_tekst.png|PDF/A|49px]]
||PDF/A
||||Retrieve PDF/A||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>PDF/A</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>PDF/A in FHIR</s>]]
|-
|[[Bestand:Huisartsgegevens-zonder-tekst-dun.png|link=MedMij:Vprepub-2019.01_OntwerpHuisartsgegevens|49px|Huisartsgegevens]]||GP data||||GP data|| [[MedMij:Vprepub-2019.01_VerlopenGD|<s>GP data</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>GP data in FHIR</s>]]
|-style="background-color: white;"
|[[Bestand:GGZ-59.-zondertekst.png|49px|GGZ]]
||Basic GGZ data|||| Basic GGZ data|| [[MedMij:Vprepub-2019.01_VerlopenGD|<s>Basic GGZ data</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Basic GGZ data in FHIR</s>]]
|-
|[[Bestand:BgLZ-icon.png|link=MedMij:Vprepub-2019.01_OntwerpLangdurigeZorg|49px|Basisgegevens Langdurige Zorg]]||BgLZ||||Retrieve BgLZ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>BgLZ</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>BgLZ in FHIR</s>]]
|-
|[[Bestand:vragenlijstenIcoon.png|link=MedMij:Vprepub-2019.01_OntwerpVragenlijsten|49px|Questionnaires]]
||Questionnaires||||Questionnaires||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Questionnaires</s>]] ||[[MedMij:Vprepub-2019.01_VerlopenGD|<s>Questionnaires in FHIR</s>]]
|}

=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==
A key feature of FHIR is the ability of resources to reference each other. This is done using the [https://hl7.org/fhir/STU3/references.html#Reference {{datatype|Reference}} datatype]. This datatype supports two modes of referencing:
; [https://hl7.org/fhir/STU3/references.html#literal Literal references], using the {{fhir|.reference}} element: A relative or absolute REST endpoint containing {{fhir|.id}} of the referenced resource. In a Bundle context, this may also be a reference to a {{fhir|Bundle.resource.fullUrl}}.
; [https://hl7.org/fhir/references.html#logical Logical references], using the {{fhir|.identifier}} element: Meaning a match on the business identifier ({{fhir|.identifier}}) for the referenced resource, without specifying where to find the referenced resource. Note: confusingly, although this reference type is called "logical reference", it does ''not'' act on the "logical identifier" ({{fhir|.id}}) of resources.

The resource/profile will usually constrain which resources may be targeted from a given element. For example, {{fhir|Patient.generalPractitioner}} may point only to an Organization or Practitioner resource, and the nl-core-patient profile further restricts this to the nl-core-organization and nl-core-practitioner profiles{{ref|weakness-target-unavailable}}.

The basic requirements for using references in this context are:
* Either a literal or logical reference SHALL be specified, unless specified otherwise.
** Literal references are preferred over logical references when multiple target resource types/profiles may be used{{ref|weakness-unknown-type}}.
* Literal references SHALL be resolvable.
** External references SHALL be regarded in the same context as the resource itself. If the current security context is insufficient for retrieving the reference, then additional negotiation for appropriate privileges may be required.
** Relative references are preferred over absolute references.
* A short description of the target resource SHALL be included using the {{fhir|.display}} element.

''Note 1'':  {{note|weakness-target-unavailable}}In some circumstances, the constraints om the target are too strict for the use case and the appropriate resource can't be referenced (examples are {{fhir|Encounter.participant}}, which cannot reference a PractitionerRole resource to provide context of the attending physician, and {{fhir|Media.operator}}, which cannot target Patient resources and thus doesn't recognize patient-generated Media). In such cases, the proper reference type is added using an extension within the element that is used to refer the other resource. Because some receiving systems may not be able to handle this extension, the {{fhir|.display}} on both the element itself and the extension SHOULD be populated with the same value.

''Note 2'': {{note|weakness-unknown-type}}There is a known weakness in the Reference datatype for FHIR STU3 which is fixed in FHIR R4: if the reference might have more than one type of resource as target, a receiving system cannot know what type is meant when only an identifier is provided.

== Usage of the <code>id</code> and <code>fullUrl</code> elements in FHIR instances ==

=== <code>id</code> versus <code>identifier</code> ===
FHIR recognizes two fields that are used as identifier for instances: <code>id</code> and <code>identifier</code>. Although these are both identifiers, they are unrelated and serve a completely different purpose:
* <code>id</code> is the logical identifier, or technical identifier, akin to the id-field in a database. It is used as a unique handle for every instance on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. The <code>id</code> has no further meaning outside of the server.
* <code>identifier</code> is a business identifier, which has a meaning ''outside'' of the server. Examples are a registration number of a healthcare provider, a BSN or social security number for citizens, ISBNs for books, etc. Any instance may have multiple kinds of identifiers.

This section is about the <code>id</code> field and more general about the concept of a logical/technical id to identify instances on a server. The usage of the <code>identifier</code> field, i.e. the business identifier, cannot be described in general terms and will be dictated one a use-case basis by the particular profiles.

=== When is <code>id</code> expected? ===

As stated above, the logical id is meant to uniquely identify instances on a particular server; it is a vital component when using FHIR within a RESTful context. So as a rule of thumb, the <code>id</code> element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:
* Any operation where an existing instance on the server is addressed, like reading or updating, ''needs'' a logical id to target said instance for the URL. In these cases, <code>id</code> field SHALL be populated in both the request and the response, and it SHALL match the id in the URL.
* When a client sends a ''new'' instance to a server using a create operation, the <code>id</code> element is ''not'' expected to be present, but the server SHALL populate it in the response. This is because upon sending, these new instances don't exist yet on the server, so a logical id has no meaning. But whenever it is created on the server, it should get a logical id assigned by the server. (Note: it is not strictly prohibited to populate the <code>id</code> field when sending a new instance, but the server SHOULD ignore it).
* When a client performs a search on a server, all instances in the returned searchset Bundle SHALL have the <code>id</code> field populated. Note that in some situations, servers might not support logical id's, for example when it is a stateless middleware server that gets its input from a non-FHIR XIS backend. If this is the case ''and'' if the use case doesn't require read support, [[#uuid-as-logical-id|a single use UUID]] or [[#oid-as-logical-id|an OID]] may be used to populate the <code>id</code> field; however, a server SHOULD try its best to populate it with a meaningful value.

=== Logical ids, <code>fullUrl</code>s and references in Bundles ===

There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the <code>id</code> element of every instance; it is not guaranteed that all instances have a logical id. Instead, Bundles allow an <code>entry.fullUrl</code> element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement:
* The [[#When_is_id_expected.3F|guidelines above]] for populating the <code>id</code> field still apply. 
* If <code>id</code> is present, <code>fullUrl</code> SHALL correspond with it (see below).

<code>fullUrl</code>s may be RESTful URLs, UUIDs or even OIDs, based on the situation (which may be mixed within the same Bundle):
; Instances with a logical id: If an instance can be accessed on the server using RESTful operations, the <code>id</code> of that instance in the Bundle will be populated. The corresponding <code>fullUrl</code> in this case SHALL be the absolute URL to the instance on the server.<p>Instances within the Bundle may use relative references to each other, like they are on the same server. The FHIR machinery specifies how to find the matching instance based on the <code>fullUrl</code>.</p>
; Instances without a logical id: When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:
:* <span id="uuid-as-logical-id"></span>UUIDs can be used as single-use ids that will change each time the Bundle is generated. The <code>fullUrl</code> for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>, while the <code>id</code> field (if present) is the unprefixed UUID.
:* <span id="oid-as-logical-id"></span>OIDs can be used if the instance has an OID-based ''business'' identifier (i.e. the <code>identifier</code> field), like the UZI number of a healthcare provider. The <code>fullUrl</code> will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code>, while the <code>id</code> field (if present) is the unprefixed OID. However, the use of OIDs as id has some limitations:
:** The <code>id</code> has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
:** OID-based id's are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID-based ids.
: Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.

==== Example ====
Consider a client that wants to send a new Observation instance to a server and simultaneously link it to an existing Task instance. This can be done using a transaction Bundle:
<syntaxhighlight lang="xml" highlight="7-8,11,23-24,27-28,33-34,41-42" style="max-height:400px; overflow: auto;">
<Bundle xmlns="http://hl7.org/fhir">
    <!-- Transaction Bundle that will simultaneously create a new instance and update an existing one -->
    <type value="transaction"/>
    
    <!-- A new instance to create -->
    <entry>
        <!-- The new instance doesn't have a logical id yet, so a temporary UUID is used for references within the Bundle -->
        <fullUrl value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
        <resource>
            <Observation>
                <!-- The id field is absent, because the instance doesn't exist yet on the server -->
                ...
            </Observation>
        </resource>
    </entry>
    <request>
        <method value="POST"/>
        <url value="Observation"/>
    </request>

    <!-- An existing instance to update with a reference to the new instance -->
    <entry>
        <!-- RESTful URL of existing Task instance -->
        <fullUrl value="http://example-xis.com/Task/1234"/>
        <resource>
            <Task>
                <!-- Logical id of the instance, matches the fullUrl -->
                <id value="1234"/>
                ...
                <output>
                    ...
                    <valueReference>
                        <!-- Reference to the fullUrl of the new instance -->
                        <reference value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
                    </valueReference>
                </output>
            </Task>
        </resource>
        <request>
            <method value="PUT"/>
            <!-- The path on the server, consistent with fullUrl and id -->
            <url value="Task/1234"/>
        </request>
    </entry>
</Bundle>
</syntaxhighlight>

The server response should then look like:
<syntaxhighlight lang="xml" highlight="5-6,9-10,28-29" style="max-height:400px; overflow: auto;">
<Bundle xmlns="http://hl7.org/fhir">
    <type value="transaction-response"/>
    
    <entry>
        <!-- The newly created instance gets the logical id "5678" from the server -->
        <fullUrl value="http://example-xis.com/QuestionnaireResponse/5678"/>
        <resource>
            <Observation>
                <!-- The id matches the fullUrl -->
                <id value="5678"/>
                ...
            </Observation>
        </resource>
    </entry>
    <response>
        ....
    </request>

    <entry>
        <fullUrl value="http://example-xis.com/Task/1234"/>
        <resource>
            <Task>
                <id value="1234"/>
                ...
                <output>
                    ...
                    <valueReference>
                        <!-- Reference to the relative URL of the created instance may be relative -->
                        <reference value="Observation/5678"/>
                    </valueReference>
                </output>
            </Task>
        </resource>
        <response>
            ....
        </response>
    </entry>
</Bundle>
</syntaxhighlight>

==Use of coded concepts==
Coded information is extremely important for interoperability between systems. It enables systems to act on information rather than have humans read everything for interpretation - it enables medication related alerts, exercise encouragements because of weight increase, and many more things. In the HCIMs and profiles, we therefore strive for complete coverage of all possible situations.

However it is likely that unknown codes present themselves 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. Therefore, it is vital that the sender includes the semantics of the code in his communication using (CodeableConcept.)[http://hl7.org/fhir/datatypes.html#coding coding.display] and/or [http://hl7.org/fhir/datatypes.html#codeableconcept CodeableConcept.text]. Although it might be overkill for the generic profiles to use these fields in closely coupled situations. Within the loosely coupled MedMij context however, systems SHOULD include .display and/or .text for coded data in FHIR instances. Both could be absent for example in historic data or in data acquired without such info from a third party.

===Mapping of coded concepts===
Terminology from HCIMs or UCSDs (use case specific datasets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the HCIM or UCSD. These cases include, but are not limited to, the FHIR resource elements of datatype 'code' (Patient.gender, status elements, structural type elements, etc.). This datatype always describes FHIR specific terminology, which usually doesn't align with the HCIM/UCSD terminology.

In these cases, a mapping will be provided to explain the relationship between de HCIM/UCSD terminology and the FHIR terminology. This is normally done through a FHIR [https://hl7.org/fhir/STU3/conceptmap.html ConceptMap], which can translate between the terminology used in the HCIM/UCSD, and the terminology that FHIR instances need to adhere to. Usually, the original terminology from the HCIM/UCSD will be communicated as well by adding the extension [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/code-specification code-specification] on the same element. This allows unambiguous interpretation on the receiver end.

Example snippet from an [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/zib-AllergyIntolerance AllergyIntolerance] where both the FHIR terminology ''high'' and the SNOMED CT ''24484000'' terminology are communicated. The FHIR terminology is obtained from the HCIM terminlogy using ConceptMap [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/ConceptMap/MateVanKritiekZijnCodelijst-to-allergy-intolerance-criticality MateVanKritiekZijnCodelijst-to-allergy-intolerance-criticality]:

  <criticality value="high">
    <extension url="http://nictiz.nl/fhir/StructureDefinition/code-specification">
      <valueCodeableConcept>
        <coding>
          <system value="http://snomed.info/sct"/>
          <code value="24484000"/>
          <display value="Severe"/>
        </coding>
      </valueCodeableConcept>
    </extension>
  </criticality>

'''Please note''': Unfortunately, FHIR doesn't have a core structured way for indicating which ConceptMaps to use. Instead, mappings are documented in the description of the element in the profile and/or specifically on the mapping description contained in the element.

To retrieve the indicated ConceptMap on Simplifier, the canonical url from the description needs to be used as search term. We are still examining ways to make this more user friendly, for example by using the [https://hl7.org/fhir/STU3/extension-11179-permitted-value-conceptmap.html extension for ConceptMaps], but that does not work unless various third party tooling is updated.

==Relating FHIR profiles with their functional definitions==
All profiles have a traceable relationship with their functional counterpart(s) based on the element mapping mechanism in FHIR. This allows to:
# define one or more references from a FHIR profile to an external URL where the functional definition can be found
# define for each FHIR profile element to which concept ''within'' a functional definition it corresponds

The functional definition(s) underlying the profile can thus be resolved using the [http://hl7.org/fhir/STU3/structuredefinition-definitions.html#StructureDefinition.mapping StructureDefinition.mapping] metadata field of a profile. To relate a FHIR profile field to a concept from the functional description, the concept ID defined in the [http://hl7.org/fhir/STU3/dataelement-definitions.html#DataElement.mapping DataElement.mapping] can be used to look up the concept in the functional definition. It is possible that a single profile element refers concepts from multiple functional descriptions. Simplifier will show an onverview of all the mappings for a FHIR profile on the dedicated 'mappings' tab, together with a clickable URL to the functional definition. In addition, on the 'overview' tab for each field the relevant mapping can be found.

For example, the profile nl-core-address defines a relationship with [https://simplifier.net/NictizSTU3-Zib2017/nl-core-address/~mappings with four functional definitions], one of which is [https://zibs.nl/wiki/AddressInformation-v1.0(2017EN) AddressInformation-v1.0(2017EN)]. This mapping is identified within the profile using 'hcim-addressinformation-v1.0-2017EN'. Looking at the 'Address.city' element in this profile, one of the mappings is defined as 'hcim-addressinformation-v1.0-2017EN:NL-CM:20.5.3'. This reveals that this element implements (amongst others) the concept from the HCIM AddressInformation-v1.0(2017EN) described using ID 'NL-CM:20.5.3'.

=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)
* [https://confluence.hl7.org/display/FHIR/NPM+Package+Specification The HL7 base specification for FHIR pacakges]

{{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]
* [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: 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:Vprepub-2019.01_Ontwerpen#Release_Notes|functional design page]].

=Releases=
{| class="wikitable" 
! Version !! Date !! Notes
|-
| [[MedMij:Vprepub-2019.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}}