Using clinFHIR to create a profile

In the previous post, we outlined our plans for creating a profile against the Patient resource, and manually created and saved some of the supporting resources (ValueSet and our NamingSystem) that we’re going to need.

Next up is the extension definition and the actual profile against Patient. Once we’ve done that (which is the topic of this post) we can actually create conformant resources.

Fortunately, we can use clinFHIR to create these artifacts, so start up that application and select the ‘profile builder’ from the front page. (And a reminder that this is very much ‘beta’ software designed for training! Let me know of any issues)

The overall process we’ll follow is this.

1. Select the base resource that we are going to profile (Patient)
2. Disable the photo (and anything else we don’t want in our profile – like animal for example)
3. Set the Identifier to be one only, and set the required system (NHI)
4. Create a new extension definition that will record the patients Iwi
5. Add the extension to the profile
6. Save the profile.

To work.

There’s a dropdown labeled ‘Base Resource’ on the toolbar. Click it, and select the ‘Patient’ type. After a brief delay, the elements of the Patient resource will be displayed in the left side of the screen. Here’s what it looks like.

There are 6 columns.

The Path is the ‘location’ of the element in the resource. If you click on it then a detailed display will be shown on the right side. We’ll use this when we set the NamingSystem for identifier, but it has other capabilities we’ll talk about another time (or just click around and see what things do!).

Card stands for ‘cardinality’ – how many of these elements can be in an instance.

DataType is just that. Neither Cardinality nor dataType will do anything if clicked.

Then there are 3 checkboxes.

Req is required. If we select this checkbox then we are saying that our profile requires that this element must be present in a conformant instance. You’ll notice that if the element is already required in the base resource, then the box is missing. You can’t make a required element optional in a profile. (It’s a wee bit more complex than that, but that will do for now)

Mult stands for multiple. If checked then it means that there can be more than one of these elements in a conformant resource. Note that you can only make an element that is already multiple become single – you can’t do it the other way around.

Incl is include. If this is unchecked then the element is not available in the profile. Do this for photo to remove it from your profile. If you remove other elements, just be aware that the display is a ‘flattened hierarchy’ and be careful to remove all the elements you need to. For example, if you wanted to remove ‘animal’, then you’d need to remove Patient.animal, Patient.animal.species, Patient.animal.breed and Patient.animal.genderStatus. If you are inconsistent here, then the profile will be a bit weird.

Next let’s adjust Patient.Identifier.

Uncheck the ‘mult’ checkbox – and note that the cardinality changes from 0..* to 0..1    If you want to make it required as well, then check the req. box – and the cardinality becomes 1..1 and the path colour becomes red.

Now to set the system. Click on the path ‘Patient.identifier’ and then in the details on the right hand side drop down the ‘system’ combo box. This box has a list of all the known NamingSystem resources in the registry. NHI should be there, and you can select it.

Now for the extension.

We’ll create the extension definition first, then attach it to our profile, and finally save the profile. Now, in real use you’d first search to see if there was an extension already defined that you could use – re-use of extension definitions is a good thing as it makes it more likely that a resource consumer will understand your extension. We’ll just create one to see how that works.

First of all click on the ‘Patient’ path. This indicates that we are adding the extension at the ‘root’ of the resource. It’s possible to add an extension to any element (including another extension) and even to a datatype – though clinFHIR doesn’t support that as yet.

To the upper right of the profile builder is a button titled ‘New’ under an ‘Extension’ label. Click that. You should get a screen that looks like the screenshot below. (Oh, you can see the ‘Find’ button there as well if you know that there is already an extension for you to use).

The first thing to do is to enter the name of the extension. This should be descriptive of what the extension is about (clinFHIR will use that to create an id for the extension). For example we used ‘nziwi’. When you tab or click out of the field, clinFHIR will query the server to determine if there is already an extension with that id in the registry. If there isn’t then ‘save’ buttons will appear at the top and bottom of the form. If there is, then you will get a warning that you are going to replace an existing extension and have the opportunity to change the name and id.

This does bring up an interesting topic about governance of these definitions – we’ll touch on that later. For now, just be sure to choose a name that hasn’t been used before.

Enter a more complete description in the next field (this is mandatory) but you may as well leave the other fields in the first column as they are.

Next up is the datatype. This is a coded extension, so the datatype we want is CodeableConcept. Drop down the selection box in the upper right  and select CodeableConcept from the list. When you do so, 2 new fields appear – Binding and Binding strength.

Binding is the term used to describe the association between a property in the resource (including an extension) and the ValueSet that contains the set of values – there’s a section in the spec that discusses terminologies that is worth reviewing.

Click on the link ‘Find ValueSet’. This brings up the ValueSet explorer which allows you to select a ValueSet, and also to browse its contents. (This explorer is the same one used in the resource builder). The ‘search’ tab should be displayed.

In the ‘name’ field enter ‘iwi’ and click ‘search’. After a short delay (while clinFHIR queries the registry) you will get a list of matching ValueSets – hopefully the ValueSet we created last time will be in that list. Click to select it. There are tabs that allow you to examine the ValueSet – when you’ve had a good look around, click the Select button to confirm that this is the ValueSet you want and return to the extension definition screen.

You can change the Binding Strength if you want to, and/or select Patient as the resource type (if you leave resource type blank then that means that the extension can be applied to any resource).

When done click the Save button. clinFHIR will save the resource to the registry and return to the profile screen.

Back in the profile builder main screen, a summary of the extension definition is displayed in the right column, with a button below it that says something like “Add to profile at path: Patient”. Click this button, and you’ll see the extension added to the list of elements on the left side. Note that if you don’t click this button, the extension definition will have been created, but not added to the profile.

(Note that the above process created and saved an extension definition for iwi. Once created it can be re-used any time it makes sense – for example if you create another Patient profile, you can just find this extension definition rather than re-creating it. New Zealand Iwi may not be all that re-usable, but you get the idea).

Here’s a screenshot of the completed profile. The Patient.identifier path has been clicked so you can see how the system has been selected.

So that completes the profile – click the ‘Save’ button to the upper right which will bring up a dialog where you can set the name of the profile and/or view the contents. As you did for the extension definition, set the name and then tab out of the field so clinFHIR can see if you are about to overwrite an existing profile.

You have just created the profile!

Now, this might all look complicated, but you need to remember that all of this is about making our changes discoverable, understandable and computable – so therefore interoperable. And, really, when you understand what is the purpose of each part and how they relate to each other, then it’s really quite straightforward.

It’s also worth pointing out that FHIR itself is build on the same framework as we’ve described here – truly an example of eating your own dog food

In the next post we’ll look at creating conformant resources, and talk a bit about what a ‘conformant resource’ actually means.

The last thing to mention is governance. As you can see, it’s really easy to create the FHIR artifacts needed for profiling – and really easy to obliterate resources that have the same name. This can, of course, have potentially disastrous consequences and so a good governance framework – and a robust registry – is going to be essential when using profiling in the real world. A topic for another time!