Brontekst bekijken van MedMij:V2018.04 FHIR MedicationProcess

{{DISPLAYTITLE:MedMij FHIR use case Medication Process}}

[[Bestand:MedMij2.png |link=https://www.medmij.nl/|rechts|Naar medmij.nl]]
[[Bestand:Medication_Icoon.png|link=|85px|links|Use case Medication|Medication process]] 
<imagemap>Bestand:Leeswijzer-technisch-banner 03 white.png|center|400px|alt=Afspraken-Functioneel-Technisch   
circle 241 216 211 [https://www.medmij.nl/afsprakenstelsel Afsprakenstelsel]                
circle 1013 224 212 [[MedMij:V2018.04_OntwerpMedicatie|Functional]]                
circle 1787 230 212 [[MedMij:V2018.04_FHIR_IG|Tecnical]]                
desc none                    
</imagemap>

__TOC__

=Introduction=
[[Bestand:Functioneel-02.png|link=MedMij:V2018.04_Ontwerpen |100px|rechts|Functional design|Go to functional design]]

This page describes patient's use cases, in a personal health record (PHR) context, in relation to the information standard [https://informatiestandaarden.nictiz.nl/wiki/Landingspagina_Medicatieproces Medication Process] (MP). These use cases are based on version 9.x of this standard. Functional specification of these use cases are described in the [[MedMij:V2018.04_Ontwerpen| functional design wiki page]]. The technical specification is described here. HL7 FHIR STU3 is used for this purpose.

The Medication Process information building blocks are adopted by 'Registratie aan de Bron' and converted to Health and Care Information models, also called ZIB's. In order to exchange medication information between systems, FHIR representations of these ZIB's are made and used in the transactions described on this page.

Use cases:
* [[MedMij:V2018.04_FHIR_MedicationProcess#Use_case:_retrieve_medication_overview|Retrieve a medication overview]]
* [[MedMij:V2018.04_FHIR_MedicationProcess#Use_case:_retrieve_medication_information|Retrieve medication information]]

=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
| The user of a personal healthcare enviorment.
| PHR
| Personal health record
|[[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/medication-clientcapabilities|CapabilityStatement: Client|scope=nictiz.fhir.nl.stu3.zib2015@1.0.0}}
| Medication process client requirements 
|-
| Healthcare professional
| The user of a XIS
| XIS
| Healthcare information system
|[[Bestand: Verwijzing.png| 20px]] {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/medication-servercapabilities|CapabilityStatement: Server|scope=nictiz.fhir.nl.stu3.zib2015@1.0.0}}
| Medication process server requirements 
|}

=Use case: retrieve medication overview=
{{FHIR-IG-Afsprakenstelsel-Note}}

==Introduction==
The retrieve medication overview transaction is used by the PHR to retrieve a medication overview from the XIS.

==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"|Retrieve Medication Overview(PULL)
|style="background-color: white;vertical-align:top;"|Retrieve medication overview request
|style="background-color: white;vertical-align:top;"|Patient (using a PHR)
|style="background-color: white;vertical-align:top;"|Request medication overview from the XIS
|-
|style="background-color: white;vertical-align:top;"|Retrieve medication overview response
|style="background-color: white;vertical-align:top;"|Healthcare professional (using a XIS)
|style="background-color: white;vertical-align:top;"|Serves medication overview to the PHR
|}

==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====
When the patient(PHR) wants to obtain the current medication overview, it issues a retrieve medication overview request message.

====Message Semantics====
The PHR executes a medication-overview operation with HTTP POST against the XIS's base endpoint as shown below.

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

=====Expected Actions=====
The XIS shall process the operation to find or generate and return the current medication overview.

===XIS: response message===
The XIS returns a HTTP Status code appropriate to the processing of the operation as well as a Bundle of type 'collection', 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====
Based on the medication-overview operation processing results, the XIS will either return an error or success. When the XIS needs to report an error, it shall use HTTP error response codes and shall include a FHIR OperationOutcome resource with more details on the failure. If the request message is processed successfully, whether or not a Medication Overview is found or generated, the HTTP status code shall be 200. 

The body of the response message shall be a Bundle resource of type "collection". The following section will elaborate on the content included.

If the XIS is sending warnings, the Bundle resource shall also contain a FHIR OperationOutcome resource that contains those warnings. The FHIR specification describes the relevant sections:
*[http://hl7.org/fhir/STU3/http.html RESTful API framework] 
*[http://hl7.org/fhir/operations.html Operations]
*[http://hl7.org/fhir/STU3/bundle.html Bundle resource]
*[http://hl7.org/fhir/operationoutcome.html OperationOutcome resource]

=====Message content=====
The outcome of the {{Simplifier|http://nictiz.nl/fhir/OperationDefinition/Medication-Overview|medication-overview operation|scope=nictiz.fhir.nl.stu3.zib2015@1.0.0}} is the body of the medication overview request 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.04_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].


<html>
<iframe width="750" frameborder="1" height="400" src=https://www.simplifier.net/embed/render?id=NictizSTU3-Zib2017/Medication-Overview frameborder="0" align="middle"></iframe>
</html>


The content in the response message SHALL be a valid instance of the following profiles. Clicking on the link will open the formal definition on Simplifier.net.

* '''Bundle profile:''' [https://simplifier.net/NictizSTU3-Zib2017/MedicationOverviewresponsestructure http://nictiz.nl/fhir/StructureDefinition/Bundle-MedicationOverview]
* '''List profile:''' [https://simplifier.net/NictizSTU3-Zib2017/MedicationOverview http://nictiz.nl/fhir/StructureDefinition/MedicationOverview]

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 returned Bundle has at least one List and one Patient resource. 

All returned resources to the PHR, including the Bundle and List, SHALL include their related profile canonical URL in the ''meta.profile'' element in order to show compliance. The resources in the response message SHALL be a valid instance of these profiles. In the table below, the ZIB's 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.04_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|zib-Medication-MedicationTreatment extenstion|scope=nictiz.fhir.nl.stu3.zib2015@1.0.0}}  is added to all medication profiles and can be used for this grouping purpose.

{| 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; 
|-
| Patient
| #ZIB Patient|Patient
| Patient
| [https://simplifier.net/NictizSTU3-Zib2017/nl-core-patient  http://fhir.nl/fhir/StructureDefinition/nl-core-patient]
|-
| Zorgverlener
| HealthProfessional
| Practitioner
| [https://simplifier.net/NictizSTU3-Zib2017/nl-core-practitioner http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner]
|-
| Zorgaanbieder
| HealthcareProvider
| Organization
| [https://simplifier.net/NictizSTU3-Zib2017/nl-core-organization http://fhir.nl/fhir/StructureDefinition/nl-core-organization]
|-
| Medicatiegebruik||MedicationUsage||MedicationStatement|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-MedicationUse http://nictiz.nl/fhir/StructureDefinition/zib-MedicationUse]
|-
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-AdministrationAgreement http://nictiz.nl/fhir/StructureDefinition/zib-AdministrationAgreement]
|-
| Medicatieafspraak||MedicationAgreement||MedicationRequest|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-MedicationAgreement http://nictiz.nl/fhir/StructureDefinition/zib-MedicationAgreement]
|-
| Product||Product||Medication|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-Product http://nictiz.nl/fhir/StructureDefinition/zib-Product]
|-
| GebruiksInstructie||InstructionsForUse||Dosage (datatype)|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-InstructionsForUse http://nictiz.nl/fhir/StructureDefinition/zib-InstructionsForUse]
|-
|}

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

==Interactions, operations, search parameters== 
===Interactions===
No interactions are needed for the retrieve medication overview transaction.

===Operations===
The retrieve medication overview medication operation is used for this transaction. The formal definition can be found here:
* [https://simplifier.net/NictizSTU3-Zib2017/Medication-Overview Medication Overview]

===Search parameters===
The following search parameter type needs to be supported for this transaction.

Search parameter types:
* [http://hl7.org/fhir/STU3/search.html#token token]

=Use case: retrieve medication information=
{{FHIR-IG-Afsprakenstelsel-Note}}

==Introduction==
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 wanted 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"|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
* MedicationAdministration
* 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:

<pre>
GET [base]/[type]{?[parameters]{&_format=[mime-type]}}
</pre>

This URL is configurable by the PHR by configuring the query search parameters and search control parameters to modify the behavior of the XIS such as response format, or pagination. An example of a search for MedicationRequest resources:

<pre>
GET https://vonk.test-nictiz.nl/MedicationRequest?date=gt2010-10-01
</pre>

This search interaction will finds any MedicationRequest resources changed since 1-Oct 2010. 

=====Including other resources in searchresults=====
The PHR may request that the XIS return resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources. This is useful when the PHR is searching on a clinical resource, but for every such resource returned, the client will also need the subject (Patient resource) or prescriber (Practitioner resource) or medication that the clinical resource refers to. The client can use the _include parameter to indicate that the subject resources be included in the results. Example search:

<pre>
GET [base]/MedicationRequest?&category=http://snomed.info/sct|16076005&_include:MedicationRequest:medication
</pre>

This search interaction will find all MedicationRequest resources of the category MedicationAgreement and if present includes the referenced Medication resource.

====Query Search Parameters====
The PHR may supply, and the XIS SHALL be capable of processing, all query parameters listed in the table below. The XIS may choose to support additional query parameters beyond the subset listed below. Any additional query parameters supported shall be supported according to the core FHIR specification. Such additional parameters are considered out of scope for this transaction.

{| 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
|-
| Identification
| Search on identifier.
| identifier
| MedicationRequest, MedicationDispense, MedicationAdministration, MedicationStatement
|-
| Type
| Search on type of medication building block (HCIM). 
| category '''*''' / '''**'''
| MedicationRequest, MedicationAdministration, MedicationDispense, MedicationStatement
|-
| ProductCode
| Search on medication code.
| code
| MedicationRequest, MedicationAdministration, MedicationDispense, MedicationStatement, Medication
|-
| UsePeriod
| Search on medication use in the past, present or future within the specified time period.
| periodofuse '''**'''
| MedicationDispense, MedicationRequest
|-
| DispensePeriod 
| Returns all medication dispenses within the specific period.
| whenhandedover
| MedicationDispense
|}
'''*''' 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. FHIR resources MedicationAdministration and MedicationDispense do not contain a 'category' search parameter in the FHIR specification. Custom search parameters are provided.  

'''**''' The search parameter consists of a custom created FHIR search parameter not represented in the FHIR specification. 

=====Custom Search Parameters=====

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

* https://simplifier.net/NictizSTU3-Zib2017/Medications-category
* https://simplifier.net/NictizSTU3-Zib2017/Medications-periodofuse

=====Search on fixed category code=====
To distinguish the ZIB medication building blocks between general medication resources, a fixed category coding has been added to the ZIB medication profiles. This fixed category code is solely used for indexing and retrieval of the ZIB building blocks. These category codings be found in the in the profiles at the .category element. The profiles are listed at the response message section below.

====Example Searches====

'''Identifier'''
<pre>1. https://vonk.test-nictiz.nl/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448 </pre>
# Retrieves a MedicationRequest resource with the identifier 999922448.

'''Type'''
<pre>1. https://vonk.test-nictiz.nl/MedicationRequest 
2. https://vonk.test-nictiz.nl/MedicationRequest?category=http://snomed.info/sct|16076005</pre>
# Retrieves all MedicationRequest resources.
# Retrieves all MedicationRequest resources that represent a ZIB MedicationAgreement.

'''ProductCode'''
<pre>1. https://vonk.test-nictiz.nl/MedicationRequest?medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554
2. https://vonk.test-nictiz.nl/MedicationRequest?include=Medication:medication&code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554
3. https://vonk.test-nictiz.nl/MedicationRequest?category=http://snomed.info/sct|16076005&medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554</pre>
# Retrieves all MedicationRequest resources that have Carbasalaatcalcium Sandoz 600 30 as medication.
# 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 represent a ZIB MedicationAgreement and have Carbasalaatcalcium Sandoz 600 30 as medication

'''UsePeriod'''
<pre>1. https://vonk.test-nictiz.nl/MedicationRequest?periodofuse=ge2010-01-01
2. https://vonk.test-nictiz.nl/MedicationDispense?periodofuse=ge2010-01-01&periodofuse=le2011-12-31
3. https://vonk.test-nictiz.nl/MedicationRequest?category=http://snomed.info/sct|16076005&periodofuse=ge2010-01-01</pre>
# Retrieves all MedicationRequest resources that were in effect after 01-01-2010.
# Retrieves all MedicationDispense resources that were in effect within a 2 year period.
# Retrieves all MedicationRequest resources that represent a ZIB MedicationAgreement and were in effect after 01-01-2010.

'''DispensePeriod'''
<pre>1. https://vonk.test-nictiz.nl/MedicationDispense?whenhandedover=ge2010-01-01
2. https://vonk.test-nictiz.nl/MedicationDispense?whenhandedover=ge2010-01-01&whenhandedover=le2011-12-31
3. https://vonk.test-nictiz.nl/MedicationDispense?whenhandedover=ge2010-01-01&category=http://snomed.info/sct|373784005
</pre>
# Retrieves all MedicationDispense resources that were handed over after 01-01-2010.
# Retrieves all MedicationDispense resources that were handed over within a 2 year period.
# Retrieves all MedicationDispense resources that represent a ZIB Dispense and were handed over after 01-01-2010.

=====Expected Actions=====
The XIS shall process the query to discover the medication information that match the search parameters given.

===XIS: response message===
The XIS returns a HTTP Status code appropriate to the processing as well as a FHIR Bundle including the matching medication information.

====Trigger Events====
The XIS completed processing of the Retrieve medication information request message. 

====Message Semantics====
Based on the query results, the XIS will either return an error or success. When the XIS needs to report an error, it SHALL use HTTP error response codes and SHOULD include a FHIR OperationOutcome resource with more details on the failure. If the request message is processed successfully, whether or not any medication resources are found, the HTTP status code SHALL be 200. 

The response message SHALL be a Bundle resource of type "searchset" containing zero or more FHIR resources as entries. If the XIS is sending warnings, the Bundle resource SHALL also contain a FHIR OperationOutcome resource that contains those warnings. The FHIR specification describes the relevant sections:
*[http://hl7.org/fhir/STU3/http.html RESTful API framework] 
*[http://hl7.org/fhir/STU3/search.html#errors Search errors]
*[http://hl7.org/fhir/STU3/bundle.html Bundle resource]
*[http://hl7.org/fhir/operationoutcome.html OperationOutcome resource]

=====Message resource content=====
The returned data to the PHR should conform to the medication ZIBs profiles. In the table below the medication ZIB's and their respective FHIR profiles are listed. 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.

'''Note''' that the medication building blocks are grouped per 'medication treatment' conform the [https://informatiestandaarden.nictiz.nl/wiki/mp:V9.04_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 [https://simplifier.net/NictizSTU3-Zib2017/ZIB-MedicationTreatment zib-Medication-MedicationTreatment extension] is added to all medication profiles and can be used for this grouping purpose.

{| class="wikitable" width="1400px"
|-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; 
|-
| Patient
| #ZIB Patient|Patient
| Patient
| [https://simplifier.net/NictizSTU3-Zib2017/nl-core-patient  http://fhir.nl/fhir/StructureDefinition/nl-core-patient]
|-
| Zorgverlener
| HealthProfessional
| Practitioner
| [https://simplifier.net/NictizSTU3-Zib2017/nl-core-practitioner http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner]
|-
| Zorgaanbieder
| HealthcareProvider
| Organization
| [https://simplifier.net/NictizSTU3-Zib2017/nl-core-organization http://fhir.nl/fhir/StructureDefinition/nl-core-organization]
|-
| Medicatiegebruik||MedicationUsage||MedicationStatement|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-MedicationUse http://nictiz.nl/fhir/StructureDefinition/zib-MedicationUse]
|-
| Medicatietoediening||MedicationAdministration||MedicationAdministration|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-MedicationAdministration http://nictiz.nl/fhir/StructureDefinition/zib-MedicationAdministration] 
|-
| Toedieningsafspraak||AdministrationAgreement||MedicationDispense|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-AdministrationAgreement http://nictiz.nl/fhir/StructureDefinition/zib-AdministrationAgreement]
|-
| Medicatieafspraak||MedicationAgreement||MedicationRequest|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-MedicationAgreement http://nictiz.nl/fhir/StructureDefinition/zib-MedicationAgreement]
|-
| Verstrekking||Dispense||MedicationDispense|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-Dispense http://nictiz.nl/fhir/StructureDefinition/zib-Dispense]
|-
| Verstrekkingsverzoek||MedicationDispenseRequest||MedicationRequest|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-DispenseRequest http://nictiz.nl/fhir/StructureDefinition/zib-DispenseRequest]
|-
| Product||Product||Medication|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-Product http://nictiz.nl/fhir/StructureDefinition/zib-Product]
|-
| GebruiksInstructie||InstructionsForUse||Dosage (datatype)|| [https://simplifier.net/NictizSTU3-Zib2017/ZIB-InstructionsForUse http://nictiz.nl/fhir/StructureDefinition/zib-InstructionsForUse]
|-
|}

====Expected Actions====
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.

==Interactions, operations, search parameters==
===Interactions===
The following logical interactions are needed for the retrieve medication information transaction:
* [http://hl7.org/fhir/STU3/http.html#search Search]

===Operations===
No operations are defined or needed for this transaction.

===Search parameters===
The following search parameter types and search result parameters need to be supported for this transaction.

Search parameter types:
* [http://hl7.org/fhir/STU3/search.html#token token]
* [http://hl7.org/fhir/STU3/search.html#date date]

Search result parameters:
* [http://hl7.org/fhir/STU3/search.html#include _include]

[[categorie:MedMij FHIR Use Cases]]