clinFHIR and the CodeSystem resource (STU-3)

As you’ll probably be aware, a lot of my focus in recent months has been in updating clinFHIR to help non-technical folk like clinicians understand what FHIR is, and how they can get involved in FHIR related projects. Here’s a White Paper I did for Orion Health on the subject…

There are a couple of core components that have been developed to assist this.

The Scenario Builder lets you create and link together resources that shows how FHIR can represent given clinical scenarios (There are often multiple ways 🙂 ). The idea is that you have a scenario (e.g.  representing a consultation) and you create resource instances that represent the various components of that scenario (such as an Encounter, a ClinialImpression, Observations, Conditions and so forth). The builder can show the linked resources in a variety of different formats, the most helpful being a ‘graph’ of interconnected resources like this:

The Logical Modeler allows you to, in effect, create your own resource types and then use them as the ‘template’ to build a resource in the Scenario builder (rather than the core resource definitions from the spec). The intention is to use the Logical models to define the extra elements needed (or remove those not needed) to support a specific scenario in a way that is quick and easy, and then once you’re sure that you have the bits you need, you can then use those models as the basic of generating the actual FHIR profiles – either automatically or manually using a tool like Forge.

So I can imagine a process like:

1. Gather requirements
2. Create Logical Model/s (based on a Core resource type)
3. Use them in Scenario Builder to build resource instances to test against real scenarios. You can combine logical models and Core resource types in the same scenario of course.
4. Repeat 2 & 3 as required (perhaps clarifying requirements as you go)

When completed, use as the basis for generating the real FHIR artifacts.

But one thing that is missing from this is the ability to create ‘example’ values for coded elements (such as a diagnosis or an observation), and when working with clinicians it’s actually quite important that the examples are as real as possible.

I did build a simple ValueSet editor (it’s still there) that allows you to create a ValueSet from SNOMED terms, but the problem is that it only really works with SNOMED – and navigating that terminology is not simple if you are unfamiliar with it, so I felt it may not be the best choice, especially when working in a ‘real-time’ analysis situation.

When I noted that the clever terminology folk have created a specific resource in STU-3 to represent an ‘ad-hoc’ CodeSystem, I realized that this could be an alternative way for a user to quickly create a set of example values to help define the purpose of a given element that was fully compliant with the FHIR infrastructure – so operations like ValueSet/{id}/$expand will still work – which is important in the scenario builder. I’m not suggesting that this is how you’d create the ‘real’ ValueSet, but it is a way to help understand and document requirements.

So the process becomes:

1. Gather requirements
2. Create Logical Model/s (based on a Core resource type)
3. Build CodeSystems (or ValueSets) to represent example values for coded data, and bind to the element in the Logical Modeler
4. Use in Scenario Builder to test against real scenarios
5. Repeat 2,3 & 4 as required – again validating requirements

When complete, use as the basis for generating the real FHIR artifacts.

Before we take a look at the clinFHIR CodeSystem builder, a reminder about the relationship between CodeSystem, ValueSet and the binding from the Element definition in the model. (We also talked about this just recently) Here’s the picture we use: (from the spec)

In summary we will:

• Create a CodeSystem that has all the example values we want
• Create a ValueSet that contains (or refers to) all of those values, which will be the ‘binding’ between the element definition and the CodeSystem
• In the Logical modeler, bind the coded value to the ValueSet
• When the profile generation is working, maybe generate the profile

So there’s 2 aspects to discuss – creating the CodeSystem and ValueSet resources, and then binding the ValueSet to the model. Let’s consider these in turn.

Creating the CodeSystem

Start clinFHIR and select the CodeSystem Builder.

Click the ‘new’ button in the top right hand corner. You’ll get a dialog where you can enter a name (with no spaces) and then click the ‘Check’ button to ensure it is unique on the Terminology server. The name will form part of the url for the CodeSystem according to the pattern: [server]/CodeSystem/[name], and the builder will also automatically create the matching ValueSet with a url of [server]/ValueSet/[name]-cf-vs that include the entire CodeSystem

Enter a title (short sentence) and a description then click save. You’ll get a screen like this:

You can now enter the values you want in the ‘contents’ pane to the right. For each value (technically we call this a concept) you enter:

• Display (required) – what shows to the user
• Code (required) – that actual code that is stored. Must be unique in the CodeSystem.
• Definition (optional) – a more detailed description of the concept.

You can re-order concepts using the arrow buttons. The order doesn’t matter in FHIR, but can make a difference for humans!

At the top right is a Save button which will save both CodeSystem & ValueSet to the Terminology server. It appears when you make changes.

Here’s an example with some (sort of) real data in it:

And that’s it! There’s also an option to load existing CodeSystems (It is quite interesting to see what has been defined in the spec), and to edit CodeSystems that were created by clinFHIR.

Binding the ValueSet to an element in the Logical Modeler

Start clinFHIR and select the Logical Modeler.

Create or select a Logical Model.

Enter a new element (or edit an existing) and set the datatype to CodeableConcept. Just under the datatype will be a link labelled ‘Select from Server’. Click this to select the ValueSet to bind.

Here’s an image of the element edit screen:

And here’s the ValueSet selector:

The ‘Expand’ tab will display all the contents of the ValueSet (In this case it will pull in the values from the CodeSystem).

Select and save, and you’re done.

So there you go – a simple way to create example lists for coded data. Note that there’s nothing stopping you creating ValueSets directly – this is just a quick way to keep an analysis going.

Note that the CodeSystem is new in STU-3. I will modify the builder to be able to create STU-2 ValueSets as well (In STU-2 the concepts are inside the ValueSet rather than being in a separate resource), but haven’t figured out the best way to do that just yet….