Creating a resources model

This is the third post in a mini series on using the Logical modeler. In the first post we talked in generalities of models (admitting that this is very much a work in progress), and then we discussed the Information Model – a model that is used to capture clinical requirements for information exchange. Now, it’s time to think about how we can design real FHIR artifacts from the work so far.

The example we’ve been using is data collection for adverse events, and we’re previously decided to model this as a FHIR Document, which is simply a Composition resource (representing the header information) and any number of other resources representing the specific parts of the document (subject, author, sections etc) all contained in a Bundle (and all referenced by the Composition).

To continue with our analysis, we’re going to create a multi resource model – a model that represents all the resources that will be part of the Document. The value of doing this is that it will identify the resources we need (and the profiles, extension definitions and ValueSets) yet still be understandable to the clinician. A FHIR expert can then take this model and create the specific artifacts required, and the ImplementationGuide to pull them all together.

Creating the model is pretty much the same as when we created the Information model – with a few key differences.

When you create the model, choose Composition as the base resource type – and check the ‘copy elements into model’ checkbox before creating the model. This will create a model that is a duplicate of the Composition resource – and will also populate the ‘FHIR mapping’ for each element.

When you add a new element, you have to specify the mapping of that element. Let’s talk through some examples.

First create the model.

1 new rm

Here’s what it looks like after saving and removing some of the elements that we don’t need:

2 edited rm

You’ll see that I’ve removed the sections element as well. Don’t worry, all will be explained soon…

So let’s start adding some details. We want to be able to specify that we want the subject to be a patient, and that (at least) the name, date of Birth, gender and ethnicity are present.

What we’ll do is to change the subject to be a reference to a Patient resource, and to add those 4 elements as child elements.

Select the subject element, click the ‘edit’ link, and change the properties as shown in this screen shot:

3 patient

What we’ve done is to make this a reference to a Patient resource. Note that the FHIR mapping is still ‘Composition.subject’ – that’s the source of the reference. (actually, we could also just delete ‘subject’ and add a new element called ‘patient’ – provided we set the mapping correctly it would have the same result).

Save the element, returning you to the model. Now, making sure that the patient is selected, click the ‘Add Element’ link. We’ll start by adding an element that we know exists in Patient – the patient name. One option is to enter the element name, data type and mapping, but there’s a short cut. Select the FHIR mapping textbox and start to enter ‘name’. Here is what you will see:

4 patient name

Notice how the dropdown list is automatically pre-populated with matching element names from the Patient resource. It was able to do this because the parent element is a reference to a Patient resource, so the tool could load the StructureDefinition for patient and perform the filtering. But wait, there’s more!

Select ‘’ from the list. Note that the Item name and data type are automatically set to the correct values. Now, you can save the element, and you will be returned to the model with the element added.

There are a few caveats:

  • This only works if you haven’t already entered a name or selected a datatype (by design, it won’t over-write what you enter)
  • Elements that are ‘choice’ types (ie can have more than one datatype) will be automatically expanded in the mapping list – you will need to select the specific datatype you want.
  • This trick won’t work for extensions (after all, how can it know?). Instead, you still set the mapping to Extension, but need to set the datatype and name manually. You should also enter the url of the extension, once it has been created.

Complex extensions are not handled particularly well at the moment. I think the strategy is going to be to add the extension url as a BackBone element, and the individual elements within that extension as child elements of that parent. Right now you have to set that up manually – here’s an example using the US Core race extension

5 complex extension

Note how the mapping has been done (this won’t autopopulate). What would be nice would be to select the extension definition, and then have the model automatically updated. Shouldn’t be too hard….  Still not sure it’s the best way to do this though.

While we’re on the subject of the table view, note how this view shows both path and datatype in the second column. This is a great way to quickly review a model for completeness.

I should also point out that the tool will only allow a single datatype for each element. If there are situations where there could be more than one (eg an could be a Patient or a Practitioner) then you’ll need to create 2 elements (authorIfPatient and authorIfClinician). I’m not sure that this is necessarily a bad thing – it does make it explicit what’s happening, and the child elements would be different, so I’m inclined to leave it that way for now. (plus, it’s really hard to fix 🙂 )

You’ll recall that we removed the Composition.section elements when we created the model. This is because we want to create a separate element for each section (and set the path to Composition.section). Let’s take the Problem List. What we want is for the Composition.section to reference a List resource, and for the List resource to reference the Conditions. In that way, we can be explicit if the List is empty (using List.emptyReason). We created it in the same way as we did for the Patient (and that autocomplete trick really helps), here’s what it looks like in the Designer view:

6 PL1.png

And the mindmap is helpful here too:

7 PL2.png

Actually, reviewing the Composition resource, I note that there is a section.emptyReason, so the argument to include the List may not be valid. Nevertheless, it is a good example of how you can ‘nest’ these references if needed.

So that’s probably enough for now: hopefully it all makes sense, and is useful! Next up, we’ll start to think about how we can test all this in a connectathon (like the INTEROPen one we’re doing in London in a couple of weeks) – but my flight is about to leave, so it will have to wait!

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.

Leave a Reply

%d bloggers like this: