FHIR Implementation Guide Medication Process 9 version 2.0.0 for patient use cases
1 Introduction
This is the implementation guide (IG) for the information standard Medication Process 9 (MP9) version 2.0.0 for patient use cases (MedMij) using the HL7® FHIR® standard. The MP9 standard is described in this functional specification and further specified here using FHIR version R4. This implementation guide assumes that the reader is familiar with both the functional specification of both MP9 and MedMij and this version of FHIR.
This document is a specification of FHIR Implementation Guide Medication Process 9, only applicable to the patient use cases. The guidelines as specified in the MedMij FHIR Implementation Guide apply. This document extends the general FHIR Implementation Guide with the specification of the 'Afsprakenstelsel'.
This IG first describes the boundaries and relationships where they differ between the MP9 and MedMij IG, after which the implementation is described per relevant transaction.
2 Boundaries and relationships
Both the MP9 Boundaries and relationships and the MedMij Overarching principles apply. The following sections highlight the points where these two documents contradict and provides guidance on which principles to follow
2.1 Patient identification
Where the MP9 describes the use of patient.identifier search parameters, the patient use cases use the authentification method outlined by the MedMij 'Afsprakenstelsel', using Oauth2 tokens.
3 Transactions
This section describes the FHIR implementation of the Retrieve and Serve Medication Data transactions (for patient use cases) listed in section 7 of the functional specification. Each transaction hyperlinks to the functional definition in an ART-DECOR publication. The ART-DECOR publication details which data elements are expected to be supported (cardinality and conformance). Where the functional specification uses the terms ‘Consulting’ and ‘Making available’, this IG uses the terms ‘Retrieving’ and ‘Serving’.
3.1 Medication data (Retrieve/Serve)
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 for specific medication building blocks.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| Medication data (PULL) | Retrieving medication data | Client | MP-MGR | CapabilityStatement Retrieve/serve medication data |
| Serving medication data | Server | MP-MGB |
3.1.1 Retrieve (request message)
When a patient or healthcare professional wants to obtain all medication data or specific parts matching various parameters, they issue 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 search query. Multiple request messages may be needed to retrieve all desired information.
GET [base]/[type]{?[parameters]}
3.1.1.1 Search parameters
All search parameters listed in the table below SHALL be supported for processing by servers and MAY be supported by clients.
| MP9 search parameter | Description | FHIR search parameter | FHIR resource | Example |
|---|---|---|---|---|
| PatientIdentificationNumber | Search on patient. | patient.identifier [1]
|
MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration | 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 |
| Identification | Search on identifier. | identifier
|
MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration | Retrieves a MedicationRequest resource with a specific identifier.
GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448 |
| Identification | Search on the pharmaceutical treatment identifier.
Note: retrieval of all medication resources belonging to one pharmaceutical treatment requires to search on all medication resource types. |
pharmaceutical-treatment-identifier [2]
|
MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration | Retrieves all MedicationRequest resources that are part of a pharmaceutical treatment with a specific identifier.
GET [base]/MedicationRequest?pharmaceutical-treatment-identifier=http://example.nl/fhir/NamingSystem/pharmaceuticaltreatment|1247848 |
| Type | Search on type of medication building block. | category [2]
|
MedicationRequest | Retrieves all MedicationRequest resources that represent the building block MedicationAgreement.
GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005 Retrieves all MedicationRequest resources that represent the building block DispenseRequest. GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108 Retrieves all MedicationRequest resources that represent the building block VariableDosingRegimen. GET [base]/MedicationRequest?category=http://snomed.info/sct|395067002 |
| MedicationDispense | Retrieves all MedicationDispense resources that represent the building block MedicationDispense.
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005 Retrieves all MedicationRequest resources that represent the building block AdministrationAgreement. GET [base]/MedicationRequest?category=http://snomed.info/sct|422037009 | |||
| MedicationStatement | Retrieves all MedicationStatement resources that represent the building block MedicationUse2.
GET [base]/MedicationStatement?category=http://snomed.info/sct|422979000 | |||
| MedicationAdministration | Retrieves all MedicationAdministration resources that represent the building block MedicationAdministration2.
GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005 | |||
| MedicationCode | Search on medication code. | medication.code[3]
|
MedicationRequest, MedicationDispense, MedicationStatement, MedicationAdministration | Retrieves all MedicationRequest resources that represent the building block MedicationAgreement and have Carbasalaatcalcium Sandoz 600 30 as medication.
GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005&medication.code=urn:oid:2.16.840.1.113883.2.4.4.8|13610554 |
| PeriodOfUse | Search on medication use in the past, present or future within the specified time period. | period-of-use[2]
|
MedicationRequest, MedicationDispense | Retrieves all MedicationRequest resources that represent the building block MedicationAgreement and were in effect from 01-01-2010.
GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005&period-of-use=ge2010-01-01 |
| DispensePeriod | Returns all medication dispenses within the specified time period. | whenhandedover
|
MedicationDispense | Retrieves all MedicationDispense resources that represent the building block MedicationDispense 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 the building block MedicationAdministration2 and where administration happened on a specific day.
GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&effective-time=eq2022-01-01 |
| - | 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.
Supporting the include of the Patient and Medication resources referenced by building blocks is required. Others (Organization, Location, PractitionerRole, Practitioner, RelatedPerson, Observation) are optional. However: all resources referenced per literal reference SHALL be resolvable per the Nictiz IG. |
_include=[type]:patient
|
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 |
The following custom search parameters are defined for this transaction:
- http://nictiz.nl/fhir/SearchParameter/pharmaceutical-treatment-identifier
- http://nictiz.nl/fhir/SearchParameter/category
- http://nictiz.nl/fhir/SearchParameter/period-of-use
3.1.1.2 Retrieve all medication data
To retrieve all known medication data, a client has to execute the following requests to retrieve all known medication data per building block, including referenced Medication resources:
GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005&_include=MedicationRequest:medication GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108&_include=MedicationRequest:medication GET [base]/MedicationRequest?category=http://snomed.info/sct|395067002&_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.1.2 Serve (response message)
The server returns an HTTP Status code appropriate to the processing outcome and returns a Bundle, with Bundle.type = searchset, including the resources matching the search query medication data. The resources included in the Bundle SHALL conform to the profiles listed in the 'List of profiles' below.
3.1.3 List of profiles
The table below includes all profiles that are explicitly mentioned in the data set of this transaction, and thus need to be supported.
4 Release notes
Release notes can be found here.
5 Footnotes
- ↑ This search parameter only needs to be supported when patient identification requires the use of search parameters, see section 2.4.
- ↑ 2,0 2,1 2,2 The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification. Note that for
MedicationRequest.categoryandMedicationStatement.categorya core search parameter is available, hence no custom one is needed in those cases. - ↑ Chained search parameter: searches the medicationReference required in each building block for its
.code.