FHIR Documents (and other stuff)

I had an email from a company which had a number of really good questions about exposing data through FHIR, so I thought I’d write a post about it rather than just replying directly as it may be of interest to others (and also gives others the opportunity to disagree with me 🙂 )

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!



Creating documents in clinFHIR 

I did a demo of clinFHIR for the Clinicians on FHIR group that will be meeting at the Working Group Meeting next week, and completely forgot to talk about creating/viewing documents in clinFHIR using the scenario builder. This is functionality that has been around for a while, and allows you to create a FHIR document by adding a Composition resource to the scenario, and then linking up the other resource to it.

So I thought I’d do a post on it!

Read more of this post

Scenario Builder: Library and Documents

In the last post we talked about the new builder component that was developed to help people (especially clinicians) develop sets of resources to represent clinical scenarios. There are a couple of features we didn’t have time to discuss then – the Library and Documents – so let’s talk about them now.

Read more of this post

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.

Read more of this post

Updating a resource using patch

We’ve received a bit of pushback from the community regarding our proposal to use custom operations for updating the Patient in NHI upgrade project. But the development team really isn’t keen on using PUT updates of the complete resource – the main reason being that of ‘accidental’ data changes when the updater doesn’t return the parts of the resource that should remain unaltered. (Apparently, this is not uncommon with messaging based updates that are kind of similar).

I mentioned in that post that we didn’t really take a close look at PATCH updates – but a couple of days ago I saw this trail in the FHIR chat which is about a similar project (slightly different requirements) and thought I really should take a closer look at PATCH.

Read more of this post

Clinicians on FHIR workshop

This set of pages is in support of a number of workshops about FHIR that are targeted specifically at Clinicians and Business Analysts. The intention is that we will build a ‘standard guide’ for a 1 – 2 day workshop that can be given by people familiar with FHIR, and with a clinical expert to help drive model development.

The overall programme of the workshop is:

  1. Describe the clinical problem. The example we will use in this set of pages is a Discharge Summary Document. From this we select a single ‘item’ or ‘artifact’ of information to model. In the case of the Discharge Summary then it is the document itself, but for more complex problems there may be a number of different possibilities.
  2. Next we build an ‘Information Model’  that represents the information in the artifact that we want to share. Although this uses the FHIR infrastructure (the dataTypes and modelling tools), the model is not constrained to any of the standard FHIR resource types. Other than how to use the modelling tool (which is the clinFHIR Logical Modeller), no FHIR knowledge is required – indeed the purpose is to allow a clinician to document the information requirements in a semi structured fashion so that the correct FHIR artifacts can be created.
  3. The next stage is to take the information model, and produce a ‘Resources model’ and a ‘References Graph’. The purpose of this step is to identify the ‘real’ FHIR resources that will be required (if more than one) plus the constraints and any extra elements (which will be extensions) that are required.  There are actually 2 parts for this stage, each using a different component of clinFHIR.
    • Using the Logical modeler, create a model where the main nodes represent a FHIR resource, with child nodes for extensions or details/constraints on existing elements. Ultimately, the intention is to be able to map this back to the information model so we have traceability to ensure that all the elements from the information model (representing clinician requirements) are represented in a FHIR resource / profile. FHIR knowledge is required for this step.
    • Using the Scenario Builder, construct a diagram of the resources and their relationships. This provides a more visual representation of the resources and their interrelationships. It also allows for sample data to be entered, which is helpful as a ‘cross check’ that all required data elements have been identified, and the datatypes are correct. Only minimum FHIR knowledge is needed – this is almost a clinical QA step against the resource model.
  4. Finally, all the required FHIR artifacts can be identified and built. This definitely requires FHIR knowledge. The artifacts are packaged into an ‘Implementation Guide’ and consist of:
    • Profiles on resources (extensions and constraints)
    • ValueSets and CodeSystem resources
    • Examples
    • Documentation
    • Plus a number of other potential resources.

In practice, any real profile development won’t be as linear as this, and there will doubtless be multiple iterations but this approach should allow all those involved in the development to understand all the steps, and the artifacts that are produced.

Here are the links to the specific pages:

Building the information model

Building the resource model

Building the scenario

Add structured data to a resource

Create a Document from a scenario

Building the ValueSets & Extension Definitions

