HL7 FHIR Implementation Guide - New Zealand Formulary/NZULM IG
1.0.0 - ci-build
HL7 FHIR Implementation Guide - New Zealand Formulary/NZULM IG, published by New Zealand Medicines Formulary LP. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7NZ/nzf/ and changes regularly. See the Directory of published versions
DRAFT - SUBJECT TO CHANGE, NOT FOR CLINICAL USE
THE NZF/NZULM FHIR API provides support for interactions checking based on Stockley’s Alerts. This support comes in the form of two custom FHIR Operations. The first provides a list of interactions for a given NZMT medication and the second provides a list of interactions between a list of NZMT medication codes. This second API call can be limited to checking against a focussed nzmt id code.
Each API call returns a Bundle which, alongside associated resources, returns a list of ClnicalUseDefinitions
The NZ Formulary currently provides support for interactions checking via their websites and via the older webservice. The older webservice is being phased out and being replaced by this newer FHIR API. These custom operations provide support for interactions checking and should provide a level of familarity with the existing webservice calls. Due to contractual constraints the interactions data (i.e. the clinical use definitions) can not be provided via a download or for searching via the standard FHIR API. The only way to retrieve interactions data is via these custom operations.
Stockley’s Alerts data is currently provided via XML in a drug to drug format using Martindale Ids as the code for each interactant. Each interaction is a one to one interaction. The New Zealand Formulary maps NZMT Medicinal Products (MP) to Martindale Ids to support retrieving interactions for the NZMT system. When a NZMT code is submitted to the API, the related MP or MPs for each medication are retrieved. These MPs are then used to get the mapped Martindale Ids which are then used to retrieve the appropriate interaction records in the form of ClinicalUseDefinitions. In accordance with the intended design of the FHIR ClinicalUseDefinition each one to one Stockley’s interaction is mapped to two ClinicalUseDefinition records, the first has one interactant as the subject and the other as the interactant and the second has the subject and interactants switched.
For example:
Given the NZMT Id of 20025461000116102 - Paracare (paracetamol 500 mg) tablet: uncoated, 1 tablet
The system will retrieve the MP of 20025461000116102 - Paracetamol via the Medication resource related medication extension.
The system will then determine that this MP is mapped to the Martidale Id of (2679-p - paracetamol)
This martindale id is then used to retrieve the associated interactions (in the form of Clinical Use Definitions)
Note - It is possible that a submitted medication code (or a component of a medication) has not yet been mapped to a Martindale Id. If this happens then an OperationalOutcome with a status of warning is returned. The specific component can also be determined via the returned Medication and ConceptMap resources.
The interaction system has two distinct API methods, each of which return a bundle. Both methods also allow for an optional parameter (includeMedicationAndConceptMap) to indicate whether the medication and concept map resources should be returned in the response bundle.
An OperationOutcome is included in the bundle if there is an error or a warning.
An error will occur if any of the NZMT codes are not valid or not recognised.
A warning will occur if an NZMT code has not yet been mapped to an interaction substance code (mart-id)
The full medication resource for each submitted NZMT code is returned in the Bundle. These are provided for convenience and provide tracibility around which MP(s) are associated with the given medication.
A partial concept map is provided detailing the mapping between NZMT MPs and their associated Martindale Ids. If a MP has not yet been mapped to a Martindale Id then there will be no codes listed. However, if a MP has attempted to be mapped by the NZF but no appropriate Martindale Id was determined then this is recorded as Unmatched in the Concept Map resource.
{
"resourceType": "ConceptMap",
"id": "9f0ab0a4-5068-4616-b923-9ec3ff7a69da",
"status": "draft",
"group": [
{
"source": "http://nzmt.org.nz",
"target": "http://rpharms.com/mart-id",
"element": [
{
"code": "46125321000116100",
"target": [
{
"code": "20322-a",
"equivalence": "inexact",
"comment": "[NEEDS COMMENT]"
},
{
"code": "21229-g",
"equivalence": "inexact",
"comment": "[NEEDS COMMENT]"
},
{
"code": "22631-n",
"equivalence": "inexact",
"comment": "[NEEDS COMMENT]"
},
{
"code": "24730-x",
"equivalence": "inexact",
"comment": "[NEEDS COMMENT]"
},
{
"code": "9021-f",
"equivalence": "inexact",
"comment": "[NEEDS COMMENT]"
},
{
"code": "9043-v",
"equivalence": "inexact",
"comment": "[NEEDS COMMENT]"
}
]
},
{
"code": "20006751000116107",
"target": [
{
"equivalence": "unmatched"
}
]
}
]
}
]
}
A profile for interactions is provided here - Draft/Work in progress
Takes a NZMT Id (MP, TP, MPP, TPP, MPUU, TPUU or CTPP) and returns the Stockley’s interactions for that given id
nzmtid: fhir string - which is a NZMT Code for any of the following concepts (MP, TP, MPP, TPP, MPUU, TPUU or CTPP) includeMedicationAndConceptMap: boolean - which indicates whether the medication and concept maps should be included in the returned bundle
GET [base]/Medication/$interactions-of?nzmtId=10037191000116105&includeMedicationAndConceptMap=true
Takes two or more NZMT Ids (MP, TP, MPP, TPP, MPUU, TPUU or CTPP) and returns the Stockley’s interactions between those NZMT Ids
nzmtid: fhir strings - two or more NZMT Codes from any of the following concepts (MP, TP, MPP, TPP, MPUU, TPUU or CTPP)
includeMedicationAndConceptMap: boolean - which indicates whether the medication and concept maps should be included in the returned bundle
filterComplementaryRecords: boolean - when true complementary clinical use definitions are filtered out. These records are when an interaction is the same except the subject and interactant are reversed.
[HttpPost] POST [base]/Medication/$interactions-between content-type: application/json
{
"resourceType": "Parameters",
"id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
"parameter": [
{
"name": "nzmtid",
"valueString": "10037191000116105"
},
{
"name": "nzmtid",
"valueString": "10194111000116109"
},
{
"name":"includeMedicationAndConceptMap",
"valueBoolean": true
},
{
"name":"filterComplementaryRecords",
"valueBoolean": true
}
]
}
Takes a single focussed nzmt id and one or more other nzmtids and returns interactions between the focussed nzmt and the other nzmt ids. Interactions between the other nzmt ids are not performed.
All NZMT Ids need to be within the following concepts - MP, TP, MPP, TPP, MPUU, TPUU or CTPP.
focussednzmtid: fhir string - a single NZMT Codes from any of the following concepts (MP, TP, MPP, TPP, MPUU, TPUU or CTPP)
nzmtid: fhir strings - two or more NZMT Codes from any of the following concepts (MP, TP, MPP, TPP, MPUU, TPUU or CTPP)
includeMedicationAndConceptMap: boolean - which indicates whether the medication and concept maps should be included in the returned bundle
filterComplementaryRecords: boolean - when true complementary clinical use definitions are filtered out. These records are when an interaction is the same except the subject and interactant are reversed.
[HttpPost] POST [base]/Medication/$interactions-between content-type: application/json
{
"resourceType": "Parameters",
"id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
"parameter": [
{
"name": "focussednzmtid",
"valueString": "10010681000116105"
},
{
"name": "nzmtid",
"valueString": "10037191000116105"
},
{
"name": "nzmtid",
"valueString": "10194111000116109"
},
{
"name":"includeMedicationAndConceptMap",
"valueBoolean": true
},
{
"name":"filterComplementaryRecords",
"valueBoolean": true
}
]
}
Specific definitions of the codes are provided via Code system definitions. More details to follow.
Details to follow
Due to legal reasons we cannot provide a full download of all of our source data via the clinical use definitions. These therefore need to be provided via an API on a per medication basis.
The medication and concept maps resources are optionally included in the reponse (defaulting to be included). The reason for this is that it provides full tracibility to the mapping process.