FHIR Implementation Guide Medication Process 9 version 3.0.0-beta.3 for patient use cases
Deze versie zal worden getoetst tijdens de kickstart medicatieoverdracht. De versie is niet geschikt voor gebruik buiten deze beproeving. |
1 Introduction
This is the implementation guide (IG) for the information standard Medication Process 9 (MP9) version 3.0.0-beta.3 for patient use cases (MedMij) using the HL7® FHIR® standard. The MP9 standard for MedMij 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 'Use cases' or 'transactions'
Where MP9 uses the term 'transaction', MedMij generally uses the term 'use case'. On this page, the terms are used interchangeable.
2.2 Patient identification
Where MP9 describes the use of patient.identifier
or subject:Patient.identifier
search parameters, the MedMij use cases use the authentication 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 MedMij) listed in 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).
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 (MedMij) |
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
|
---|---|---|---|---|
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 [1]
|
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 [1]
|
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 MedicationDispense resources that represent the building block AdministrationAgreement. GET [base]/MedicationDispense?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 [2]
|
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 the MedicationAgreement, VariableDosingRegimen, AdministrationAgreement and MedicationUse2 building blocks that are related to medication that was used, is used or will be used during the indicated period.
Whenever a search is done on the MedicationAgreement, VariableDosingRegimen or AdministrationAgreement building blocks it is required to also include the latest stopped building blocks of that kind within each pharmaceutical treatment, even if these have a period of use outside the PeriodOfUse that is being searched on. |
period-of-use [1]
|
MedicationRequest, MedicationDispense, MedicationStatement[3] | 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
Note that in this transaction, these search requests are always executed in the context of a single patient and thus should include a patient identification mechanism (see ‘Patient identification’).
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
- ↑ 1,0 1,1 1,2 The search parameter consists of a custom FHIR search parameter not represented in the FHIR specification. Note that for
MedicationRequest.category
andMedicationStatement.category
a 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
. - ↑ For the MedicationRequest and MedicationDispense resource types, the
period-of-use
parameter searches on the ext-TimeInterval.Period extension which may include the ext-TimeInterval.Duration extension. For the MedicationStatement resource type, the parameter modifies the core search parameter on.effective
to include the ext-TimeInterval.Duration extension that may be present.