FHIR Implementation Guide Medication Process 9 version 3.0.0-beta.4 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.4 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 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 when non-FHIR systems are not involved. However: all resources referenced per literal reference SHALL be resolvable per the Nictiz IG. In the case of retrieving and serving data with non-FHIR systems and where transforming data is involved, it is required to include additional resources to ensure that the bundles get transformed to valid HL7v3 (CDA) messages. This requires additional includes in the request and the usage of the modifier iterate which is explained in ‘Additional search parameters and includes’. |
_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’).
Another note to make is that in case HL7v3 systems are involved in retrieving and serving data, additional includes are needed in the request. This is explained and defined in ‘Additional search parameters and includes’.
3.1.1.3 Additional search parameters and includes
When non-FHIR systems are involved and transformation to HL7v3 (CDA) is part of retrieving and serving data; including additional resources is necessary to ensure a successful transformation of a bundle to a valid HL7v3 message. This requires the support of additional (custom) search parameters, additional includes and the usage of the modifier iterate. All search parameters and the accompanying includes listed in the table below SHALL be supported by the servers and may be supported by clients when transformation to HL7v3 (CDA) is needed.[4] This is in addition to the search parameters mentioned in ‘Search parameters’.
The definitions of the custom search parameters can be found in the FHIR package:
- SearchParameter author
- SearchParameter dispense-location
- SearchParameter location
- SearchParameter next-practitioner
- SearchParameter prescriber
- SearchParameter reason
| Building block | FHIR resource | FHIR search parameters | Required includes |
|---|---|---|---|
| MedicationAgreement | MedicationRequest | MedicationRequest:reason, MedicationRequest:next-practitioner, MedicationRequest:requester | _include=MedicationRequest:reason _include=MedicationRequest:next-practitioner _include=MedicationRequest:requester _include=MedicationRequest:patient _include:iterate=PractionerRole:organization _include:iterate=PractionerRole:practitioner _include:iterate=PractionerRole:location |
| DispenseRequest | MedicationRequest | MedicationRequest:intended-performer, MedicationRequest:requester, MedicationRequest:dispense-location | _include=MedicationRequest:intended-performer _include=MedicationRequest:requester _include=MedicationRequest:dispense-location _include=MedicationRequest:patient _include:iterate=PractionerRole:organization _include:iterate=PractionerRole:practitioner _include:iterate=PractionerRole:location |
| AdministrationAgreement | MedicationDispense | MedicationDispense:performer, MedicationDispense:location | _include=MedicationDispense:performer _include=MedicationDispense:location _include=MedicationDispense:patient _include:iterate=PractionerRole:organization _include:iterate=PractionerRole:practitioner _include:iterate=PractionerRole:location |
| MedicationAdministration2 | MedicationAdministration | MedicationAdministration:performer | _include=MedicationAdministration:performer _include=MedicationAdministration:patient _include:iterate=PractionerRole:organization _include:iterate=PractionerRole:practitioner _include:iterate=PractionerRole:location |
| MedicationDispense | MedicationDispense | MedicationDispense.performer, MedicationDispense.location, MedicationDispense.destination | _include=MedicationDispense:performer _include=MedicationDispense:location _include=MedicationDispense:destination _include=MedicationDispense:patient _include:iterate=PractionerRole:organization _include:iterate=PractionerRole:practitioner _include:iterate=PractionerRole:location |
| MedicationUse2 | MedicationStatement | MedicationStatement.presciber, MedicationStatement.source,MedicationStatement.author | _include=MedicationStatement:prescriber _include=MedicationStatement:source _include=MedicationStatement:author _include=MedicationStatement:patient _include:iterate=PractionerRole:organization _include:iterate=PractionerRole:practitioner _include:iterate=PractionerRole:location |
Retrieving all known medication data is similar to ‘Retrieve all medication data’ but has additional includes:
GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005&_include=MedicationRequest:medication&_include=MedicationRequest:patient &_include=MedicationRequest:reason&_include=MedicationRequest:next-practitioner&_include=MedicationRequest:requester &_include:iterate=PractionerRole:organization&_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
GET [base]/MedicationRequest?category=http://snomed.info/sct|52711000146108&_include=MedicationRequest:medication&_include=MedicationRequest:patient &_include=MedicationRequest:intended-performer&_include=MedicationRequest:dispense-location&_include=MedicationRequest:requester &_include:iterate=PractionerRole:organization&_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
GET [base]/MedicationRequest?category=http://snomed.info/sct|395067002&_include=MedicationRequest:medication&_include=MedicationRequest:patient &_include=MedicationRequest:reason&_include=MedicationRequest:next-practitioner&_include=MedicationRequest:requester &_include:iterate=PractionerRole:organization&_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
GET [base]/MedicationDispense?category=http://snomed.info/sct|373784005&_include=MedicationDispense:medication&_include=MedicationDispense:patient &_include=MedicationDispense:destination&_include=MedicationDispense:location&_include=MedicationDispense:performer &_include:iterate=PractionerRole:organization&_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
GET [base]/MedicationDispense?category=http://snomed.info/sct|422037009&_include=MedicationDispense:medication&_include=MedicationDispense:patient &_include=MedicationDispense:location&_include=MedicationDispense:performer&_include:iterate=PractionerRole:organization &_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
GET [base]/MedicationStatement?category=http://snomed.info/sct|422979000&_include=MedicationStatement:medication&_include=MedicationStatement:patient &_include=MedicationStatement:prescriber&_include=MedicationStatement:author&_include=MedicationStatement:source &_include:iterate=PractionerRole:organization&_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
GET [base]/MedicationAdministration?category=http://snomed.info/sct|18629005&_include=MedicationAdministration:medication&_include=MedicationAdministration:patient &_include=MedicationAdministration:performer&_include:iterate=PractionerRole:organization &_include:iterate=PractionerRole:practitioner&_include:iterate=PractionerRole:location
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.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. - ↑ For the MedicationRequest and MedicationDispense resource types, the
period-of-useparameter 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.effectiveto include the ext-TimeInterval.Duration extension that may be present. - ↑ The CareInformationBroker (ZIM) uses these includes as client in order to query all data needed by the MessageTransformationService (BTD).
