Participating in a Clinical Connectathon

In this page we’ll describe how to participate in a Clinical Connectathon. We’ll assume that the event has been previously set up with Tracks and Scenarios, that the organizer has given you the url to the event (they are different for every event), and you know the name of the Track you wish to participate in. (If you’re interested, there are a few pages that describe this setup process:  <<add here>>

So the first thing to do is to log into the event. Navigate to the Url you were given, and you should see a login screen. If this is your first time, click the ‘Register new Person’ link, and enter the requested details. You only need to do this once – the browser will remember the details after this.

You’ll get a screen that looks like this, with all the tracks in the event listed on the left.

Select the track you want (in the example above this was the Problem List), and you should see a number of new tabs appear along the top:

• Scenario Builder (Where you will actually construct the FHIR resources that represent the scenarios – we call them ‘Graphs’)
• Summary of Scenarios. This displays all the graphs that people have entered against each scenario in the track, along with any notes they have made. This is where to go to see what others have been doing!
• All scenario Notes. Displays all the notes across all tracks and scenarios.

Before continuing, lets step back and think about why we’re doing this. Generally there are 2 main reasons.

• Education. This is for people new to FHIR who want to learn how to add data to resources (or profiled resources) and to link them together to represent a clinical story
• Design. This is for the advanced user (generally members of the HL7 committees) who are determining if the resource structure is correct, or needs to be altered in the next version of FHIR.

We’ll focus more on the first type of user in this page – we’ll have another page for the designers.

With that out of the way, let’s build a Graph!

Select the ‘Resource Builder’ tab, then select one of the scenarios from the dropdown to the upper left. You’ll see a screen like the one below. This is your main work area.

There are 3 main panes in this screen.

• Along the top is where you select the scenario (as you’ve just done) and the resources that you want to add to your graph. Some of the scenario details are shown here – but there’s an ‘eye’ icon above the description that will show all the scenario details.
• To the lower left is a series of tabs – List, Graph, Notes and Server interaction. After you have  added resources to your graph (more on that in a moment) you can interact with them here. Selecting them, viewing the overall graph, editing references, saving them to the server and so forth.
• To the lower right (which will be blank initially) is the actual editor pane. Here is where you can add data to resources, and connect them together. The editor pane also has places where you can make any notes about the resources as you build the graph. This is really useful information for the designers. (We won’t describe this in this page – but there is an ‘advanced’ page that does so)

You start by selecting the resources you need for your graph. This can be done at any time, but we’ll add them at the beginning. The example scenario we’ll use is to represent a patients Problem List. They have 2 problems – Asthma and Diabetes.

The selection area is at the right of the top pane. When the scenario designer built the scenario, they will (or should) have listed the resources that you will need to build the graph, so you can add an instance of the scenario simply by clicking on its name. You enter a short description of the resource (a few words only), and it will be added to the list in the left pane. Note that you are able to add any resource type even it it wasn’t added by the designer by clicking the ‘>Select Direct<‘ link alongside the resource names. In this example, select a Patient, a List and 2 Conditions – giving them short titles. (These are especially useful in the Graph view).

To actually add data to a resource instance select it in the left list, and after a short delay (while the tool looks up the details of that resource type) a form will appear to the right. Here’s an example of a patient:

You’ll note that there are 3 tabs in the right pane.

• Table. This is a table (kind of like a form) that was automatically generated from the description of the resource type, and has links where you enter sample data (and other stuff as we shall see). We’ll focus on this form in this page.
• Tree. This is also generated from the resource type description, but shows the elements in the resource in a hierarchical tree rather than a form (just as the clinFHIR Resource Builder does). It’s just a different representation – you can use either format – or switch between them as you want to.
• Resource Instance. This shows what the resource looks like ‘on the wire’ – ie the actual form that is exchanged between systems.

Take a closer look at the table. You will see that it has a number of rows (one for each element in the resource), and each row has a number of columns.

• The first column is a ‘control’ column. If a row has ‘child’ elements (like Patient.contact), then the child elements are initially hidden, and there is a ‘>’ symbol that will display the children when clicked (and changes to a down arrow symbol that will hide them again).
• The next column has the name of the row, and a ‘mouse over’ that will display a more complete description of the element. If the element can appear more than once (like identifier), then there is a plus (‘+’) symbol to the right of the column that will add another copy of this row (and any children) when clicked.
• The third column has the cardinality – the number of times that this element can appear in a resource.
• The fourth column lists all the datatypes that values for this element can contain. If there is more than one, then they will be represented as a set of radio  buttons. There is an edit icon to the right of the column that will show the data entry dialog when clicked.
• The last column (at the moment) is generally read-only, and shows the value that has been entered for that element.

To add data for an element, simply click on the edit icon in the fourth column (selecting the datatype first if necessary). You will see a dialog box into which the value of the element can be entered. The actual format of the dialog will vary according to the datatype, and hopefully should be self explanatory. Here’s an address:

 

Coded data is a bit different – here you enter a search string, and select the value from matching concepts served up by the Terminology server. Here’s an example for asthma, showing a number of matches. The next step would be to select the actual concept.

The last thing that we’ll cover off in this introduction is how to connect resources together – called references between resources. References are always directional – from the source to the target. Let’s create a reference from a Condition to the Patient who is the subject of the Condition. As you do this, it pays to display the graph view in the left – that way you can see the references as they are created.

First, select the Condition (note that we scrolled the table to get the subject into view).

Take a look at the subject field in the form and note that there are 2 entries in the fourth column – arrows pointing to ‘Patient’ and ‘Group’. To create the reference, simply click on the type of resource that you want to refer to. A reference is created according to the following rules:

1. If there is a single instance of that resource type, then a reference to it is immediately created.
2. If there are no instance of that type, then one will be created and a reference to it created
3. If there is more than one potential match, then a dialog with the matching resource is displayed, and you select the one you want.

If you do link to the wrong resource – or change your mind – then references can be deleted from the list to the left.

So that’s a quick run through of the new Scenario Builder in action. And here’s a graph of the final result:

(and just a final note about the List references to the Conditions – I used the ‘duplicate’ plus (‘+’) symbol against the entry element to set these – you can see that there are 2 entry elements in the image above.