MedMij FHIR Implementation Guide Medication Process
1 Introduction
This page describes patient's use cases, in a personal health record (PHR) context, in relation to the information standard 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 functional design wiki page.
The Medication Process information building blocks are adopted by 'Registratie aan de Bron' and converted to Health and Care Information models (HCIM), also called 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:
Note: This implementation guide builds on the general guidelines described in the use case overarching principles.
2 Actors involved
| Persons | Systems | FHIR Capability Statements | |||
|---|---|---|---|---|---|
| Name | Description | Name | Description | Name | Description |
| Patient | The user of a personal healthcare environment. | PHR | Personal health record |  CapabilityStatement: Client
|
Medication process client requirements |
| Healthcare professional | The user of a XIS | XIS | Healthcare information system | CapabilityStatement: Server
|
Medication process server requirements |
3 Use case: retrieve medication overview
This FHIR implementation guide assumes that the PHR system is able to make a connection to the right XIS that contains the patient's information. It does not provide information on finding the right XIS nor does it provide information about security. Moreover, each transaction is performed in the context of a specific authenticated patient, for whose context (token) has been established using the authentication mechanisms described in the 'Afsprakenstelsel'. Each XIS Gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification.
3.1 Introduction
The retrieve medication overview transaction is used by the PHR to retrieve a medication overview from the XIS.
3.2 Actors
| Transaction group | Transaction | Actor | Role |
|---|---|---|---|
| Retrieve Medication Overview(PULL) | Retrieve medication overview request | Patient (using a PHR) | Request medication overview from the XIS |
| Retrieve medication overview response | Healthcare professional (using a XIS) | Serves medication overview to the PHR |
3.3 Invocations
3.3.1 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.
3.3.1.1 Trigger Events
When the patient (PHR) wants to obtain the current medication overview, it issues a retrieve medication overview request message.
3.3.1.2 Message Semantics
The PHR executes a medication-overview operation with HTTP POST against the XIS's base endpoint as shown below.
POST [base]/$medication-overview
3.3.1.2.1 Expected Actions
The XIS shall process the operation to find or generate and return the current medication overview.
3.3.2 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.
3.3.2.1 Trigger Events
The XIS completed processing of the retrieve medication overview request message.
3.3.2.2 Message Semantics
The outcome of the $medication-overview operation 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 Medication Process specification. The functional dataset of the medication overview can be found on decor.nictiz.nl.
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: http://nictiz.nl/fhir/StructureDefinition/Bundle-MedicationOverview
- List profile: 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 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 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 zib-Medication-MedicationTreatment extension is added to all medication profiles and can be used for this grouping purpose.
|
|
MedMij uses the FHIR Packaging mechanism. This conveniently bundles all examples, profiles and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages: Note: any other version with the same major.minor version is compatible. See Semantic Versioning for more information. |
| HCIM name NL | HCIM name EN | FHIR Resource | FHIR Profile |
| Patient | Patient | Patient | http://fhir.nl/fhir/StructureDefinition/nl-core-patient |
| Zorgverlener | HealthProfessional | Practitioner | http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner |
| Zorgaanbieder | HealthcareProvider | Organization | http://fhir.nl/fhir/StructureDefinition/nl-core-organization |
| Medicatiegebruik | MedicationUse | MedicationStatement | http://nictiz.nl/fhir/StructureDefinition/zib-MedicationUse |
| Toedieningsafspraak | AdministrationAgreement | MedicationDispense | http://nictiz.nl/fhir/StructureDefinition/zib-AdministrationAgreement |
| Medicatieafspraak | MedicationAgreement | MedicationRequest | http://nictiz.nl/fhir/StructureDefinition/zib-MedicationAgreement |
| Product | Product | Medication | http://nictiz.nl/fhir/StructureDefinition/zib-Product |
| GebruiksInstructie | InstructionsForUse | Dosage (datatype) | http://nictiz.nl/fhir/StructureDefinition/zib-InstructionsForUse |
3.3.2.3 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.
4 Use case: retrieve medication information
This FHIR implementation guide assumes that the PHR system is able to make a connection to the right XIS that contains the patient's information. It does not provide information on finding the right XIS nor does it provide information about security. Moreover, each transaction is performed in the context of a specific authenticated patient, for whose context (token) has been established using the authentication mechanisms described in the 'Afsprakenstelsel'. Each XIS Gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification.
4.1 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 desired information by searching on specific medication building blocks.
4.2 Actors
| Transaction group | Transaction | Actor | Role |
|---|---|---|---|
| Retrieve Medication Information(PULL) | Retrieve medication information request | Patient (using a PHR) | Request medication information from the XIS |
| Retrieve medication information response | Healthcare professional (using a XIS) | Serves medication information to the PHR |
4.3 Invocations
4.3.1 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.
4.3.1.1 Trigger Events
When the patient (PHR) wants to obtain medication information matching various parameters, it issues a retrieve medication information request message.
4.3.1.2 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 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.
GET [base]/[type]{?[parameters]}
4.3.1.3 Query Search Parameters
The PHR may supply, and the XIS 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 | Retrieves a MedicationRequest resource with the identifier 999922448.
GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448 |
| Type | Search on type of medication building block (HCIM). | category [1],[2]
|
MedicationRequest | Retrieves all MedicationRequest resources that represent a HCIM MedicationAgreement.
GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005 Retrieves all MedicationRequest resources that represent a HCIM DispenseRequest. GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108 |
| MedicationDispense | Retrieves all MedicationDispense resources that represent a HCIM Dispense.
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005 Retrieves all MedicationRequest resources that represent a HCIM AdministrationAgreement. GET [base]/MedicationRequest?category=http://snomed.info/sct|422037009 | |||
| MedicationStatement | Retrieves all MedicationStatement resources that represent a HCIM MedicationUse.
GET [base]/MedicationStatement?category=urn:oid:2.16.840.1.113883.2.4.3.11.60.20.77.5.3|6 | |||
| ProductCode | Search on medication code. | code
|
MedicationRequest, MedicationDispense, MedicationStatement, Medication | Retrieves all MedicationRequest resources that represent a HCIM 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. | periodofuse [2],[3]
|
MedicationDispense, MedicationRequest | Retrieves all MedicationRequest resources that represent a HCIM MedicationAgreement and were in effect after 01-01-2010.
GET [base]/MedicationRequest?category=http://snomed.info/sct|16076005&periodofuse=ge2010-01-01 |
| DispensePeriod | Returns all medication dispenses within the specific period. | whenhandedover
|
MedicationDispense | Retrieves all MedicationDispense resources that represent a HCIM 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 |
| MedicationTreatment | Search on the medication treatment identifier | medicationtreatment [2]
|
MedicationRequest, MedicationDispense, MedicationStatement | Retrieves all MedicationRequest resources that are part of the medication treatment 1247848.
GET [base]/MedicationRequest?medicationtreatment=http://example.nl/fhir/NamingSystem/medicationtreatment|1247848 |
| - | 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. | _include
|
MedicationRequest, MedicationDispense, MedicationStatement | 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 |
|
|
Known issue: the MedicationTreatment search parameter was previously also shown as a system-wide search, e.g. a search on the server's base. This is not correct and potentially dangerous. Therefore this should not be implemented. It is expected that requests are made on a Resource type instead of the server base. More information can be found here: https://bits.nictiz.nl/browse/MM-560 |
4.3.1.3.1 Custom Search Parameters
The following custom search parameters are defined for this use case:
- http://nictiz.nl/fhir/SearchParameter/Medications-category
- http://nictiz.nl/fhir/SearchParameter/Medications-periodofuse [3]
- http://nictiz.nl/fhir/SearchParameter/Medications-medicationtreatment
4.3.1.3.2 Expected Actions
The XIS shall process the query to discover the medication information that match the search parameters given.
4.3.2 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.
4.3.2.1 Trigger Events
The XIS completed processing of the Retrieve medication information request message.
4.3.2.2 Message Semantics
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.
Note that the medication building blocks are grouped per 'medication treatment' conform the 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 zib-Medication-MedicationTreatment extension is added to all medication profiles and can be used for this grouping purpose.
|
|
MedMij uses the FHIR Packaging mechanism. This conveniently bundles all examples, profiles and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages: Note: any other version with the same major.minor version is compatible. See Semantic Versioning for more information. |
4.3.2.3 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.
5 Use case: retrieve Dispense612ToFHIRConversion from the LSP
This FHIR implementation guide assumes that the PHR system is able to make a connection to the right XIS that contains the patient's information. It does not provide information on finding the right XIS nor does it provide information about security. Moreover, each transaction is performed in the context of a specific authenticated patient, for whose context (token) has been established using the authentication mechanisms described in the 'Afsprakenstelsel'. Each XIS Gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification.
5.1 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.
5.2 Actors
| Transaction group | Transaction | Actor | Role |
|---|---|---|---|
| Retrieve Dispense612ToFHIRConversion(PULL) | Retrieve Dispense612ToFHIRConversion request | Patient (using a PHR) | Request Dispense612ToFHIRConversion from the XIS |
| Retrieve Dispense612ToFHIRConversion response | Healthcare professional (using a XIS) | Serves Dispense612ToFHIRConversion to the PHR |
5.3 Invocations
5.3.1 PHR: request message
This message uses the HTTP GET method parameterized query to obtain medication information from a XIS.
5.3.1.1 Trigger Events
When the patient (PHR) wants to obtain Medication process Dispense 6.12 information matching various parameters, it issues a retrieve Dispense612ToFHIRConversion request message.
5.3.1.2 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 FHIR search specification as shown:
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005,http://snomed.info/sct|422037009&_include=MedicationDispense:medication&_include=MedicationDispense:patient&_include=MedicationDispense:performer{&[parameters]}
This search interaction Retrieves MedicationDispense resources that represent a MedicationDispense or AdministrationAgreement and includes the related Patient, Organization and Medication resources in the result.
5.3.1.3 Query Search Parameters
The PHR may supply, and the XIS SHALL be capable of processing, all query parameters listed in the table below.
| MP9 search parameters | Description | FHIR search parameter | Example |
|---|---|---|---|
| UsePeriod | Search on medication use in the past, present or future within the specified time period. | periodofuse [2],[3]
|
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.
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 |
| DispensePeriod | Returns all medication dispenses within the specific period, based on the dispense request date. | requestdate [2]
|
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.
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 |
5.3.1.3.1 Custom Search Parameters
The following custom search parameters are defined for this use case:
- http://nictiz.nl/fhir/SearchParameter/Medications-category
- http://nictiz.nl/fhir/SearchParameter/Medications-periodofuse [3]
- http://nictiz.nl/fhir/SearchParameter/MedicationDispense-requestdate
5.3.2 XIS: response message
The XIS returns a HTTP Status code appropriate to the processing of the request as well as a Bundle of type searchset.
5.3.2.1 Trigger Events
The XIS completed processing of the retrieve medication overview request message.
5.3.2.2 Message Semantics
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.
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 nullFlavor extension to indicate that and why the information is not present. The PHR should be able to process nullFlavor extensions and values.
|
|
MedMij uses the FHIR Packaging mechanism. This conveniently bundles all examples, profiles and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages: Note: any other version with the same major.minor version is compatible. See Semantic Versioning for more information. |
| HCIM name NL | HCIM name EN | FHIR Resource | FHIR Profile url |
| Patient | Patient | Patient | http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Patient&scope=nictiz.fhir.nl.stu3.zib2017@1.3.10 http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Patient |
| Zorgaanbieder | HealthcareProvider | Organization | http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Organization |
| Toedieningsafspraak | AdministrationAgreement | MedicationDispense | http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-AdministrationAgreement |
| Verstrekking | Dispense | MedicationDispense | http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Dispense |
| Product | Product | Medication | http://nictiz.nl/fhir/StructureDefinition/mp612-DispenseToFHIRConversion-Product |
5.3.2.3 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.
6 Terminology, NamingSystems, Mappings
6.1 Terminology
Relevant ValueSets can be found through the ValueSet bindings in the listed StructureDefinitions. All ValueSets can be found here here and can be downloaded as a .zip in XML or JSON format.
6.2 NamingSystems
Relevant NamingSystems can be found here.
6.3 Mappings
A FHIR ConceptMap resource is provided when a FHIR value set is used instead of a HCIM value set. A ConceptMap maps the values between the two value sets. These ConceptMaps can be found here.
An explanation about mappings can be found at Mapping of coded concepts.
7 Examples
- Medicatieproces has a wiki page that contains 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-zib2017 project: https://simplifier.net/NictizSTU3-Zib2017/~resources?category=Example&exampletype=MedicationDispense%7CMedicationStatement%7CMedicationRequest%7CMedication&fhirVersion=STU3&sortBy=DisplayName
8 Release notes
Release notes can be found on the functional design page.
9 Footnotes
- ↑ 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.
- ↑ 2,0 2,1 2,2 2,3 2,4 The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification.
- ↑ 3,0 3,1 3,2 3,3 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.