FHIR Implementation Guide Medication Process
|
|
This pages describes Medication Process version and is currently not in use. Active versions can be found through the references on the landing page of Medication Process. |
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 |  CapabilityStatement: Client
|
Client requirements |
| Healthcare professional | The user of a healthcare information system (XIS) | Server | XIS | CapabilityStatement: Server
|
Server requirements |
3 Use case: retrieve medication data
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 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 Query 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 | 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 from 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 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 | 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.2 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/PharmaceuticalTreatmentIdentifier
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 'medication 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
|
|
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 |
| 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-MedicationUse |
| Verstrekking | Dispense | MedicationDispense | http://nictiz.nl/fhir/StructureDefinition/nl-core-Dispense |
| Verstrekkingsverzoek | DispenseRequest | MedicationRequest | http://nictiz.nl/fhir/StructureDefinition/nl-core-DispenseRequest |
Note that also besides the profiles listed directly in the table, but also to profiles referred from/used by these listed profiles are applicable. These consist of profiles for zibs Patient, HealthProfessional, HealthcareProvider, BodyWeight and BodyHeight.
4 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.
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 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 that are referenced in the medication-overview operation. Clicking on the link will open the formal definition on Simplifier.net.
- Medication-Overview OperationDefinition: http://nictiz.nl/fhir/OperationDefinition/MedicationOverview
- Bundle profile: http://nictiz.nl/fhir/StructureDefinition/MedicationOverview-structure
- 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 resources blocks are grouped per 'medication 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
|
|
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 |
| 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-MedicationUse |
Note that also besides the profiles listed directly in the table, but also to profiles referred from/used by these listed profiles are applicable. These consist of profiles for zibs Patient, HealthProfessional, HealthcareProvider, BodyWeight and BodyHeight.
5 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-MedicationProcess project: https://simplifier.net/nictizstu3-medicationprocess/~resources?category=Example&exampletype=MedicationDispense%7CMedicationStatement%7CMedicationRequest%7CMedication&fhirVersion=STU3&sortBy=DisplayName
6 Release notes
Release notes can be found on the functional design page.
7 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 The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification.
- ↑ 3,0 3,1 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 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.