Creating sample data with GraphBuilder

One of the things I find myself doing quite often is helping people design FHIR API interfaces. Of course, the actual API itself is defined by the FHIR standard – but the parts that are implemented by any given system will vary tremendously – particularly with regard to API features like chaining, reverse chaining and the _include search parameter.

What I find very useful is to create a small set of sample data and save to a generic FHIR server (I use the HAPI server generally, though there are others available these days). Then, I can test out the API calls against that sample data set to make sure I have the syntax right – and they are returning the results I expect.

So, there are 2 parts to this – creating the sample set, and running the queries.

I generally use POSTMan to test out the queries – though clinFHIR has a server query app as well.

To create the sample set I use the clinFHIR GraphBuilder which has been designed for this very purpose! Well, it started out as an educational tool, but became more useful than that. The latest version uses an API supplied by the clever MITRE folk – essentially a service façade to the sushi application which implements the FSH Domain Specific language to produce FHIR artifacts.

Each resource in GraphBuilder has a FSH script associated with it which is then converted into a FHIR resource by the sushi API.

GraphBuilder is reasonably complicated (though straightforward when you’re used to it), and the overall process to create sample data is as follows.

1. Create a new project

 Load the app in your favourite browser (most modern ones should work – I use Chrome most of the time) and create a new Project by clicking the green ‘New Project’ button at the top of the screen. Into the dialog that appears, enter a description of what you’re trying to do.

You will want to set a server to save the resources to – there are a couple of pre-defined servers, but any server that implements the R4 API should work. Start with the public HAPI server if you are unsure.

You might also want to select the ‘multi-view’ option. This allows you to create different sets of sample data – useful when there is a lot of data to visualize.

Here’s a screen shot of the lab project:

Once that’s saved, the project is stored in the local browser cache and displayed on the screen, click on it to select it. The initial view (graph) will be displayed.

2. Add  Resources to the graph.

Using the green ‘Add a new resource instance’ button to the upper right, select resources to add to the graph. You select the resource type, add a display and text to it and then save it to the graph. It pays to add the Patient resource first, as the tool will autowire subsequent resources that have a ‘patient’ or ‘subject’ element.

You can add new resources any time.

One thing worth mentioning is that it’s a great idea to add an identiifer to the Patient to make it easier to find later – see step 4 below

3. Create the references between the elements

Next up is ‘wiring up’ the resources to each other using resource references. Each reference has a source and a target resource instance. To create a reference:

Select the source resource. The panel to the right shows the details of that resource at the top, and the potential target resources at the bottom. There are 2 kinds of reference – simple and backbone.

Potential simple references are shown on the first tab. Each line shows the element in the source, and matching resources from the view (based on the reference type). To add a reference, click the ‘Add reference’ link

Backbone references (ie where the reference is in a Backbone element) are in the second tab. Selecting that shows a list of the Backbone elements in the selected resource. Click the Add button and a dialog will appear showing the sub-elements within the backbone. You can enter any of the element values, including selecting the resource to reference.

Here’s the lab data graph:

4. Add resource contents.

Thus far the resources have only the references – no actual data. To add data, double click on the resource in the view to bring up the FSH editor dialog for that resource. Here’s an example:

The FSH editor allows you to enter the FSH text that defines the resource contents. As describe above, the Sushi API will then convert that into a ‘real’ FHIR resource (so the FSH is the ‘source of truth’ for the resource content – including the references). There are 2 ways to update the FSH.

To the left in the editor is a list of all the elements in the resource along with the datatype (a single element can have multiple possible datatypes). Clicking the datatype will call up another dialog where you can enter the specific value. If the datatype is coded (e.g. CodeableConcept) then it is possible to select the value from a terminology server – actually the Ontoserver terminology server from CSIRO.

The other way to add content is to type it directly into the text box to the right. Sometimes adding content through the list on the left can get confused and add invalid content, in which case you’ll need to manually correct it. Understanding FSH really pays off – and you only need to understand a small subset of the language.

Regardless of how content is entered, it is a good idea to generate the resource to make sure you have the FSH correct – do this by clicking the refresh icon to the upper right (looks like 2 round arrows). This will call the sushi API with the FSH from the text box, and populate the Json & Xml tabs with the complete resource. If there are errors, they will be displayed above the text box, and you will need to correct them at some point.

Here’s an example of a missing element:

Make sure you click the Save button at the upper right to save your changes. Note that you can save FSH even if there are errors, but they will need to be fixed before saving the resource to the FHIR server.

5. Save the resources to the FHIR server.

Back at the main editor screen, click the ‘Save to server’ link at the upper left. This will only show if you selected a server when creating the project – if you forgot, then you can go back and add it – click the blue ‘Project selector’ at the top, then the edit icon at the upper right corner of each project.

The save resources dialog displays a list of the resources in the view. At the top right of the list is a ‘Prepare to save’ link. Click that to check that the resources are ready to save. GraphBuilder will ‘re-build’ all the resources in the view from the FSH content. Any errors will be displayed and will need to be corrected before proceeding. In some cases, you can still save even if there are errors – generally if the green ‘Send to Server’ button appears you are OK, though technically the resource is not compliant.

Clicking the green ‘Send to Server’ button will package all the resources into a Transaction bundle and send it to the FHIR server.

All going well, the resources will be saved to the server – any errors will be displayed.

You can save a view any number of times – if the resource changes, then a new version will be created on the server.

Odds and ends

That’s really all there is to it. There are other functions within GraphBuilder that we won’t discuss now – but there are a couple of things worth mentioning.

It’s possible for a project to have multiple views within it – useful for representing changes to a resource or de-cluttering a view. To create a new view, click the ‘New View’ link at the bottom of the left pane. You’ll get a dialog where you can enter a name for the view and there’s a checkbox that allows you to copy existing resources into the new view.

If this is going to be a different set of resources, you’ll want to unselect this. When adding resources to the new view, you’ll note that existing resources will also be available for you to add. Often, you’ll want the Patient at least, but it depends on the use case.

The other thing to mention is the library. By default, the project is saved in your local browser cache so only viewable by you. However, you can save the project to the library (a mongo server that is part of clinFHIR) and then others can view and download it.

There’s a green ‘Upload to Library’ button at the top that does this. In the dialog there us a url to the library entry – you can copy that url and send it to others to view.