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!

To start, load clinFHIR, set the servers to public HAPI-3 and select the Scenario Builder. Create a scenario in the usual way (remember that adding the patient first is always a good idea as the subsequent resources will be connected automatically) and then add a Composition resource. This will automatically invoke the Document functionality – and you’ll notice a new tab appearing in the middle pane.

Here’s a screenshot with just a Composition and a Patient resource. Note the Document tab in the middle pane (next to the Graph).


Next, carry on adding resources as you normally would – linking them up as required. The example we’re going to work with is the report of an Adverse Drug Reaction (ADR) scenario that we talked about in an earlier post. One of the elements to be collected is the patients current medications, so add a couple of MedicationStatements plus a List and link them up – like this:



(Remember the ‘quirk’ in clinFHIR when adding multiple references to a List. You add the first one by selecting List.entry.item and the resource to link using the plus (+) icon, then select another resource in the graph, back to the List.entry.item again and click the Add Branch link to add a new branch. I really must fix this.)

Now we need to connect the List to Composition.section.entry. You don’t do this in the same way as the other references (you’ll get a warning if you try) – instead you use the functionality in the document tab, so let’s take a look at that. There are 4 subtabs off the Document tab:

  • Sections: allows you to add new sections to the Composition
  • Generated Text: Uses the document rendering rules in FHIR to generated the human readable text from the contents of the document.
  • Document Bundle: the bundle that holds the contents of the document – the composition and all the references resources
  • Tree view: A depiction of the ‘hierarchical’ structure of the document.

To add a new section to the document, click the ‘Add Section’ link that is on the Sections tab. In the dialog that is displayed, select the code for the section (It’s a LOINC code defined in the SectionCodes ValueSet) and a title and save the section. You’ll now get a display like the one below, that has the section on the left side, and resources on the right. The right hand column shows resources that are attached to the section at the top, and resources that are not at the bottom. You move resources from the bottom to the top (thus adding them to the section) by clicking on the plus (+) button. In the screenshot below, I’ve added the list to the section.


If you take a look at the Graph tab, you’ll see that there is now a reference from the Composition to the List resource. (It often helps to hide the Patient resource in the graph view – most resources have a reference to patient, and it clutters the display).

And that’s really all you need to do. There are options to reorder and remove sections, and to reorder/remove resources in a section. The various displays will update themselves as you do. One of the more useful views is the tree view – here’s a screenshot of a more complex one (Actually, it’s the Adverse Drug Reaction report that we mentioned above.)


(At the time of writing this, you need to click the ‘Generate tree’ link to actually create the tree – and to update it – I’ll make that automatic shortly).

Note how it shows the ‘hierarchical’ layout of the document (order matters in a document!) Clicking on a resource in the tree will display the details of that resource to the right – it’s handy to select the view you want, then select various resources to see the content. Note also that this view is read only, and shows only the resources directly connected to the Composition.section – and to any attached Lists – and doesn’t show all the references Use the Graph view to see those (and remember to hide the patient to get a better view of the layout – here’s an example.


In summary – the ‘Document Builder’ functionality is a great way to visualize how Documents work in FHIR. It’s kind of fun to take an existing scenario by just adding a Composition resource, and setting the section references!

I think it’s also going to be very useful when developing profiles on documents – as the ADR report is. More on that to come.

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: