Creating a simple scenario

This page describes how to create a simple scenario in the clinFHIR Scenario Builder – in this case a Problem List. This could be a ‘stand alone’ scenario, or part of a more complex scenario – such as a Discharge Summary.

Start by loading clinFHIR  and make sure that the servers are set to the ones you want –  the public HAPI 3 server is a good default. Select the ‘Scenario Builder’ from the launch menu, and the main screen will be displayed. Here’s a screen shot:

Some notes before we start.

• A ‘scenario’ represents some clinical ‘thing’ that you want to represent – in this case a Problem List, but it could be a consultation, a Discharge Summary or an Adverse Reaction report
• The scenario we build is saved on the local computer (actually in the browser you use). It is possible to ‘upload’ it to a server – or to download the resources from a server – though we won’t discuss that here.
• In this post we’ll just add the basic resource – we’ll describe adding structured data in a separate post.

So the first thing is to create a new scenario – by clicking the ‘new scenario’ link to the upper left. You enter the following details:

• Name
• Description
• Category (leave as ‘default’)

After saving, the main screen is agains displayed, with the new scenario selected. (It’s currently empty of course).

Looking at the screen shot above, you can see that the builder is divided into 3 ‘panes.

• The left pane lists all the scenarios in this browser. You can hide it (getting more space for the other 2 panes) by clicking the ‘hide selector’ link in the nav bar at the top. This is where you select the scenario you wish to work with.
• The middle pane has a number of tabs.
  • The List tab has a list of the resources in the scenario. You can select a resource for editing (opens in the right pane)
  • The Description tab which has the description of the scenario.
  • The Graph tab which displays all the resources in the scenario, and the references between them (This is the most useful display, and the one you want to have open most often).
  • The FHIRPath tab. This lets you examine the internals of a resource – or all the resources in the bundle. We won’t do that here, but here is a post with more detail if you are interested.
  • The Mark tab. This is intended for automatic grading of scenarios, and won’t be used here
  • There’s also a Document tab that appears when a Composition resource is added to the scenario. This is the subject of a separate post.
• The right tab has the details of the selected resource (and is only shown when a resource is selected), allowing you to view and to edit it. It also has a number of tabs
  • Structure & Reference
  • Current resource views
  • Changes

The overall process to build the scenario is as follows

1. Start with an idea of the resources you’re going to need – and the references between them. You can either do this ‘on the fly’ – or using a ‘Resource Model’ for more complex scenarios.
2. Select a ‘type’ for each resource (starting with the Patient). We’ll describe what we mean by that in a moment.
3. As we add each resource, include some text that describes it. We’ll talk about adding structured data in a separate page
4. Create the references between the resources

and that’s it!

So for the Problem List we’re going to need:

• A Patient resource
• A List resource – which will have a reference to the Patient and to the Condition resource
• A Condition resource for each problem which will have a reference to the Patient (and from the List)

To actually add a new resource, click the blue ‘Add resource’ at the top right of the middle pane. On the right pane, another tab panel appears with 4 tabs. The one we want is already selected – the Core resource types. These are the resources defined in the FHIR specification, and you can think of them as if they were ‘templates’ for creating a ‘real’ resource. (Technically, we refer to these as ‘types’ and ‘instances’ respectively). From the drop-down that is displayed, select the ‘Patient’ type. Here’s a screen shot after the Patient resource type has been selected:

In the text box, enter the patients name and then click the green ‘Add’ button. Select the Graph tab in the middle pane. You’ll see a single light green square labelled ‘Patient’ with the name below that. Repeat this process, selecting a List resource and 2 (or more Condition) resources. Remember to add a short descriptive text for each one.

Here’s a screen shot of the graph view of the Problem list I created.

Note that the references to the Patient resource were automatically created by the Builder (which is why we added that one first). If you add the Patient after the others you can still establish the connection manually, using the process described next.

Now we need to connect the List resource to the Condition resources. To do that, select the List resource in the graph. The details of this resource are shown in the right tab (just like the Condition is shown in the screenshot above).

From the specification  we can see that the connection from the List to the Condition is from the ‘entry’ element of the list, from an element called ‘item’. We can refer directly to this element (we call it the path to the element) using ‘dotted’ notation – so this element is referred to as ‘Condition.entry.item‘

You can see that the List resource in the right pane is represented as a tree. Expand the entry node (by clicking on the + icon) and then click the item node. To the immediate right of the tree is quite a lot of detail about this element. Here’s a picture:

Looking at the details of the List in the right pane, we see:

• In a shaded box at the top is the full path to the selected element – List.entry.item
• Next is a section about branches – currently empty, but we’ll come back to that in a minute
• Then the list of datatypes for this element – for this path it’s only a reference
• Finally, a table headed ‘Potential References’.

This detail will be shown whenever an element is selected, and the content is specific to that  element.

Creating the reference is simple. Just click on the + symbol to the right of the resource  (one of the Conditions) in the ‘Potential References’ table (and you can see why you need to add text to each reference). The graph is updated immediately (It’s kind of fun to see this happening!)

But there’s a catch – if you select another Condition resource, it simply replaces the connection you just created. How to create the others? This is quite simple, but there is a trick to it. First, select any other resource in the graph. Then, reselect the List resource and the List.entry.item element as we’ve just done. Note that just under the path banner, there is now a box with a ‘1’ in it. In other words, there is a single ‘branch’ from List.entry.item that references the Condition resource. To create another branch (to refer to the second Condition) click the ‘Add Branch’ link to the right. Immediately, another box appears to the right of the ‘1’ which has – unsurprisingly – a ‘2’ in it. You have created a second branch, and can now click the + to the right of the second Condition resource in the ‘potential references’ table to add the reference to the List. Here’s a screen dump:

This process can be repeated any number of times, adding branches as required. The ‘trick’ is that after creating the first reference you have to ‘click away’ from the List to be able to add subsequent branches.

To remove a reference, you need to edit the ‘source’ resource in the ‘Current Resource views tab’. When you select a top level node in the tree view of the resource instance (not the same as the resource type of course), a delete button appears that will remove that node. In the case of the List, it will remove all the references so you can start again. Here’s a screen dump.

Note that you don’t need to save changes – this happens automatically.

So that’s how to create a simple scenario. However, we haven’t added any structured data. In the next page we’ll show how to do that.