Brontekst bekijken van mp:V9 2.0.0-beta2 FHIR MedicationProcess

__NUMBEREDHEADINGS__
{{DISPLAYTITLE:FHIR Implementation Guide Medication Process Medication Process 9 version 2.0.0 bèta{{VersieInfo|mp9|release=MP9 2.0.0 bèta}} }}
{{IssueBox|This publication has [[Media:20210826 - Roadmap releases informatiestandaard Medicatie Proces 9.pdf|beta status]] and is being further developed for the Kickstart Medicatieoverdracht. Final publication expected in March 2022. For an overview of current documentation for Medication Process see here [[Landingspagina_Medicatieproces]]}}

__TOC__

=Introduction=
This is the FHIR implementation guide for the information standard Medicatieproces 9 version 2.0.0 bèta. This standard is described in [[mp:V9_2.0.0_Ontwerp_medicatieproces_ENG|this functional specification]] and implemented here using [https://www.hl7.org/fhir/R4/ HL7 FHIR, R4]. This implementation guide assumes that the reader is familiar with this FHIR version.

Apart from this document, the guidelines as specified in [[FHIR:Vdraft FHIR IG R4|general FHIR Implementation Guide]] apply. In particular, the reader should take note of the [[FHIR:Vdraft_FHIR_IG_R4#Use_case_overarching_principles|Use case overarching principles]] and the use of [[FHIR:Vdraft_FHIR_IG_R4#FHIR_Packages|FHIR packages]].

Use cases:
* [[#Use_case:_retrieve_medication_data|Retrieve medication data]]
* [[#Use_case:_retrieve_medication_overview|Retrieve medication overview]]

=Actors involved=
{| class="wikitable"
! colspan="2" style="text-align:left;" | Persons
! colspan="2" style="text-align:left;" | Systems
! colspan="2" style="text-align:left;" | FHIR Capability Statements
|-
! style="text-align:left;" |Name
! style="text-align:left;" |Description
! style="text-align:left;" |Name
! style="text-align:left;" |Description
! style="text-align:left;" |Name
! style="text-align:left;" |Description
|-
| Patient or Healthcare professional
| The user of a personal healthcare environment (PHR) or a healthcare information system (XIS).
| Client
| PHR or XIS
|[[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/MedicationProcess-ClientCapabilities|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2|title=CapabilityStatement: Client}}
| Client requirements 
|-
| Healthcare professional
| The user of a healthcare information system (XIS)
| Server
| XIS
|[[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/MedicationProcess-ServerCapabilities|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2|title=CapabilityStatement: Server}}
| Server requirements 
|}

=Use case: retrieve medication data=
==Introduction==
The retrieve medication data transaction is used by the client to retrieve medication data from a server. The client can retrieve its desired information by searching on specific medication building blocks.

==Actors==
{| class="wikitable" "cellpadding="10"
! style="text-align:left;"| '''Transaction group'''
! style="text-align:left;"| '''Transaction'''
! style="text-align:left;"| '''Actor'''
! style="text-align:left;"| '''Role'''
|-
|style="background-color: white;vertical-align:top;" rowspan="2"|[https://decor.nictiz.nl/pub/medicatieproces/mp-html-20210921T194523/sc-2.16.840.1.113883.2.4.3.11.60.20.77.3.27-2021-04-02T093339.html#_2.16.840.1.113883.2.4.3.11.60.20.77.4.170_20210402093339 Retrieve Medication Data (PULL)] 
|style="background-color: white;vertical-align:top;"|[https://decor.nictiz.nl/pub/medicatieproces/mp-html-20210921T194523/tr-2.16.840.1.113883.2.4.3.11.60.20.77.4.171-2021-04-02T093339.html Consulting medication data]
|style="background-color: white;vertical-align:top;"|Client 
|style="background-color: white;vertical-align:top;"|Request medication data
|-
|style="background-color: white;vertical-align:top;"|[https://decor.nictiz.nl/pub/medicatieproces/mp-html-20210921T194523/tr-2.16.840.1.113883.2.4.3.11.60.20.77.4.172-2021-04-02T093339.html Making medication data available]
|style="background-color: white;vertical-align:top;"|Server
|style="background-color: white;vertical-align:top;"|Serve medication data
|}
The names of the transaction groups and transactions link to the functional definition in an ART-DECOR publication which details per scenario which data elements are used.

==Invocations==

===Request message===
When a patient or healthcare professional wants to obtain all medication data or specific parts matching various parameters, it issues a retrieve medication data request message.
This message uses the HTTP GET method parameterized query against the server's medication FHIR endpoints. These endpoints can be one of the following: 
* MedicationRequest
* MedicationDispense
* MedicationStatement
* MedicationAdministration

The search interaction is performed by an HTTP GET conform the [http://hl7.org/fhir/R4/search.html FHIR search specification], as shown below. This URL is configurable by the client by configuring the query search parameters and search control parameters to modify the behaviour of the server such as response format and pagination. Multiple request messages may be needed to retrieve all desired information.

<pre>
GET [base]/[type]{?[parameters]}
</pre>

====Patient identification====
This implementation guide assumes that the client system is able to make a connection to the right server that contains the patient's information. It does not provide information on finding the right server nor does it provide information about security. Moreover, each transaction is performed in the context of a specific (authenticated) patient, for whose context might have been established using the authentication mechanisms described in external specifications such as the MedMij 'Afsprakenstelsel' or through the usage of search parameters for patient identification. Each server is required to perform filtering based on the patient associated with the context for the request or based on the patient identification search parameters, so only the records associated with the authenticated patient are returned. 

When patient identification requires the use of search parameters, the following search parameters SHALL be supported:

* Patient: {{fhir|identifier}}
* MedicationRequest: {{fhir|patient}}
* MedicationDispense: {{fhir|patient}}
* MedicationStatement: {{fhir|patient}}
* MedicationAdministration: {{fhir|patient}}

An example of a request that retrieves all MedicationRequest resources of a patient with a fake BSN of 11122233:

<pre>GET [base]/MedicationRequest?patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>

====Search Parameters====
The client MAY supply, and the server SHALL be capable of processing, all query parameters listed in the table below.

{| class="wikitable"
! style="font-weight: bold;text-align:left;" | MP9 search parameters
! style="font-weight: bold;text-align:left;" | Description
! style="font-weight: bold;text-align:left;" | FHIR search parameter
! style="font-weight: bold;text-align:left;" | FHIR resource
! style="font-weight: bold;text-align:left;" | Example
|-
| Identification
| Search on identifier.
| {{fhir|identifier}}
| MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration
| Retrieves a MedicationRequest resource with the identifier 999922448.
<pre>GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448</pre>
|-
| Identification
| Search on the pharmaceutical treatment identifier. Note: retrieval of all medication resoures belonging to one pharmaceutical treatment requires to search on all medication resource types.
| {{fhir|pharmaceutical-treatment-identifier}} <ref name="custom-searchparameter"/>
| MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration
| Retrieves all MedicationRequest resources that are part of the pharmaceutical treatment with identifier value of 1247848.
<pre>GET [base]/MedicationRequest?pharmaceuticaltreatment=http://example.nl/fhir/NamingSystem/medicationtreatment|1247848 </pre>
|-
| rowspan="4" |Type
| rowspan="4" |Search on type of medication building block. 
| rowspan="4" |{{fhir|category}} <sup><ref name="custom-searchparameter">The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification.</ref>,<ref>The FHIR profiles that represent the medication building blocks contain fixed code values in the ''.category'' elements to allow searching on specific medication building blocks.</ref></sup>
| MedicationRequest
| Retrieves all MedicationRequest resources that represent a zib MedicationAgreement.
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005</pre>
Retrieves all MedicationRequest resources that represent a zib DispenseRequest.
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108</pre>
|-
| MedicationDispense
| Retrieves all MedicationDispense resources that represent a zib Dispense.
<pre>GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005</pre>
Retrieves all MedicationRequest resources that represent the zib AdministrationAgreement.
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|422037009</pre>
|-
| MedicationStatement
| Retrieves all MedicationStatement resources that represent a zib MedicationUse2.
<pre>GET [base]/MedicationStatement?category=http://snomed.info/sct|422979000</pre>
|-
| MedicationAdministration
| Retrieves all MedicationAdministration resoures that represent a zib MedicationAdministration2.
<pre>GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&_include=MedicationStatement:medication</pre>
|-
| ProductCode
| Search on medication code.
| {{fhir|code}}
| MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration
| Retrieves all MedicationRequest resources that represent a zib MedicationAgreement and have Carbasalaatcalcium Sandoz 600 30 as medication.
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554</pre>
|-
| UsePeriod
| Search on medication use in the past, present or future within the specified time period.
| {{fhir|period-of-use}}<ref name="custom-searchparameter"/>
| MedicationDispense, MedicationRequest
| Retrieves all MedicationRequest resources that represent a zib MedicationAgreement and were in effect from 01-01-2010.
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&period-of-use=ge2010-01-01</pre>
|-
| DispensePeriod 
| Returns all medication dispenses within the specified time period.
| {{fhir|whenhandedover}}
| MedicationDispense
| Retrieves all MedicationDispense resources that represent a zib Dispense and were handed over within a 2 year period.
<pre>GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005&whenhandedover=ge2010-01-01&whenhandedover=le2011-12-31</pre>
|-
| AdministrationPeriod 
| Returns all medication administrations within the specified time period.
| {{fhir|effective-time}}
| MedicationAdministration
| Retrieves all MedicationAdministration resources that represent a zib MedicationAdministration2 and were administration happened within a 2 year period.
<pre>GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&effective-time=ge2010-01-01&effective-time=le2011-12-31</pre>
|-
| -
| The client may request that the server returns resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources.
| {{fhir|_include}}
| MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration
| Retrieves all MedicationRequest resources that have Carbasalaatcalcium Sandoz 600 30 as medication and includes the Medication resource in the search results.
<pre>GET [base]/MedicationRequest?medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554&_include=MedicationRequest:medication</pre>
|}

====Custom Search Parameters====
The following custom search parameters are defined for this use case:

* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/category|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/period-of-use|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}} 
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/pharmaceutical-treatment-identifier|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}

====Retrieve all medication data====
A common scenario for a client is to request all known medication data. The following requests retrieve all known medication data per building block and will include the Medication resource:
<pre>
GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&_include=MedicationRequest:medication
GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108&_include=MedicationRequest:medication
GET [base]/MedicationRequest?category=http://snomed.info/sct|274512008&_include=MedicationRequest:medication
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005&_include=MedicationDispense:medication
GET [base]/MedicationDispense?category=http://snomed.info/sct|422037009&_include=MedicationDispense:medication
GET [base]/MedicationStatement?category=http://snomed.info/sct|422979000&_include=MedicationStatement:medication
GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&_include=MedicationStatement:medication
</pre>

===Response message===
The server returns a HTTP Status code appropriate to the processing as well as a FHIR Bundle of type 'searchset' including the matching medication data. The returned data to the client SHALL be a valid instance of the applicable profile in the [[#List_of_Profiles|List of Profiles]].

'''Note''' that the medication resources are grouped per 'pharmaceutical treatment' conform to the [https://informatiestandaarden.nictiz.nl/wiki/mp:V9_2.0.0_Ontwerp_medicatieproces_ENG#.27Medicamenteuze_behandeling.27 Medication Process specification]. Grouping SHALL be done by use of a 'Pharmaceutical Treatment Identifier'. This identifier shall be the same across different related medication resources that constitute one medication treatment. The {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/ext-PharmaceuticalTreatment.Identifier|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1|title=PharmaceuticalTreatmentIdentifier extension}} is to be used for this grouping purpose.

==List of Profiles==
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.r4.zib2020|v2=0.1.0-beta1}}

{| class="wikitable" width="1400px"
|-style="background-color: #1F497D; color: white; font-weight: bold; "
|zib/MP building block name NL||zib/MP building block name EN||FHIR Resource||FHIR Profile
|-style="vertical-align:top; background-color: #E3E3E3; 
|-
| Medicatieafspraak||MedicationAgreement||MedicationRequest||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
|WisselendDoseerschema||VariableDosingRegimen||MedicationRequest||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-VariableDosingRegimen|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| Verstrekkingsverzoek||DispenseRequest||MedicationRequest|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-DispenseRequest|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-AdministrationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| Verstrekking||Dispense||MedicationDispense||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationDispense|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| Medicatiegebruik2||MedicationUse2||MedicationStatement||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationUse2|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| MedicatieToediening2||MedicationAdministration2||MedicationAdministration|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAdministration2|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|}

Note that besides profiles listed in the above table, also profiles referred from/used by these profiles are applicable. These are profiles for zibs Patient, HealthProfessional, HealthcareProvider.

=Use case: retrieve medication overview=
==Introduction==
The retrieve medication overview transaction is used by the client to retrieve a medication overview from the server.

==Actors==
{| class="wikitable" "cellpadding="10"
! style="text-align:left;"| '''Transaction group'''
! style="text-align:left;"| '''Transaction'''
! style="text-align:left;"| '''Actor'''
! style="text-align:left;"| '''Role'''
|-
|style="background-color: white;vertical-align:top;" rowspan="2"|[https://decor.nictiz.nl/pub/medicatieproces/mp-html-20210921T194523/sc-2.16.840.1.113883.2.4.3.11.60.20.77.3.28-2021-04-14T153926.html#_2.16.840.1.113883.2.4.3.11.60.20.77.4.189_20210414153926 Retrieve Medication overview (PULL)]
|style="background-color: white;vertical-align:top;"|[https://decor.nictiz.nl/pub/medicatieproces/mp-html-20210921T194523/tr-2.16.840.1.113883.2.4.3.11.60.20.77.4.190-2021-04-14T153926.html Consulting medication overview]
|style="background-color: white;vertical-align:top;"|Client
|style="background-color: white;vertical-align:top;"|Request Medication overview
|-
|style="background-color: white;vertical-align:top;"|[https://decor.nictiz.nl/pub/medicatieproces/mp-html-20210921T194523/tr-2.16.840.1.113883.2.4.3.11.60.20.77.4.191-2021-04-14T153926.html Making medication overview available]
|style="background-color: white;vertical-align:top;"|Server
|style="background-color: white;vertical-align:top;"|Serve Medication overview 
|}
The names of the transaction groups and transactions link to the functional definition in an ART-DECOR publication which details per scenario which data elements are used.

==Invocations==
===Request message===
When the patient or healthcare professional wants to obtain a patient's medication overview, it issues a Consulting medication overview request message.
This message uses an extended operation on the RESTful API to obtain a medication overview from a server. An operation is needed because the server will formulate the content of the response based on its internal business logic. The medication overview can not easily be described by standardized restful requests. 

The client executes a {{Simplifier|http://nictiz.nl/fhir/OperationDefinition/Medication-Overview|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2|title=medication-overview operation}} with HTTP POST against the server base endpoint as shown below.

<pre>
POST [base]/$medication-overview
</pre>

===Response message===
The server returns a HTTP Status code appropriate to the processing of the operation. The successful outcome of the {{Simplifier|http://nictiz.nl/fhir/OperationDefinition/Medication-Overview|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2|title={{fhir|$medication-overview}} operation}} is the body of the medication overview response message. Successful processing of this operation should result in a Bundle recourse of type 'searchset', containing one List and one Patient resource as entries along with all the resources that represent the current medication overview. These resources SHALL be referenced from the List resource. The clinical content of the medication overview is defined in the [https://informatiestandaarden.nictiz.nl/wiki/mp:V9_2.0.0_Ontwerp_medicatieproces_ENG#Medication_overview_and_inference_rules Medication Process specification]. 

The Bundle profile represents the structure of the retrieve medication overview response message. The List profile represents the medication overview. The List contains the medication overview metadata and references to all resources that constitute the medication overview. These resources are included in the Bundle as entries. The {{fhir|Bundle.total}} value contains the number of matching zib: MedicationUse, AdministrationAgreement and MedicationAgreement. Other included resources, such as Medication resources, are not included in the total. The returned Bundle has at least one List and one Patient resource. The returned data to the client SHALL be a valid instance of its applicable profile as shown in the [[#List_of_Profiles|List of Profiles]].

'''Note''' that the medication resources blocks are grouped per 'pharmaceutical treatment' conform to the [https://informatiestandaarden.nictiz.nl/wiki/mp:V9_2.0.0_Ontwerp_medicatieproces_ENG#.27Medicamenteuze_behandeling.27 Medication Process specification]. Grouping SHALL be done by use of a 'Pharmaceutical Treatment Identifier'. This identifier shall be the same across different related medication resources that constitute one medication treatment. The {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/ext-PharmaceuticalTreatment.Identifier|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1|title=PharmaceuticalTreatmentIdentifier extension}} is to be used for this grouping purpose.

==List of Profiles==
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.r4.medicationprocess9|v1=2.0.0-beta2|p2=nictiz.fhir.nl.r4.zib2020|v2=0.1.0-beta1}}

{| class="wikitable" 
|-style="background-color: #1F497D; color: white; font-weight: bold; "
|zib name NL||zib name EN||FHIR Resource||FHIR Profile
|-style="vertical-align:top; background-color: #E3E3E3; 
|-
| - || - || Bundle || {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/Bundle-MedicationOverview|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2}}
|-
| - || - || List || {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/MedicationOverview|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2}}
|-
| Medicatieafspraak||MedicationAgreement||MedicationRequest|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-AdministrationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|-
| Medicatiegebruik||MedicationUse||MedicationStatement|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationUse2|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
|}

Note that besides profiles listed in the above table, also profiles referred from/used by these profiles are applicable. These are profiles for zibs Patient, HealthProfessional, HealthcareProvider, BodyWeight and BodyHeight.

=Release notes=
Release notes can be found on the [[mp:V9_2.0_Ontwerp_medicatieproces_patient#Release_notes|functional design page]].

=Footnotes=
<references/>