Managing the Medication List in SNapp, part 1.

So, in the last post we talked about setting up a FHIR server, and populating it with some sample data. Let’s turn our attention now to how we would interact with that server in the context of a ‘Medication List’, and we’ll use the STU-3 release candidate (as used at the recent Baltimore connectathon) as the basis of the discussion, though this should work just as well in older versions.

(Our discussion will generally apply to other lists – such as Allergies and Problem lists – though it’s not uncommon for there to be multiple Problem Lists for a patient that are ‘clinician focussed’ e.g. the list of significant problems from the perspective of a respiratory physician tends to be different to that from the perspective of an orthopedic surgeon. But I digress…)

First, lets think about the overall architecture of the solution that we’ll be working in. As this is in support of the SNOMED SNapp, we’re really talking about the proposed ‘NZ-EHR’ – a single national source of health related data accessed freely by all that have the rights to do so. (For the purposes of this discussion we won’t consider security aspects – which in practice will be a biggie of course. Similarly we won’t consider privacy – we’ll assume that a caller has access to the entire list – again, not something likely in real life).

Here’s a picture that shows the overall ecosystem (Taken from an Orion Health presentation)


The repository is in the upper right hand corner. Systems at the bottom of the picture will access and update the list as required.

So how do we represent the List of medications? We’ve discussed that before a number of times – and most of the comments are still reasonably true, so let’s make this post more of a practical exercise.

There are quite a few different ways that you can represent a medication list in FHIR. This is deliberate as it is intended to be useable in a wide variety of contexts – and countries – and so needs to be adapted to many different environments. So we’ll mention the options, but at the same time call out the ones that would seem to make the most sense in the New Zealand context – and ones that participants at the SNApp event might choose to use.

(Though, as another side line, we’re a bit early in the process to be making firm recommendations . As we get (hopefully) closer to the reality of a single EHR in New Zealand we might want to hold one or more connectathons to test out the various possibilities before coming up with a firm proposal – and an Implementation Guide that describes it)

First, which resource will we use to represent an item (medication) in the list? There are a number of medication related resources, but we’ll settle on the MedicationStatement as the one that we’ll use. Of course applications that are updating the list may get data from other sources like MedicationOrder or MedicationDispense, but in updating the list they can easily create a MedicationStatement, so let’s go with that.

The key properties of the resource for our use include:

  • Medication – the actual drug we’re referring to. This can either be a CodeableConcept (to an underlying terminology) or a reference to a Medication resource if we need to record more details about it. Commonly this will be a contained resource, though there are other options.
  • Dosage information
  • The period over which the statement applies. This is useful to distinguish between ‘regular’ medications like anti-hypertensive medications and ‘short term’ medications such as a course of antibiotics.
  • Why the medication is being taken
  • General notes

Next – how to represent the list? Well there are a couple of options.

The one we’ve talked about most in the past is using the List Resource. This has a number of advantages:

  • We can indicate when the list was created, and by whom.
  • We can be explicit about medications that have been discontinued (Using an extension to indicate why)
  • We can be explicit that the patient is not taking any medications.
  • We can have ‘types’ of list – e.g. following a comprehensive review of all mediations, or just updating it in the context of a specific event (an antibiotic for a fixed period)
  • We can add notes to the list
  • We can easily support different versions of the list

But the primary disadvantage of the List is that it is more complex to implement – and to update – compared to the alternative option of just querying for ‘active’ MedicationStatement resources (where ‘active’ is based both on the status and the period).

So, for now, we’ll support both, but we’ll probably want to think about this a bit more in the future (and test it at connectathon!).

So – on to more practical stuff. For the examples below, I created a test patient against the public HAPI STU-3 server. But do be aware that the actual resources may be cleared when the server is re-set, however as described in the previous post, creating another test patient is trivial.

First up, we’ll need the patient id. (We can do without it, but let’s keep it simple for now).

The name of the patient I created was Nina Thomas, so the following query gave me all the patients with a name of ‘Thomas’, from which I found the id I wanted – 149632.

(As an aside, the search parameters I could have used are documented here – I think HAPI supports all of them). Note also that I’ve included the _count parameter. By default HAPI will only return 10 matches, with paging links if there are more than 10. I’m lazy, so I prefer not to have to traverse the pages – but you should watch out for the paging links and take appropriate action if they are present.

So I could retrieve the Patient resource directly like so:

and, of course, I could use the ‘Accept’ header to indicate the format I wanted – application/fhir+xml or application/fhir+json. (I find json easier to deal with as I’m a javascript developer – but either is just fine).

Now we have the patient Id we can retrieve the list.

Let’s start by assuming that we’re not using the List resource – but simply working with MedicationStatement resources.

First, let’s just get the current MedicationStatement resources for the patient.

This will return a bundle of MedicationStatement resources (up to 50) that are active. I figured out the correct query parameters from the spec. Note that I still need to examine the effctivePeriod property to be sure that the MedicationStatement is still current (It could be active, but expired for example).

What if I want to update the ‘list’? Maybe remove a medication that the patient is no longer taking?

Well, I could always delete a MedicationStatement that is no longer true. HAPI will keep a history of the resource so I can always get it back, but it’s not a very tidy solution. Instead I’ll update the status. Looking at the spec, I note there is a status of ‘completed’, which sounds like the one I want (Here’s a complete list – It has a binding strength of required, so I must use one of these ones).

So the process will be:

  1. Retrieve the MedicationStatement I want to update
  2. Change the status property
  3. Update it on the server.

Retrieving the MedicationStatement is straightforward – it’s a simple GET:

Changing the status to ‘completed’ is simple, and then I just PUT it back using the same query but with a method of PUT, and the resource in the body of the call. You’ll also need to set the Content-Type header.

Now when I query for active MedicationStatements for that patient, this one will not be in the list.

But hold on,  what if someone else updates the MedicationStatement between the time I retrieve it and the time I update it? Won’t this overwrite their changes?

Well, yes it will. The server will keep a version (providing it supports versioning that is) but that can be cold comfort. However, the specification does provide a mechanism for managing this resource contention by using ETags and the ‘If-Match’ header (kind of like Optimistic Locking). It’s up to the server to decide whether to support this – HAPI doesn’t as it is a dev server, so we won’t bother with it, but it’s good to know it’s there.

This complexity also explains why some vendors won’t support updating in this way – there are often significant business processes around updating medication lists. If a server doesn’t allow this kind of update, it can declare so in its conformance resource.

Creating a MedicationStatement is reasonably straightforward.

  1. Create the resource
  2. Set the ‘patient.reference’ property to the patient id
  3. POST to the type root (eg

The server will assign an id to it, and create the link to the patient. After that, performing the search query will include the new resource.

So that’s what’s involved in updating the list assuming a simple collection of MedicationStatement resources. However, as mentioned above, the List resource offers significant advantages at the cost of some complexity.

We’ll consider that in the next post.

About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

2 Responses to Managing the Medication List in SNapp, part 1.

  1. Pingback: Supporting SNapp: Lists of medications | Hay on FHIR

  2. Great post. If we get medications right in the personal health record, other things fall into place – adverse reactions (to medicines), problems (treated by medicines) etc. Think big, start small.

Leave a Reply

%d bloggers like this: