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.

When you develop a set of resources, they are saved in a bundle on your local computer (actually in the browser storage). The problem with this approach is that you have to use the same browser to edit them – and you cannot share them with others. To get around this, we have the concept of the Library of sets.

The idea is that you create and edit sets in your local browser, and periodically ‘publish’ them to a FHIR server (the library) from where they can be downloaded on to any browser and edited. This also means that others can view your work – it would be great to have a whole collection of ‘sample’ sets for people to download and examine – hence the idea of a library.

To access the Library, click on the ‘View Library’ link in the navbar – you’ll see a display similar to this:

To the left is a list of sets in the library – regardless of who published it. Selecting a set shows a summary of the set (name, description, author, resources in the set etc.) To download a set, click the download icon (a cloud with an arrow) and a copy will be downloaded to your local machine where it can be viewed and edited.

Technically, the set is stored as a bundle in the content property of a DocumentReference resource on the Data Server. (Right now the contents are stored inside the DocumentReference itself – later on we’ll likely move the content to a Binary resource and just reference them from the DocumentReference, as the current approach won’t scale well).

To add a set to the library, there’s a link in the navbar when a set is being edited that will copy the current set up to the library (creating a new version if there is one already there).

Right now, anyone can access and update the library – later on we’ll add a bit more security – and also tidy up the versioning and resource contention capabilities.

So now let’s talk about documents.

In FHIR, a document is just a bundle of resources with a special resource – the Composition resource – that has the information ‘about’ the document (analogous to the CDA header). There are a number of other rules about what’s in a document, how it should be rendered and so forth but fundamentally it’s just a Bundle of resources.

I’ve done a number of posts on documents – here’s a summary, though a bit out of date as it uses an Atom feed as the container rather than a Bundle, but the fundamentals are still correct. Refer to the spec for the most up to date details.

In the clinFHIR simple builder (I really need a better name ! ) adding a Composition resource to a set will automatically invoke the document features – represented as a new tab in the middle pane. Here’s a screen dump (the Composition resource has been selected which is why it’s detailed in the right hand pane):

To build a document, you add sections to the document (under the hood this will add Composition.section elements) and then add resources to the section (references from Composition.section to the resource).

To add a new section, click the Add button below the section list, then select the section code from the drop down list (the list contents come from the ValueSet defined in the spec of course).

Then, select the section in the middle pane and you’ll see 2 lists to the right of the section:

• Resources that are in the section (directly referenced by the section)
• Resources that could be added to the section – ie the others.

To add a resource to the section, click the plus (+) icon to the right of the resource display in the lower list (mousing over the resource will show the id and the complete text).

You can also re-order or remove the resources in the section using the arrow icons that appear when you mouse over the resource in the upper list. Similarly, you can re-order the sections themselves.

The graph view will be updated according the resources referenced by the section.entry elements.

The reason why you might want to re-order sections and resources is that the tool will automatically generate the document text for you – and will show that text in the ‘Generated text’ tab.

There’s a specific set of rules for rendering a FHIR document:

1. First the Composition narrative
2. Next the subject narrative
3. Finally the section.text narratives

The narrative for a resource is the textual representation of the resource. All resources can have a narrative (it’s the text element in the resource), and it’s up to the resource creator to decide what text should be in there. In this tool, the narrative for any resource is a combination of text directly entered by the user, and a textual representation of any structured data entered (which can be manually edited if necessary).

When generating text, the following rules are used:

• The composition narrative is rendered
• The subject narrative is rendered (generally this is a Patient, but any resource can be a subject)
• The narrative for each section  is created by iterating through each of the sections in order, and then each of the referenced resources (section.entry) in order.
  • If the referenced resource is a List resource, then the narrative is the narrative of the List resource, plus the narrative of all the resources that the List references
  • If the referenced resource is not a List, then the narrative is rendered

And here’s a rendered document:

So that’s the new builder tool. Feedback welcomed!