Slicing with Forge

This is a ‘so I can remember how I did it later’ post.

Slicing in FHIR is where you take an element that can repeat and create ‘sub-lists’ which have specific values. The example in the spec involves slicing the Observation.component element to represent a Blood Pressure measurement where you want to record the systolic and diastolic values in a single observation.

In my example I wanted to create a slice on Patient.identifier as part of the work we’re doing for the NHI (National Health Identifier) interface. Because patients are frequently duplicated in the NHI registry, it’s common for a single person to have a number of different identifiers – the current ‘active’ one, and any number of ‘old’ ones – numbers that were assigned to duplicate entries than have been merged or linked (we call them dormant ones).

There are a number of ways that we could represent this in FHIR depending on the circumstances – for our needs we want to be able to expose a single Patient resource that has all of these numbers – exactly one that is active (identifier.use = ‘official’, and all the others that they may have had in the past (identifier.use = ‘old’)

To create a profile to represent this, we’re going to need two ‘slices’ on Identifier:

• One for the current NHI with:
  • multiplicity = 1..1 (ie required0
  • system set to “https://standards.digital.health.nz/id/nhi”
  • use fixed to “official”
• One for the others with:
  • Multiplicity = 0..* (optional, many allowed)
  • system as to “https://standards.digital.health.nz/id/nhi” (It’s still from the NHI namespace
  • use fixed to “old”

There’s a free tool that you generally use for profiling called Forge – provided by the good folk at firely who have been involved with FHIR from the beginning. (They’re also the guys that host the devdays meetings – highly recommended!).

Forge is a windows application (I use VirtualBox to run it on my Mac, but apparently wine works as well) but because it has to be able to do any aspect of profiling (which can get extremely complex) the User Interface has a lot of options, and it’s not always clear which ones you need and when. Therefore this post a step by step guide for when I need to do this again and have forgotten how!

Start up Forge, and select the profile folder (where the completed profiles will be placed).

Next, click the ‘New’ Link at the top left and select New Profile (or press <control>N). You will get a list of all the available resource types – Select the Patient resource from the list, then fill in the text boxes at the lower left before clicking the OK button. (It’s easiest to do this now). Here’s what mine looked like:

It’s easiest to enter the name first (Use a capital letter to start otherwise Forge will complain later), and then adjust the canonical Url as required. This is important as it’s how we will refer to the profile from a Patient instance later on.

Click OK, and the Element Tree is displayed.

Select the identifier element and then click the ‘slice’ icon immediately above it. What this is doing is setting up the profile to add slices to the identifier element. The main thing to do here is to set the discriminator for this group of sliced elements. This can get really complicated, but in our use case it’s simple – we want to set the discriminator to be the Identifier.use element – it’s the one that will distinguish between the ‘active’ NHI and the others.

Click the + symbol to the right of the word ‘Discriminator’ which is just under the label ‘Slicing details’ half way down the screen on the right hand pane. In the drop boxes that are displayed, set the type to value and the path to use. You can also enter a description if you wish. Here’s what my screen looked like at the end of this (Note that the ‘slice’ icon now says ‘sliced’).

So now we can create the actual slices – 2 of them. First the one for the active NHI.

Making sure that the identifier element is still selected, click the ‘Add slice’ icon at the top. This will add another copy of the identifier to the tree just underneath the existing one – including all the child elements of Identifier. In the detail pane to the right enter a name for the slice and the cardinality. Just like this:

Don’t set the fixed value here! Instead, select the ‘use’ element in the tree and set the fixed value there – just like this:

The select the ‘system’ element and set the fixed value to the url of the NHI – in this case https://standards.digital.health.nz/id/nhi  

Then repeat the process to record the old (dormant) identifiers:

• Select the identifier element
• Click add slice
• Give it a name and set the multiplicity (0..*)
• Select the use element and set the fixed value to ‘old’
• Select the system element and set the fixed value

(Actually, I should probably have set the multiplicity of use and system to 1..1 . And my friend Brian Postlethwaite says I should also set the type property as well)

Finally, select the ‘Properties’ tab and add an id (makes it much easier to update the profile – which you’ll do often!)

Once you’re done, you can save the profile (click ‘save’ to the upper left). If you want, you can select the XML tab to see what the StructureDefinition looks like. This is what I had.

Once that’s done the profile is good to go. Upload it to a FHIR server. I generally use HAPI myself – the R4 server is at http://hapi.fhir.org/baseR4

To test it, create a patient instance that refers to the url profile and then POST it to the Patient/$validate endpoint (the validate operation). This resource fails validation – as there is no identifier with a use element of ‘official’. But changing the use to ‘official’ will allow it to pass.

There’s a whole lot more you can do with slicing (and profiling in general) – for example we haven’t prevented any other identifiers being used – but it’s nice to be able to do the basics!