mp:V9 2.0.0-draft FHIR MedicationProcess: verschil tussen versies

Uit informatiestandaarden
Naar navigatie springen Naar zoeken springen
 
(42 tussenliggende versies door dezelfde gebruiker niet weergegeven)
Regel 1: Regel 1:
 
__NUMBEREDHEADINGS__
 
__NUMBEREDHEADINGS__
{{DISPLAYTITLE:FHIR Implementation Guide Medication Process {{VersieInfo|mp|release=V9_2.0}} }}
+
{{DISPLAYTITLE:FHIR Implementation Guide Medication Process {{VersieInfo|mp9|release=V9_2.0}} }}
{{NoteBox|This pages describes Medication process version {{VersieInfo|mp|release=V9_2.0}} and is currently not in use. Active versions can be found through the references on the [https://informatiestandaarden.nictiz.nl/wiki/Landingspagina_Medicatieproces landing page of MedicationProcess].}}
+
{{NoteBox|This pages describes the development version of Medication Process version {{VersieInfo|mp9|release=V9_2.0}}. It is not in use and should not be implemented. Active versions can be found through the references on the [https://informatiestandaarden.nictiz.nl/wiki/Landingspagina_Medicatieproces landing page of Medication Process].}}
  
 
__TOC__
 
__TOC__
  
 
=Introduction=
 
=Introduction=
[[Bestand:Functioneel-02.png|link=mp:V9_2.0.0_Ontwerp_medicatieproces_patient |100px|rechts|Functional design|Go to functional design]]
+
This is the FHIR implementation guide for the information standard Medicatieproces 9, version 2.0. 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.
  
This page describes patient's use cases, in a personal health record (PHR) context, in relation to the information standard [https://www.nictiz.nl/standaardisatie/informatiestandaarden/informatiestandaard-medicatieproces/ Medication Process] (MP). These use cases are based on version {{VersieInfo|mp|release=V9.1}} of this standard. Functional specification of these use cases are described in the [[mp:V9.1.0_Ontwerp_medicatieproces_patient| functional design wiki page]].
+
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]].
 
 
The Medication Process information building blocks are adopted by 'Registratie aan de Bron' and converted to Health and Care Information models (HCIM), also named zibs. In order to exchange medication information between systems, FHIR representations of these HCIMs are made and used in the transactions described on this page.
 
  
 
Use cases:
 
Use cases:
* [[#Use_case:_retrieve_medication_overview|Retrieve a medication overview]]
+
* [[#Use_case:_retrieve_medication_data|Retrieve medication data]]
* [[#Use_case:_retrieve_medication_information|Retrieve medication information]]
+
* [[#Use_case:_retrieve_medication_overview|Retrieve medication overview]]
* [[#Use_case:_retrieve_Dispense612ToFHIRConversion_from_the_LSP|Retrieve Dispense612ToFHIRConversion]]
 
 
 
==Overarching principles==
 
This implementation guide builds on the general guidelines described in the [[MedMij:V2020.01/FHIR_IG#Use_case_overarching_principles|use case overarching principles]].
 
  
 
=Actors involved=
 
=Actors involved=
Regel 33: Regel 27:
 
! style="text-align:left;" |Description
 
! style="text-align:left;" |Description
 
|-
 
|-
| Patient
+
| Patient or Healthcare professional
| The user of a personal healthcare environment.
+
| The user of a personal healthcare environment (PHR) or a healthcare information system (XIS).
| PHR
+
| Client
| Personal health record
+
| PHR or XIS
|[[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/medication-clientcapabilities|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1|title=CapabilityStatement: Client}}
+
|[[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}}
| Medication process client requirements  
+
| Client requirements  
 
|-
 
|-
 
| Healthcare professional
 
| Healthcare professional
| The user of a XIS
+
| The user of a healthcare information system (XIS)
 +
| Server
 
| XIS
 
| XIS
| Healthcare information system
+
|[[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}}
|[[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/medication-servercapabilities|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1|title=CapabilityStatement: Server}}
+
| Server requirements  
| Medication process server requirements  
 
 
|}
 
|}
  
=Use case: retrieve medication overview=
+
=Use case: retrieve medication data=
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]
 
{{FHIR-IG-Afsprakenstelsel-Note}}
 
 
 
 
==Introduction==
 
==Introduction==
The retrieve medication overview transaction is used by the PHR to retrieve a medication overview from the XIS.
+
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==
 
==Actors==
Regel 62: Regel 53:
 
! style="text-align:left;"| '''Role'''
 
! style="text-align:left;"| '''Role'''
 
|-
 
|-
|style="background-color: white;vertical-align:top;" rowspan="2"|Retrieve Medication Overview(PULL)
+
|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;"|Retrieve medication overview request
+
|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;"|Patient (using a PHR)
+
|style="background-color: white;vertical-align:top;"|Client
|style="background-color: white;vertical-align:top;"|Request medication overview from the XIS
+
|style="background-color: white;vertical-align:top;"|Request medication data
 
|-
 
|-
|style="background-color: white;vertical-align:top;"|Retrieve medication overview response
+
|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;"|Healthcare professional (using a XIS)
+
|style="background-color: white;vertical-align:top;"|Server
|style="background-color: white;vertical-align:top;"|Serves medication overview to the PHR
+
|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==
 
==Invocations==
===PHR: request message===
 
This message uses an extended operation on the RESTful API to obtain a medication overview from a XIS. This operation is used because the XIS needs to play an active role in formulating the content of the response.
 
  
====Trigger Events====
+
===Request message===
When the patient (PHR) wants to obtain the current medication overview, it issues a retrieve medication overview 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
  
====Message Semantics====
+
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.
The PHR executes a {{Simplifier|http://nictiz.nl/fhir/OperationDefinition/Medication-Overview|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1|title=medication-overview operation}} with HTTP POST against the XIS's base endpoint as shown below.
 
  
 
<pre>
 
<pre>
POST [base]/$medication-overview
+
GET [base]/[type]{?[parameters]}
 
</pre>
 
</pre>
  
=====Expected Actions=====
+
====Patient identification====
The XIS shall process the operation to find or generate and return the current medication overview.
+
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.  
 
 
===XIS: response message===
 
The XIS returns a HTTP Status code appropriate to the processing of the operation as well as a Bundle of type 'searchset', containing one List and one Patient resource along with other resources that represent the Medication Overview.
 
 
 
====Trigger Events====
 
The XIS completed processing of the retrieve medication overview request message.
 
 
 
====Message Semantics====
 
The outcome of the {{Simplifier|http://nictiz.nl/fhir/OperationDefinition/Medication-Overview|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1|title=<code>$medication-overview</code> operation}} is the body of the medication overview response message. Successful processing of this operation should result in a Bundle recourse, 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.1.0_Ontwerp_medicatieproces#Medicatieoverzicht_en_afleidingsregels Medication Process specification]. The functional dataset of the medication overview can be found on [http://decor.nictiz.nl/medicatieproces/mp-html-20170829T141253/tr-2.16.840.1.113883.2.4.3.11.60.20.77.4.148-2016-11-08T103441.html decor.nictiz.nl].
 
 
 
The content in the response message SHALL be a valid instance of the following profiles that are referenced in the medication-overview operation. Clicking on the link will open the formal definition on Simplifier.net.
 
* '''Medication-Overview OperationDefinition:''' {{Simplifier|http://nictiz.nl/fhir/OperationDefinition/Medication-Overview|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
* '''Bundle profile:''' {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/Bundle-MedicationOverview|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
* '''List profile:''' {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/MedicationOverview|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
 
 
The Bundle profile represents the structure of the retrieve medication overview response message. The List profile represents the actual 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 Bundle.total value contains the number of matching HCIMs: 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.
 
 
 
In the table below, the HCIMs that constitute the clinical content of the Medication Overview and their respective profiles are listed.
 
 
 
'''Note''' that the medication building blocks are grouped per 'medication treatment' conform the [https://informatiestandaarden.nictiz.nl/wiki/mp:V9.1.0_Ontwerp_medicatieproces#Medicamenteuze_behandeling Medication Process specification]. Grouping SHALL be done by use of a 'medication treatment' identifier. This identifier shall be the same across different related medication resources that constitute a medication treatment. The {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/zib-Medication-MedicationTreatment|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0|title=zib-Medication-MedicationTreatment extension}} is added to all medication profiles and can be used for this grouping purpose.
 
 
 
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.stu3.medicationprocess|v1=9.1.0-beta1|p2=nictiz.fhir.nl.stu3.zib2017|v2=2.0.0}}
 
{| class="wikitable"
 
|-style="background-color: #1F497D; color: white; font-weight: bold; "
 
|HCIM name NL||HCIM name EN||FHIR Resource||FHIR Profile
 
|-style="vertical-align:top; background-color: #E3E3E3;
 
|-
 
| Patient
 
| #HCIM Patient|Patient
 
| Patient
 
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
 
|-
 
| Zorgverlener
 
| HealthProfessional
 
| Practitioner
 
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
 
|-
 
| Zorgaanbieder
 
| HealthcareProvider
 
| Organization
 
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-organization|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
 
|-
 
| Medicatiegebruik||MedicationUse||MedicationStatement|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-MedicationUse|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
|-
 
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-AdministrationAgreement|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
|-
 
| Medicatieafspraak||MedicationAgreement||MedicationRequest|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-MedicationAgreement|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
|-
 
| Product||Product||Medication|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-Product|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
|-
 
| GebruiksInstructie||InstructionsForUse||Dosage (datatype)|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-InstructionsForUse|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
|-
 
|}
 
 
 
====Expected Actions====
 
The PHR processes the results according to application-defined rules. The PHR should be robust as the response may contain medication information resources as mentioned in the former section.
 
  
=Use case: retrieve medication information=
+
When patient identification requires the use of search parameters, the following search parameters SHALL be supported:
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]
 
{{FHIR-IG-Afsprakenstelsel-Note}}
 
  
==Introduction==
+
* Patient: {{fhir|identifier}}
The Retrieve Medication Information transaction is used by the PHR to retrieve medication information from the XIS. The PHR can use this transaction to retrieve the desired information by searching on specific medication building blocks.
+
* MedicationRequest: {{fhir|patient}}
 +
* MedicationDispense: {{fhir|patient}}
 +
* MedicationStatement: {{fhir|patient}}
 +
* MedicationAdministration: {{fhir|patient}}
  
==Actors==
+
An example of a request that retrieves all MedicationRequest resources of a patient with a fake BSN of 11122233:
{| 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"|Retrieve Medication Information(PULL)
 
|style="background-color: white;vertical-align:top;"|Retrieve medication information request
 
|style="background-color: white;vertical-align:top;"|Patient (using a PHR)
 
|style="background-color: white;vertical-align:top;"|Request medication information from the XIS
 
|-
 
|style="background-color: white;vertical-align:top;"|Retrieve medication information response
 
|style="background-color: white;vertical-align:top;"|Healthcare professional (using a XIS)
 
|style="background-color: white;vertical-align:top;"|Serves medication information to the PHR
 
|}
 
 
 
==Invocations==
 
===PHR: request message===
 
This message uses the HTTP GET method parameterized query to obtain medication information from a XIS. Multiple different HTTP GET request messages may be needed to retrieve all medication information.
 
 
 
====Trigger Events====
 
When the patient (PHR) wants to obtain medication information matching various parameters, it issues a retrieve medication information request message.
 
 
 
====Message Semantics====
 
The PHR executes an HTTP GET against the XIS's medication FHIR endpoints. These endpoints can be one of the following:  
 
* MedicationRequest
 
* MedicationDispense
 
* MedicationStatement
 
 
 
The search interaction is performed by an HTTP GET conform the [http://hl7.org/fhir/STU3/search.html FHIR search specification], as shown below. This URL is configurable by the PHR by configuring the query search parameters and search control parameters to modify the behaviour of the XIS such as response format, or pagination.
 
  
<pre>
+
<pre>GET [base]/MedicationRequest?patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
GET [base]/[type]{?[parameters]}
 
</pre>
 
  
====Query Search Parameters====
+
====Search Parameters====
The PHR may supply, and the XIS SHALL be capable of processing, all query parameters listed in the table below.
+
The client MAY supply, and the server SHALL be capable of processing, all query parameters listed in the table below.
  
 
{| class="wikitable"
 
{| class="wikitable"
Regel 200: Regel 107:
 
| Identification
 
| Identification
 
| Search on identifier.
 
| Search on identifier.
| <code>identifier</code>
+
| {{fhir|identifier}}
| MedicationRequest, MedicationDispense, MedicationStatement
+
| MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration
 
| Retrieves a MedicationRequest resource with the identifier 999922448.
 
| Retrieves a MedicationRequest resource with the identifier 999922448.
<pre>GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448 </pre>
+
<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="3" |Type
+
| rowspan="4" |Type
| rowspan="3" |Search on type of medication building block (HCIM).  
+
| rowspan="4" |Search on type of medication building block.  
| rowspan="3" |<code>category</code> <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>,</sup><ref name="custom-searchparameter">The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification.</ref>
+
| 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
 
| MedicationRequest
| Retrieves all MedicationRequest resources that represent a HCIM MedicationAgreement.
+
| Retrieves all MedicationRequest resources that represent a zib MedicationAgreement.
 
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005</pre>
 
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005</pre>
Retrieves all MedicationRequest resources that represent a HCIM DispenseRequest.
+
Retrieves all MedicationRequest resources that represent a zib DispenseRequest.
 
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108</pre>
 
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108</pre>
 
|-
 
|-
 
| MedicationDispense
 
| MedicationDispense
| Retrieves all MedicationDispense resources that represent a HCIM Dispense.
+
| Retrieves all MedicationDispense resources that represent a zib Dispense.
 
<pre>GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005</pre>
 
<pre>GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005</pre>
Retrieves all MedicationRequest resources that represent a HCIM AdministrationAgreement.
+
Retrieves all MedicationRequest resources that represent the zib AdministrationAgreement.
 
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|422037009</pre>
 
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|422037009</pre>
 
|-
 
|-
 
| MedicationStatement
 
| MedicationStatement
| Retrieves all MedicationStatement resources that represent a HCIM MedicationUse.
+
| Retrieves all MedicationStatement resources that represent a zib MedicationUse2.
<pre>GET [base]/MedicationStatement?category=urn:oid:2.16.840.1.113883.2.4.3.11.60.20.77.5.3|6</pre>
+
<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
 
| ProductCode
 
| Search on medication code.
 
| Search on medication code.
| <code>code</code>
+
| {{fhir|code}}
| MedicationRequest, MedicationDispense, MedicationStatement, Medication
+
| MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration
| Retrieves all MedicationRequest resources that represent a HCIM MedicationAgreement and have Carbasalaatcalcium Sandoz 600 30 as medication.
+
| 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>
 
<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
 
| UsePeriod
 
| Search on medication use in the past, present or future within the specified time period.
 
| Search on medication use in the past, present or future within the specified time period.
| <code>periodofuse</code> <ref name="custom-searchparameter"/><sup>,</sup><ref name="Medications-periodofuse"/>
+
| {{fhir|period-of-use}}<ref name="custom-searchparameter"/>
 
| MedicationDispense, MedicationRequest
 
| MedicationDispense, MedicationRequest
| Retrieves all MedicationRequest resources that represent a HCIM MedicationAgreement and were in effect from 01-01-2010.
+
| 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&periodofuse=ge2010-01-01</pre>
+
<pre>GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&period-of-use=ge2010-01-01</pre>
 
|-
 
|-
 
| DispensePeriod  
 
| DispensePeriod  
| Returns all medication dispenses within the specific period.
+
| Returns all medication dispenses within the specified time period.
| <code>whenhandedover</code>
+
| {{fhir|whenhandedover}}
 
| MedicationDispense
 
| MedicationDispense
| Retrieves all MedicationDispense resources that represent a HCIM Dispense and were handed over within a 2 year period.
+
| 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>
 
<pre>GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005&whenhandedover=ge2010-01-01&whenhandedover=le2011-12-31</pre>
 
|-
 
|-
| MedicationTreatment
+
| AdministrationPeriod
| Search on the medication treatment identifier
+
| Returns all medication administrations within the specified time period.
| <code>medicationtreatment</code> <ref name="custom-searchparameter"/>
+
| {{fhir|effective-time}}
| MedicationRequest, MedicationDispense, MedicationStatement
+
| MedicationAdministration
| Retrieves all MedicationRequest resources that are part of the medication treatment 1247848.
+
| Retrieves all MedicationAdministration resources that represent a zib MedicationAdministration2 and were administration happened within a 2 year period.
<pre>GET [base]/MedicationRequest?medicationtreatment=http://example.nl/fhir/NamingSystem/medicationtreatment|1247848 </pre>
+
<pre>GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&effective-time=ge2010-01-01&effective-time=le2011-12-31</pre>
 
|-
 
|-
 
| -
 
| -
| The PHR may request that the XIS returns resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources.
+
| 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.
| <code>_include</code>
+
| {{fhir|_include}}
| MedicationRequest, MedicationDispense, MedicationStatement
+
| 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.
 
| 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>
 
<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=====
+
====Custom Search Parameters====
 
 
 
The following custom search parameters are defined for this use case:
 
The following custom search parameters are defined for this use case:
  
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/Medications-category|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
+
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/category|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/Medications-periodofuse|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}} <ref name="Medications-periodofuse">This SearchParameter searches on the FHIR DataType Period in the PeriodOfUse extension, which is added to profiles on MedicationRequest and MedicationDispense resources. Clients use date parameter searches as described by the [http://hl7.org/fhir/stu3/search.html#date FHIR specification]. Servers are expected to take the [http://nictiz.nl/fhir/StructureDefinition/zib-MedicationUse-Duration MedicationUse-Duration extension] into account when processing a client's search. This means that either a Period.start AND Period.end or Period.start AND Duration or Period.end AND Duration is used to determine the search results. To illustrate the expected behavior: if a Period.start and a Duration is known, but not the Period.end, the Duration should be added to the Period.start date to calculate the Period.end. The calculated Period.end date is then used to determine the search results.</ref>
+
* {{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/Medications-medicationtreatment|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
+
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/pharmaceutical-treatment-identifier|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
  
=====Expected Actions=====
+
====Retrieve all medication data====
The XIS shall process the query to discover the medication information that matches the search parameters given.
+
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>
  
===XIS: response message===
+
===Response message===
The XIS returns a HTTP Status code appropriate to the processing as well as a FHIR Bundle including the matching medication information.
+
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]].
  
====Trigger Events====
+
'''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.
The XIS completed processing of the Retrieve medication information request message.  
 
  
====Message Semantics====
+
==List of Profiles==
The returned data to the PHR SHALL conform to the medication HCIMs profiles. The table below lists the medication HCIMs and their respective FHIR profiles. The resources in the response message SHALL be a valid instance of these profiles. All resources SHALL include their related profile canonical URL in the ''meta.profile'' element in order to show compliance.
+
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.r4.zib2020|v2=0.1.0-beta1}}
 
 
'''Note''' that the medication building blocks are grouped per 'medication treatment' conform to the [https://informatiestandaarden.nictiz.nl/wiki/mp:V9.1.0_Ontwerp_medicatieproces#Medicamenteuze_behandeling Medication Process specification]. Grouping SHALL be done by use of a 'medication treatment' identifier. This identifier shall be the same across different related medication resources that constitute a medication treatment. The {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/zib-Medication-MedicationTreatment|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0|title=zib-Medication-MedicationTreatment extension}} is added to all medication profiles and can be used for this grouping purpose.
 
 
 
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.stu3.medicationprocess|v1=9.1.0-beta1|p2=nictiz.fhir.nl.stu3.zib2017|v2=2.0.0}}
 
  
 
{| class="wikitable" width="1400px"
 
{| class="wikitable" width="1400px"
 
|-style="background-color: #1F497D; color: white; font-weight: bold; "
 
|-style="background-color: #1F497D; color: white; font-weight: bold; "
|HCIM name NL||HCIM name EN||FHIR Resource||FHIR Profile
+
|zib/MP building block name NL||zib/MP building block name EN||FHIR Resource||FHIR Profile
 
|-style="vertical-align:top; background-color: #E3E3E3;  
 
|-style="vertical-align:top; background-color: #E3E3E3;  
 
|-
 
|-
| Patient
+
| Medicatieafspraak||MedicationAgreement||MedicationRequest||{{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
| #Zib Patient|Patient
 
| Patient
 
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
 
|-
 
| Zorgverlener
 
| HealthProfessional
 
| Practitioner
 
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
 
|-
 
| Zorgaanbieder
 
| HealthcareProvider
 
| Organization
 
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-organization|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0-beta1}}
 
|-
 
| Medicatiegebruik||MedicationUse||MedicationStatement|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-MedicationUse|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
 
|-
 
|-
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-AdministrationAgreement|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
 
|-
 
|-
| Medicatieafspraak||MedicationAgreement||MedicationRequest|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-MedicationAgreement|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
 
|-
 
|-
| Verstrekking||Dispense||MedicationDispense|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-Dispense|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
 
|-
 
|-
| Verstrekkingsverzoek||DispenseRequest||MedicationRequest|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-DispenseRequest|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
 
|-
 
|-
| Product||Product||Medication|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-Product|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
|-
 
| GebruiksInstructie||InstructionsForUse||Dosage (datatype)|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp-InstructionsForUse|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
 
|}
 
|}
  
====Expected Actions====
+
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.
The PHR shall process the results according to application-defined rules. The PHR should be robust as the response may contain medication information resources that match the query parameters.
 
 
 
=Use case: retrieve Dispense612ToFHIRConversion from the LSP=
 
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]
 
{{FHIR-IG-Afsprakenstelsel-Note}}
 
  
 +
=Use case: retrieve medication overview=
 
==Introduction==
 
==Introduction==
This use case concerns the retrieval of medication dispenses and related medication information that is exchanged between healthcare providers on the 'Landelijk Schakelpunt' (LSP). Over the LSP, these medication dispenses are exchanged based on the information standard MedicationProces version 6.12 in HL7v3-messaging format. In this use case, the requested information by a PHR is converted to FHIR-resources by the XIS.
+
The retrieve medication overview transaction is used by the client to retrieve a medication overview from the server.
  
 
==Actors==
 
==Actors==
Regel 337: Regel 238:
 
! style="text-align:left;"| '''Role'''
 
! style="text-align:left;"| '''Role'''
 
|-
 
|-
|style="background-color: white;vertical-align:top;" rowspan="2"|Retrieve Dispense612ToFHIRConversion(PULL)
+
|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;"|Retrieve Dispense612ToFHIRConversion request
+
|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;"|Patient (using a PHR)
+
|style="background-color: white;vertical-align:top;"|Client
|style="background-color: white;vertical-align:top;"|Request Dispense612ToFHIRConversion from the XIS
+
|style="background-color: white;vertical-align:top;"|Request Medication overview
 
|-
 
|-
|style="background-color: white;vertical-align:top;"|Retrieve Dispense612ToFHIRConversion response
+
|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;"|Healthcare professional (using a XIS)
+
|style="background-color: white;vertical-align:top;"|Server
|style="background-color: white;vertical-align:top;"|Serves Dispense612ToFHIRConversion to the PHR
+
|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==
 
==Invocations==
===PHR: request message===
+
===Request message===
This message uses the HTTP GET method parameterized query to obtain medication information from a XIS.  
+
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.  
  
====Trigger Events====
+
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.
When the patient (PHR) wants to obtain Medication process Dispense 6.12 information matching various parameters, it issues a retrieve Dispense612ToFHIRConversion request message.
 
 
 
====Message Semantics====
 
The PHR executes an HTTP GET against the XIS's MedicationDispense FHIR endpoint. This URL is configurable by the PHR by configuring the query search parameters and search control parameters to modify the behaviour of the XIS such as response format, or pagination. The search interaction is performed by an HTTP GET compliant with the [http://hl7.org/fhir/STU3/search.html FHIR search specification] as shown:
 
  
 
<pre>
 
<pre>
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005,http://snomed.info/sct|422037009&_include=MedicationDispense:medication&_include=MedicationDispense:patient&_include=MedicationDispense:performer{&[parameters]}
+
POST [base]/$medication-overview
</pre>
 
 
 
This search interaction Retrieves MedicationDispense resources that represent a MedicationDispense or AdministrationAgreement and includes the related Patient, Organization and Medication resources in the result.
 
 
 
====Query Search Parameters====
 
The PHR may supply, and the XIS 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;" | Example
 
|-
 
| UsePeriod
 
| Search on medication use in the past, present or future within the specified time period.
 
| <code>periodofuse</code> <ref name=custom-searchparameter/><sup>,</sup><ref name="Medications-periodofuse"/>
 
| Retrieves MedicationDispense resources that represent a HCIM MedicationDispense or AdministrationAgreement, were in effect within a 2 year period and includes related Medication, Patient and Organization resources in the result.
 
<pre>
 
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005,http://snomed.info/sct|422037009&periodofuse=le2011-12-31&periodofuse=ge2010-01-01&_include=MedicationRequest:medication&_include=MedicationDispense:patient&_include=MedicationDispense:performer
 
 
</pre>
 
</pre>
|-
 
| DispensePeriod
 
| Returns all medication dispenses within the specific period, based on the dispense request date.
 
| <code>requestdate</code> <ref name=custom-searchparameter/>
 
| Retrieves MedicationDispense resources that represent a HCIM MedicationDispense or AdministrationAgreement, that requested after 01-01-2010 and includes related Medication,  Patient and Organization resources in the result.
 
<pre>
 
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005,http://snomed.info/sct|422037009&requestdate=ge2010-01-01&_include=MedicationRequest:medication&_include=MedicationDispense:patient&_include=MedicationDispense:performer
 
</pre>
 
|}
 
 
=====Custom Search Parameters=====
 
The following custom search parameters are defined for this use case:
 
  
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/Medications-category|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}}
+
===Response message===
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/Medications-periodofuse|nictiz.fhir.nl.stu3.zib2017|pkgVersion=2.0.0}} <ref name="Medications-periodofuse">This SearchParameter searches on the FHIR DataType Period in the PeriodOfUse extension, which is added to profiles on MedicationRequest and MedicationDispense resources. Clients use date parameter searches as described by the FHIR specification. Servers are expected to take the MedicationUse-Duration extension into account when processing a client's search. This means that either a Period.start + Period.end or Period.start + Duration is used to determine the search results. To illustrate the expected behavior: if a Period.start and a Duration is known, but not the Period, the Duration should be added to the Period.start date to calculate the Period.end. The calculated Period.end date is then used to determine the search results.</ref>
+
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].  
* {{Simplifier|http://nictiz.nl/fhir/SearchParameter/MedicationDispense-requestdate|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
  
===XIS: response message===
+
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]].
The XIS returns a HTTP Status code appropriate to the processing of the request as well as a Bundle of type searchset.  
 
  
====Trigger Events====
+
'''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.
The XIS completed processing of the retrieve medication overview request message.
 
  
====Message Semantics====
+
==List of Profiles==
The returned data to the PHR SHALL conform to the profiles listed in the table below. The resources in the response message SHALL be a valid instance of these profiles. All resources SHALL include their respective profile canonical URL in the ''meta.profile'' element to show compliance.
+
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.r4.medicationprocess9|v1=2.0.0-beta2|p2=nictiz.fhir.nl.r4.zib2020|v2=0.1.0-beta1}}
  
These profiles are derived from the HCIM profiles. This use case has a very specific and stable underlying dataset. Therefore, the profiles contain many mandatory elements. Within the Medication Process dataset, there is a difference between the concept cardinalities '1..* Required' and '1..* Mandatory'.: The first means the element is required to be present if the system possesses the information and the latter means the element should always be present. Both are mapped to a mandatory cardinality in the FHIR profiles. If the XIS is not able to provide the required information for a mandatory element, it shall use a [http://hl7.org/fhir/STU3/extension-iso21090-nullflavor.html nullFlavor extension] to indicate that and why the information is not present. The PHR should be able to process nullFlavor extensions and values.
+
{| class="wikitable"  
 
 
{{MedMij:NoteBoxPackage|p1=nictiz.fhir.nl.stu3.medicationprocess|v1=9.1.0-beta1|p2=nictiz.fhir.nl.stu3.zib2017|v2=2.0.0}}
 
 
 
{| class="wikitable" width="1400px"
 
 
|-style="background-color: #1F497D; color: white; font-weight: bold; "
 
|-style="background-color: #1F497D; color: white; font-weight: bold; "
|HCIM name NL||HCIM name EN||FHIR Resource||FHIR Profile url
+
|zib name NL||zib name EN||FHIR Resource||FHIR Profile
 
|-style="vertical-align:top; background-color: #E3E3E3;  
 
|-style="vertical-align:top; background-color: #E3E3E3;  
 
|-
 
|-
| Patient
+
| - || - || Bundle || {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/Bundle-MedicationOverview|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2}}
| Patient
 
| Patient
 
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Patient|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
|-
 
| Zorgaanbieder
 
| HealthcareProvider
 
| Organization
 
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Organization|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
 
|-
 
|-
| Toedieningsafspraak
+
| - || - || List || {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/MedicationOverview|nictiz.fhir.nl.r4.medicationprocess9|pkgVersion=2.0.0-beta2}}
| AdministrationAgreement
 
| MedicationDispense
 
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-AdministrationAgreement|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
 
|-
 
|-
| Verstrekking
+
| Medicatieafspraak||MedicationAgreement||MedicationRequest|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
| Dispense
 
| MedicationDispense
 
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Dispense|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.1.0-beta1}}
 
 
|-
 
|-
| Product
+
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense|| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-AdministrationAgreement|nictiz.fhir.nl.r4.zib2020|pkgVersion=0.1.0-beta1}}
| Product
 
| Medication
 
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Product|nictiz.fhir.nl.stu3.medicationprocess|pkgVersion=9.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}}
 
|}
 
|}
  
====Expected Actions====
+
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.
The PHR shall process the results according to application-defined rules. The PHR should be robust as the response may contain medication information resources that match the query parameters.
 
 
 
=Terminology, NamingSystems, Mappings=
 
 
 
===Terminology===
 
Relevant ValueSets can be found through the ValueSet bindings in the listed StructureDefinitions. The FHIR packages include in the relevant ValueSets.
 
 
 
===NamingSystems===
 
Relevant NamingSystems can be found in the FHIR package.
 
 
 
===Mappings===
 
A FHIR ConceptMap resource is provided when a FHIR value set is used instead of a HCIM value set. In these cases, the StructureDefinitions provides information on the available ConceptMap. A ConceptMap maps the values between the two value sets. These ConceptMaps can be found in the nictiz.fhir.nl.stu3.medicationprocess and nictiz.fhir.nl.stu3.zib2017 package.
 
 
 
An explanation about mappings can be found at [[MedMij:V2020.01/FHIR_IG#Mapping_of_coded_concepts|Mapping of coded concepts]].
 
 
 
=Examples=
 
 
 
# Medicatieproces has a wiki page that contains [https://informatiestandaarden.nictiz.nl/wiki/mp:V9.1_Voorbeelden_doseringen examples in FHIR and CDA for dosage instructions].
 
# Every profile or resource on Simplifier has a reference tab. The reference tab shows all references from and to the selected resource. So the listed profiles in these use cases have a reference tab on Simplifier where examples are listed that declare conformance to the specific profile.
 
# Examples are accessible through the Simplifier project by going to the resources tab of the project. It is possible to filter on examples and underlying FHIR resource. This is clarified with the following URL, which lists all medication examples available in the NictizSTU3-MedicationProcess project: https://simplifier.net/nictizstu3-medicationprocess/~resources?category=Example&exampletype=MedicationDispense|MedicationStatement|MedicationRequest|Medication&fhirVersion=STU3&sortBy=DisplayName
 
  
 
=Release notes=
 
=Release notes=
Release notes can be found on the [[mp:V9.1.0_Ontwerp_medicatieproces_patient#Release_notes|functional design page]].
+
Release notes can be found on the [[mp:V9_2.0_Ontwerp_medicatieproces_patient#Release_notes|functional design page]].
  
 
=Footnotes=
 
=Footnotes=
 
<references/>
 
<references/>

Huidige versie van 30 sep 2021 om 14:04


1 Introduction

This is the FHIR implementation guide for the information standard Medicatieproces 9, version 2.0. This standard is described in this functional specification and implemented here using 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 general FHIR Implementation Guide apply. In particular, the reader should take note of the Use case overarching principles and the use of FHIR packages.

Use cases:

2 Actors involved

Persons Systems FHIR Capability Statements
Name Description Name Description Name Description
Patient or Healthcare professional The user of a personal healthcare environment (PHR) or a healthcare information system (XIS). Client PHR or XIS Verwijzing.png CapabilityStatement: Client Client requirements
Healthcare professional The user of a healthcare information system (XIS) Server XIS Verwijzing.png CapabilityStatement: Server Server requirements

3 Use case: retrieve medication data

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

3.2 Actors

Transaction group Transaction Actor Role
Retrieve Medication Data (PULL) Consulting medication data Client Request medication data
Making medication data available Server 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.

3.3 Invocations

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

GET [base]/[type]{?[parameters]}

3.3.1.1 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: identifier
  • MedicationRequest: patient
  • MedicationDispense: patient
  • MedicationStatement: patient
  • MedicationAdministration: patient

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

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

3.3.1.2 Search Parameters

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

MP9 search parameters Description FHIR search parameter FHIR resource Example
Identification Search on identifier. identifier MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration Retrieves a MedicationRequest resource with the identifier 999922448.
GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448
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. pharmaceutical-treatment-identifier [1] MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration Retrieves all MedicationRequest resources that are part of the pharmaceutical treatment with identifier value of 1247848.
GET [base]/MedicationRequest?pharmaceuticaltreatment=http://example.nl/fhir/NamingSystem/medicationtreatment|1247848 
Type Search on type of medication building block. category [1],[2] MedicationRequest Retrieves all MedicationRequest resources that represent a zib MedicationAgreement.
GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005

Retrieves all MedicationRequest resources that represent a zib DispenseRequest.

GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108
MedicationDispense Retrieves all MedicationDispense resources that represent a zib Dispense.
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005

Retrieves all MedicationRequest resources that represent the zib AdministrationAgreement.

GET [base]/MedicationRequest?category=http://snomed.info/sct|422037009
MedicationStatement Retrieves all MedicationStatement resources that represent a zib MedicationUse2.
GET [base]/MedicationStatement?category=http://snomed.info/sct|422979000
MedicationAdministration Retrieves all MedicationAdministration resoures that represent a zib MedicationAdministration2.
GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&_include=MedicationStatement:medication
ProductCode Search on medication code. code MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration Retrieves all MedicationRequest resources that represent a zib MedicationAgreement and have Carbasalaatcalcium Sandoz 600 30 as medication.
GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554
UsePeriod Search on medication use in the past, present or future within the specified time period. period-of-use[1] MedicationDispense, MedicationRequest Retrieves all MedicationRequest resources that represent a zib MedicationAgreement and were in effect from 01-01-2010.
GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&period-of-use=ge2010-01-01
DispensePeriod Returns all medication dispenses within the specified time period. whenhandedover MedicationDispense Retrieves all MedicationDispense resources that represent a zib Dispense and were handed over within a 2 year period.
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005&whenhandedover=ge2010-01-01&whenhandedover=le2011-12-31
AdministrationPeriod Returns all medication administrations within the specified time period. effective-time MedicationAdministration Retrieves all MedicationAdministration resources that represent a zib MedicationAdministration2 and were administration happened within a 2 year period.
GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&effective-time=ge2010-01-01&effective-time=le2011-12-31
- 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. _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.
GET [base]/MedicationRequest?medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554&_include=MedicationRequest:medication

3.3.1.3 Custom Search Parameters

The following custom search parameters are defined for this use case:

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

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

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

Note that the medication resources are grouped per 'pharmaceutical treatment' conform to the 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 PharmaceuticalTreatmentIdentifier extension is to be used for this grouping purpose.

3.4 List of Profiles

zib/MP building block name NL zib/MP building block name EN FHIR Resource FHIR Profile
Medicatieafspraak MedicationAgreement MedicationRequest http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAgreement
WisselendDoseerschema VariableDosingRegimen MedicationRequest http://nictiz.nl/fhir/StructureDefinition/nl-core-VariableDosingRegimen
Verstrekkingsverzoek DispenseRequest MedicationRequest http://nictiz.nl/fhir/StructureDefinition/nl-core-DispenseRequest
Toedieningsafspraak AdministrationAgreement MedicationDispense http://nictiz.nl/fhir/StructureDefinition/nl-core-AdministrationAgreement
Verstrekking Dispense MedicationDispense http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationDispense
Medicatiegebruik2 MedicationUse2 MedicationStatement http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationUse2
MedicatieToediening2 MedicationAdministration2 MedicationAdministration http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAdministration2

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.

4 Use case: retrieve medication overview

4.1 Introduction

The retrieve medication overview transaction is used by the client to retrieve a medication overview from the server.

4.2 Actors

Transaction group Transaction Actor Role
Retrieve Medication overview (PULL) Consulting medication overview Client Request Medication overview
Making medication overview available Server 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.

4.3 Invocations

4.3.1 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 medication-overview operation with HTTP POST against the server base endpoint as shown below.

POST [base]/$medication-overview

4.3.2 Response message

The server returns a HTTP Status code appropriate to the processing of the operation. The successful outcome of the $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 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 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.

Note that the medication resources blocks are grouped per 'pharmaceutical treatment' conform to the 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 PharmaceuticalTreatmentIdentifier extension is to be used for this grouping purpose.

4.4 List of Profiles

zib name NL zib name EN FHIR Resource FHIR Profile
- - Bundle http://nictiz.nl/fhir/StructureDefinition/Bundle-MedicationOverview
- - List http://nictiz.nl/fhir/StructureDefinition/MedicationOverview
Medicatieafspraak MedicationAgreement MedicationRequest http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationAgreement
Toedieningsafspraak AdministrationAgreement MedicationDispense http://nictiz.nl/fhir/StructureDefinition/nl-core-AdministrationAgreement
Medicatiegebruik MedicationUse MedicationStatement http://nictiz.nl/fhir/StructureDefinition/nl-core-MedicationUse2

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.

5 Release notes

Release notes can be found on the functional design page.

6 Footnotes

  1. 1,0 1,1 1,2 The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification.
  2. 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.