Supporting SNapp: Lists of medications

In this post we’re going to look at representing the Medication List using a List resource as part of supporting the SNapp event at the SNOMED conference in New Zealand next month. As we discussed in the last post – this is a preferable, albeit more complex way than just using queries against MedicationStatement resources.

To understand how this works, take a look at this image:


It’s a screen dump from clinFHIR that shows how the List resource in the middle of the graph refers to the individual MedicationStatement resources that are part of the List (as well as the patient). Yes, I know, I really need to work on those colours! Oh, and BTW take a look at this post to see how you can create your own sample patients on a FHIR server

What you can see is that you still need the individual MedicationStatement resources that represent each medication, but you now have an additional resource that adds the extra information about the list – e.g.

  • When the list was created, and by whom.
  • Type of list eg a comprehensive review of all mediations, or just updating it in the context of a specific event (an antibiotic for a fixed period)
  • Medications that have been stopped in this review (you can indicate why they were stopped using an extension)
  • Notes about the list

And we can be explicit about stating that the patient is not taking any medications (as far as we know), plus versioning of the list as it changes.

So lets see how we can do that.

Read more of this post

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…)

Read more of this post

Creating a FHIR document

A FHIR Document is simply a collection of resources inside a Bundle, with a Composition resource to hold the ‘Document level’ information. clinFHIR has special functionality to support building a document, which is triggered by adding a Composition to the scenario. Here’s a scenario before adding the Composition (a couple of Lists and an encounter):

(Note that we’ve used the ‘hide selector’) to hide the left pane. And here’s the display after the Composition is added:

(Note the new ‘Document’ tab that has appeared next to the ‘Graph’ tab).

Select that tab, and click the ‘Add section’ link. A dialog appears that allows you to select the code for the section (from the valid LOINC codes) and also any text for that section. Here’s a screen shot:

Save the section and you are then able to add resources to that section. In the next screen shot, we’ve clicked the (+) symbol to the right of the Medication list to add it to the section. We don’t need the actual medications to the section (and we shouldn’t), as they are referred to by the medication List.

If we then display the Graph view, we can see that a reference from the Composition to the List has been made automatically. In the next screen shot we’ve added a link to the Problem List, plus a reference from Composition to Encounter. We’ve also hidden the Patient resource (There’s a link just above the graph) – as that can clutter the display.