Building the profiles

Building the Implementation Guide


FHIR Bundle Visualizer

So a little while back I wrote about an app I developed during the WGM Connectathon to send an HL7 v2 message to a converter app, and display the response (a FHIR Bundle) in a number of visualizations after validating it using the community supplied validation tool (actually, exposed by the reference servers via the $validate operation). It occurred to me that this visualization might be of use to implementers who are developing query applications – such as the CSIRO Primary Care project for example, so I pulled it out into a separate application.

Read more of this post

Creating models with the Logical Modeler

It’s been a while since we talked about the clinFHIR Logical Modeler, and I’ve had a few questions about it, so I thought an update might be in order.

The term ‘Logical Model’ can be used in different ways (much like ‘Profile’) so let’s first define just what we are talking about. Basically, it’s just a hierarchical model of data – much like you see in any of the core FHIR resource types – with the exception that the model does not have to align with any of the core types. Other than the requirement that you must use the FHIR datatypes, there are no limits on the complexity of the model you create (though overly complex models can be hard to understand – or use).

In this post we’ll talk about the general aspects of using the modeler – subsequent posts will go into more detail about how to build them.

Read more of this post

Creating an Information Model

This page describes how to build an Information model using the Logical Modeller component of clinFHIR.

We can use the Logical Modeller for creating a couple of different types on models (they are called ‘Logical’ because they don’t have to align with the predefined resource types defined by FHIR (like Patient or Condition), even though they utilize the same infrastructure.

  • An ‘Information Model’ describes the actual data items that are intended to be included when sharing clinical data. It is intended to allow a clinician (or a Business Analyst) to document these requirements without thinking about how it will be represented in ‘real’ FHIR resources. Very little FHIR knowledge is required – if any. It’s the FHIR equivalent of modeling in openEHR or CIMI
  • A ‘Resources Model’ takes the Information Model and ‘divides it up’ into the actual FHIR resources (including extensions) that will be required to represent the data in the Information Model. This needs a good understanding of FHIR, but the resultant model should be understandable by the clinician. Most of the time a Resources Model will represent multiple resources – though it is possible to create one for a single resource only.

The remainder of this pages focuses on the mechanics of using the Logical Modeler to create an Information Model. There’s a separate page the describes the specifics of creating a Resources model.

The model itself is a hierarchical tree, with parent nodes containing child elements. Although there is no limit to the depth of the model, you probably want to stick to around 3 levels, unless there is a particular reason to do so.

The example we’re going to use is a Discharge Summary – which is a kind of document.

The following is a high-level break-down of our document (Note that this is just one way to represent this – there are many others! And, indeed, this is the whole point of this process – to be able to represent these opinions in a way that others can readily understand – even if they don’t agree with them).

  • A node that has information about the document – the type of document, date it was created, the author and so forth
  • A node that represents the admission details. The hospital, the specialty under which the patient was admitted, admission dates , reason for admission and so forth.
  • A node that represents information about the patient when they were admitted. Co-morbidities (problems that might have contributed to the admission), current medications, allergies, social circumstances
  • A node that represents clinical details about the stay – key observations, tests performed, procedures performed
  • And finally a node for discharge information – medications on discharge, updated allergy list, follow up instructions.

Each of these nodes will have ‘child’ nodes with further information – sometimes with child nodes of their own. For example the discharge node will have a node for medications which, in turn, has the individual medications below it. (There’s a picture of this lower down this page)

And note also that our information model will be at a certain level of specificity. We may be wanting to model a ‘general’ Discharge Summary template for use in any department – or we may want to model a Discharge Summary from a Cardiology ward. The nodes we include, and the details of those nodes will vary – for example in this case we may always want to have a medications on discharge node, even if it is empty, whereas for a Surgical discharge this may be optionally present. The model allows up to be explicit about this.

With that out of the way, let’s create the model.

Start clinFHIR, and check that the servers are set correctly – the HAPI-3 server is a good choice. To create a Logical Model you need to log in to clinFHIR. The only reason for this is to record who has created a model (no spam, I promise) – click the login link at the top right. Enter your email and a password and you’re done. From the launcher, click the Logical Modeler link and the app will be displayed.

To create a new model, click the ‘New Model’ link (top left). The following dialog is displayed:

Enter a name and click the ‘Check’ button. Provided that the name has not already been used, a green ‘Save’ button appears to the upper right. Leave the ‘Model type’ as ‘multiple resources, and enter a title, publisher and purpose in the appropriate fields. Then click the Save button.

The screen that is displayed is divided into 3 panes:

The left pane is a list of models – either in your palette (empty right now) or all on the server. It can be hidden using the ‘Hide Selector’ link in the navbar to give more space.

The middle pane is the main editing area. It has a number of tabs:

  • The Designer ie where you can add and remove fields from the model
  • The Mind Map shows the elements in the model as a mind map
  • Table presents a tabular view of the model
  • Mapping summarises the mappings between this model and another
  • Coded displays all the coded elements (those with a datatype of code, Coding or CodeableConcept and the bound ValueSet (if given)
  • References displays the elements that are references to other resources
  • Doc shows the generated documentation
  • Dev are a number of views for the developer.

We will only use the designer in this example

The right pane also has a number of tabs.

  • Element shows details of the currently selected element
  • Model shows details of the model as a whole
  • The other tab can be ignored.


To add a new element, select the parent element in the designer (eg the root of the model). The properties of this element appear in the right pane. At the bottom of the list of properties are a number of action links – the exact ones will change according to the selected element. If the root is selected, then the only option will be ‘Add Element’. Clicking that will show the following modal dialog where you can enter the details of the new element. Here’s a screenshot:


There are a number of fields you can enter:

  • The item name is the name displayed in the tree. Keep it short and descriptive. No spaces allowed
  • Short description expands on the name. It defaults to the item name.
  • Datatype of the element. If you are unsure, then leave it at the default of string but otherwise select the one most appropriate for the information you are wanting to capture for this element. Elements that are intended to have children are often modelled as ‘Backbone Elements’. If the element is coded in some way (eg a patients gender or a type of document), then set it to CodeableConcept. That way, the FHIR designer knows that a ValueSet (list of possible values) will need to be determined.
  • A more detailed description of this element. Pays to be reasonable detailed here.
  • Multiplicity – how many times this element can appear in an instance of this model (eg a particular Discharge summary. The first number is the minumim, the second the maximum – eg 1..1 means that there must be 1 present – it is required, whereas 0..* means it’s optional, but there can be many of them.
  • Comments are any further comments – not often used
  • Fixed value is if there is a specific value that this element should always have. Commonly used with identifiers to specify that an Identifier must come from a given system such as a national identifier.
  • Mapping path and notes is how we relate (or map) this elements to others (This is not the same as a reference). You won’t generally use this field in an information model.

Once you have entered the details, click the Save button. The designer is re-displayed with the new element added.

And that’s really the main stuff you need to know. Just repeat the steps above to add the elements to your model. Remember to click the ‘Save Model’ button to the upper right to actually save the model on the server.

As you select elements in the designer, the right pane will show the key details of this element, and the ‘actions’ will allow you to modify the model:

  • Add new elements as children to the currently selected one
  • Edit an element
  • Remove it
  • Copy it
  • Move it up and down (but always under its parent)

(Ignore the ‘discriminator’ option).

Here’s a model with some of the fields added:

and here’s the tabular view:

There really aren’t any ‘rules’ for how the model should be laid out – it’s really all about capturing the information required in some kind of order that makes sense. It’s possible to get inspiration from other modelling tools like openEHR, or if you do have some knowledge of FHIR  resources, to organize it by resource, but it’s important not to be constrained at this stage.

Make sure you make as many notes as needed in the comments field, and if something must be present then make it required (for example the model indicates that there should always be a medsOnAdmission section, even if there are no medications in it.

As noted above, if you do know that an element should be coded, then set the datatype to CodeableConcept. This makes it easy to identify where valueSets are needed. Here’s a screen dump:

In this model there are no ValueSet (we just identified the coded elements). But it’s quite feasible to specify the ValueSet in this model as well, if you know what it is…

And if you’re not sure what a datatype should be, either use a string or the closest option. This will be clarified as the models are refined (especially the resources model)

Just as a disclaimer – the terms ‘Information Model’ and ‘Resources Model’ are my own – I take full responsibility if they are not correct!

It’s likely that as FHIR matures, patterns of use will emerge, but right now the situation is evolving. Exciting times!