Supporting SNAPP: Accessing New Zealand Medicines Terminologies With FHIR Terminology Services

A guest post from Peter Jordan – author of the Patients First Terminology server that will be available for use at SNApp, and frequent HL7 FHIR Connectathon attender…

Take it away Peter…

As those developing healthcare applications for the local market are well aware, and overseas developers preparing for the ‘SNAPP’ event at the upcoming SNOMED conference in Wellington, are becoming aware, New Zealand has its own medicines terminology. Interacting with this terminology – broadly known at the NZ Universal List of Medicines (NZULM) – is one of the many challenges facing SNAPP participants.

In common with the self-deprecating slogan used to advertise a local soft drink, NZULM happens to be ‘world famous in New Zealand’, but little known outside the ‘Shaky Islands’. Therefore, in the interests of levelling the playing field for all contestants (and there is prize money at stake here), this post is a brief introduction to NZULM and how one may interact with it using a Terminology Services API based on…no surprises to readers of this Blog…FHIR.

While NZULM shares some similarities with SNOMED CT (SCT-compatible identifiers, fully-specified names and preferred terms), to date it has not been designed as a SNOMED-CT national drug extension and therefore, not instantly accessible through the Implicit Value Set syntax that FHIR offers for accessing SNOMED CT.

In fact NZULM consists of several components, the main one – particularly for this purpose – being the NZ Medicines Terminology (NZMT). In FHIR parlance, one might describe this as the Code System. In relational database terms, this consists of a large number of tables, but the key objects are those designed to hold the seven distinct “product concepts” – collectively known as the “Seven Boxes”:

In addition, the monthly distribution includes several combined views of these tables, the most significance of which – for SNAPP anyway – might be that containing all the unique available prescribing terms, generic and trade, with their associated concept identifiers and a flag to indicate whether the term is generic or trade.

Now – short of downloading grabbing the entire NZULM package and digesting copious amounts of additional documentation – how does one interact with this complex terminology without attempting to become an overnight expert? The answer offered here centres on the value proposition for terminology services – delegate most of that responsibility to specialist software and interact with a relatively simple, standards-based, API. In particular, the NZ Terminology Server (Terminz) built by Patients First Ltd.

For a simple introduction to Patients First Terminology Services a simple interactive test page is provided here: http://itp.patientsfirst.org.nz/Home/Terminology

1. Choose a Value Set
2. Select an operation
3. Enter a description (expand) or code (lookup and validate)
4. Click Submit Request…view results and the request URL (below)

For API access, assuming some knowledge of the basics of FHIR and the Terminology Service Section of the Specification, here are some basic URLs…

// Base URL
http://its.patientsfirst.org.nz/RestService.svc/Terminz/

// request a Conformance Statement
http://its.patientsfirst.org.nz/RestService.svc/Terminz/metadata

// request definitions of all the available Code Systems
http://its.patientsfirst.org.nz/RestService.svc/Terminz/CodeSystem

// request definitions of all the available Value Sets
http://its.patientsfirst.org.nz/RestService.svc/Terminz/ValueSet

The list of Value Sets contains an entry for each of the 7 NZMT Boxes tabulated above, plus an additional 3 that provide ‘generic only’, ‘trade only’ and ‘all’ concepts from the Prescribing Terms Table. These can be used at the target for requesting Expansions (e.g. for populating dropdowns controls on a user interface) or to Validate that a particular Code (concept identifier) belongs in a particular value set.

For example…

// [BASE ValueSet URL]
http://its.patientsfirst.org.nz/RestService.svc/Terminz/ValueSet/NZULM_Prescribing_Terms/

// Expansion filtered on all terms containing ‘cilazapril’
[BASE ValueSet URL] $expand?filter=cilazapril

// Validate that this code & code system combination belong to the Value Set
[BASE ValueSet URL] $validate-code?system=http://nzmt.org.nz&code=10348841000116107

Requests to Lookup codes operate across the NZMT Code System as a whole (i.e. the “Seven Boxes” of NZMT, which includes those contained in the Prescribing Terms Value Sets)…

// [BASE CodeSystem URL]
http://its.patientsfirst.org.nz/RestService.svc/Terminz/CodeSystem/

// Lookup this code in the passed code system and return any designations
$lookup?system=http://nzmt.org.nz&code=10348841000116107&property=designation

Note that the last request also asks for the designations which, in addition to the code system, code and description, will return the following information…

• NZULM Type…which of the Seven Boxes the code belongs to
• Medicinal Product…The name of the generic substance linked to this concept
• Is Base Substance…Whether the generic substance is the base substance
• Ingredient…The active ingredient(s) in the generic substance

Happy SNAPPing!