To view the document structure, select the Tree View subtab (off the ‘Document’ tab, and click the ‘generate tree’ link. Here’s the result:

To view the actual bundle, display the ‘Description’ tab, then the ‘Bundle Json’ – like this.

You can continue to build up your document as you need to. At the time of writing this post, there isn’t a good way to generate the text – that’s coming!



A sense of history with clinFHIR

I’m definitely going to finish off the series on building extensions (we have to cover coded extensions) but I must admit I’ve been a bit sidetracked in the last couple of days. You see we had a call with the ‘Clinicians on FHIR’ team talking about plans for the upcoming event at the WGM in Spain, and during the course of the discussion, Emma asked if clinFHIR could show versions of resources as she wanted to describe medication reconciliation.

At the time I said we could certainly do something like that (though I’ve not yet got that working in the Scenario Builder) but after the call I was thinking about it, and it occurred to me that what we really need is to be able to version scenarios – so we can show how they are built up, and potentially to model a workflow like fulfillment of an order or reconciliation.

So, may I present…

Read more of this post

FHIR Medication lists revisited

We’ve looked at representing a patients list of medications in a number of previous posts. This one describes using the List resource to describe the list, here we talked about updating the list using a transaction, and here were some thoughts on what a regional shared list might look like.

Just recently I’ve been involved in doing some more detailed design for this, as we’re looking at building a concrete implementation at Orion Health, so I’ve revisited how we could do it.

Read more of this post

Supporting the SNOMED SNAPP hackathon

So there’s a ‘hackathon’ (I actually don’t like that word) associated with the SNOMED conference in Wellington next month. They’re calling it a ‘SNAPP’ event (SNOMED App) – which is much nicer!

As part of supporting this event, HL7 New Zealand is going to stand up a server that can be used for the ‘My List of Medicines’ challenge. (The other challenge – Machine Mapping – is a bit esoteric for me).

So there are a couple of things we need to do.

  • Stand up a FHIR server for participants to use that can respond to appropriate requests (we’ll talk about what they will be in the next post).
  • Populate that server with the sample data given on the web site

Read more of this post

Building a set of resources in FHIR

One of the primary goals for clinFHIR is to help people who are new to the standard understand how it works – and increasingly these are clinicians whose interest is less in the technology and more about how FHIR can be used to represent the clinical information they wish to exchange.

While the current app does allow this, it has been aimed more at the people actually developing the resources than the casual user, and so can be time consuming to develop sets of resource instances that represent real world scenarios.

The component described by this post (called a simple builder – though a better name is needed!) is intended to allow someone completely new to FHIR to build sets of resources that represent clinical scenarios, to help them understand how the resources can be linked together – rather like Lego is used to build a complete model.

Read more of this post

Challenges with Lists

So one of the challenges we’re facing at work at the moment is Lists – more specifically ‘current’ lists – eg the medications a patient is taking right now, their problem list and set of allergies.

A bit of background.

Read more of this post

Using workflow to track comments

So there’s a requirement that’s come out of the UK profiling work (among others) to be able to gather comments about logical models as part of getting feedback – particularly from Clinicians.

Read more of this post

Updating the Medication List

In the previous post, we discussed using a List resource to represent a patient’s list of medications. In this post we’re going to talk about updating that list  – i.e. when a clinician changes the medications that a patient is taking, and wishes to record that change in the List. There are a few ‘gotcha’s to be aware of here. (By the way, do note that this discussion applies to any use of List – e.g. a list of conditions – as much as to medications).

Before we start, it’s important to appreciate that the List resource is something that ‘collects’ resources together (the other being the Group resource) – it contains a number of references to other resources that are stored somewhere else (often – but not necessarily – on the same server as the List).

Another thing to mention in passing is that much of what we are discussing here also applies to representing medications in other constructs such as FHIR Documents & Messages – though that is a big topic in its own right that will need to wait for another time…

Let’s consider the simple situation where a patient is taking 2 medications. There will therefore be:

  • 1 Practitioner resource (at least) as prescriber of medications and author (source) of the list
  • 1 Patient resource
  • 2 MedicationPrescription resources describing the medications
  • 1 List resource that has references (or pointers) to those resources.

This might look like this:

mlom v1a (1)

Note the links between the resources, representing the resource references – the meaning of those references should be evident. The List is labelled MLOM (My List Of Medicines) and has a specific code that identifies it as such as discussed in the previous post.

Now imagine that the Atenolol is stopped, and is replaced by Labetolol. This would give us the following picture:

mlom v2


  • There is a new version of the List resource (It has the same ID as the previous one)
  • The new List version has a different ‘source’ practitioner – Dr Jones
  • We have indicated that the Prescriber of the medication is also the author (source) of the List.  They may be the same (as it is here), but they don’t have to be.
  • The new version of the List still points to the Atenolol resource – even though it has been stopped. We don’t strictly need this reference, but it is really useful as it suggests that the Atenolol was stopped (and possibly why) at the same time as the Labetolol was started. Of course the List resource and MedicationAdministration will have ‘formal’ properties that inform a consumer that the medication is no longer being taken – refer to the previous post for details. You can also set the date stopped in the MedicationPrescription directly as explained below.

So, lets walk through the sequence of actions that needs to occur in making this change in a RESTful fashion. We assume that we have the patient ID.

  1. GET the existing List of medications (eg GET /Patient/100/List?code=|10160-0 which is a FHIR query that will return a bundle containing the List). Make a note of the ID of the List. (Note that we’ve been good here and added the LOINC namespace to the query).
  2. GET the medicationPrescription that we are stopping (its ID will be in the list), set the status property to ‘nullified’ and then PUT it back as an update. (You might also set the MedicationPrescription.dosageInstruction.timing.repeat.end to the date stopped if you are using a schedule datatype here).
  3. Create a new MedicationPrescription resource with the appropriate properties & references, and POST it as a new resource. Make a note of the ID that was assigned by the server (it will be in the Location header).
  4. Update the entry of the stopped medication in the List resource by:
    1. Setting the flag property to ‘cancelled’
    2. Setting the deleted property to true
    3. Optionally, add an extension to the entry indicating the reason why it was stopped
  5. Add a new entry in the List that references the new medication (which is why we made a note of the ID above).
  6. PUT a new version of the List back.

This isn’t particularly complex, but we can see that when we perform an update like this, there are a number of steps that must all succeed, or must all fail – i.e. this is really a transaction. We have a couple of ways of doing this.

  • The client can perform each step in turn as described above – checking that each one succeeds and taking responsibility for ‘rolling back’ any changes in the event that there is a failure or if some other client has updated any of the resources in the mean time. This could become complicated…
  • The alternative is to create or update all the resources on the client, and then place them into a bundle which is sent to the server to process as a single transaction, in which case the server takes the responsibility for ensuring the success – or failure – of the whole operation.

Lets walk through the same process as if it were a transaction – but first a few notes on using a bundle in this way.

In FHIR, a bundle is an Atom feed – and can be represented in both XML and JSON. I’ve already talked about this, and the spec has the definitive description, but just to point out a couple of things about the bundle entry elements that are pertinent. Each entry represents a FHIR resource and has a number of ID’s:

  • is the logical ID of the resource – not the version specific ID. Ie it is always the same for any given resource.
  • to self (<link rel=’self’…) is a version specific ID. Ie it points to a specific version of the resource. It’s an optional element, but its particular value here is that it will allow the server to apply update logic to avoid conflicts – as we will see in a moment.

Moving on, this is the process to update the List using a server transaction:

  1. Create a new bundle (an atom feed) that will hold all our updated and new resources and populate the required properties.
  2. GET the existing List of medications as described above. Make a note of the ID of the List.
  3. GET the MedicationPrescription that we are stopping, set the status property to ‘nullified’ and then add it to the bundle, setting the bundle to the ID of the MedicationPrescription. As Above, you might also set the medicationPrescription.dosageInstruction.timing.repeat.end to the date stopped if you are using a schedule datatype.
  4. Create a new MedicationPrescription resource with the appropriate properties & references and add it to the bundle. Create a temporary ID using the CID scheme and assign it to the bundle (The server will know to replace this with a real ID).
  5. Update the resource of the stopped medication in the List entry by:
    1. Setting the flag property to ‘cancelled’
    2. Setting the deleted property to true.
    3. Optionally, add an extension to the entry indicating the reason why it was stopped (as shown in the previous post)
  6. Add a new List.entry to the List resource that references the new medication using the temporary ID that we created above, and setting the other properties of the entry as appropriate. (Unfortunately both List and Bundle use the word ‘entry’ which can be confusing).
  7. Add the updated List Resource to the bundle, setting the bundle to the ID of the List.
  8. POST the bundle to the root of the server.

The bundle will therefore contain:

  • 2 MedicationPrescription resources (1 new & 1 updated) and
  • 1 List resource

When the server receives the bundle, it will update and/or create all the resources as if they had been individually submitted – but will do so as a transaction, returning an HTTP statusCode to indicate success or failure.

The server can also implement other business and validation logic – for example checking that the version of the List resource (or any of the resources for that matter) in the bundle is the same as its current version on the server – i.e. the ‘optimistic locking’ pattern. In this case, the client should also include a “<link rel=’self’> “ element in each bundle entry that contains the version-specific URI of the resource so that the server can make the comparison. Refer to the discussion of the transaction and the bundle above for the details of this process.

So this method offloads the complexity of managing the transaction to the server, which ‘feels’ the right place to manage any transactional processing, and also minimizes the work for the client.

Incidentally, the ability for a server to require that an update operation specifies the version of the resource that it is updating can be applied to all update operations.


  • If this process is repeated with further updates, you’d probably want to remove entries in the list that are already deleted – otherwise the List will bloat with lots of deleted medications.
  • You can always use the history operation to get previous versions of the List – ie the change history of medications for the patient. This allows you to create a ‘timeline’ of changes.
  • We suggested setting the MedicationPrescription.dosageInstruction.timing.repeat.end to the date the medication was stopped. This is not strictly the correct use of this property as it is more intended to represent an instruction (stop on this date) rather than a record (it was stopped on this date).