Using the clinFHIR query tool

I’ve been in China recently (attending the CHIMA conference and presenting on FHIR in a number of events), and while there I had a bit of spare time, so decided to give the clinFHIR query tool a bit of attention (I also needed it for the workshop I gave).

The query tool has been there for quite a while, but it’s been rather basic and a bit klunky, so a facelift was overdue!

At a high level, there are a number of main functions you can use it for.

• Querying a FHIR Server. This is useful when learning FHIR as you can send queries to a server (and there’s a simple query builder built in) and then review the response in a number of different ways (plain JSON, XML, a tree, FHIRPath query).
• Saving/Updating a resource directly against a FHIR server
• Validating a resource. This is useful if you are building a resource by hand and want to be sure it is valid. You can also use it to validate a resource instance against a specific profile.

To run the query tool, start clinFHIR and select the tool from the main menu. Here is a screenshot of the main UI.

At the top of the page is where you select the server to query. You can select any of the configured servers (including any that you have added through the ‘Add Server’ dialog on the front page), and you can also directly enter the URL to any FHIR compliant server.

The server must be able to return a ‘CapabilityStatement’ resource (‘Conformance’ resource in STU2). The tool will then use that resource to populate the list of supported resources, and will also generate a display (the ‘Server Capabilities’ tab).

There are 4 main tabs.

• The Query tab. Here is where you can make queries against the selected server
• The Validate tab. Used for validating resources built separately. It can also be used to add a resource directly.
• The Server Capabilities tab lists what the server supports – according to the CapabilityStatement downloaded when the server was selected
• The Query Help tab has some useful summaries and links for querying a FHIR server.

We’ll examine each of these.

The Query tab offers 2 options for generating the query – a simple builder and an ‘ad hoc’ option where you enter the query directly.

Use the builder as follows.

Select the resource you want to query from the dropdown

You can either enter the search parameters directly into the text box to the right, or click the plus (+) symbol to get a dialog box that has the search parameters supported by the server for that resource. In either case you will see the actual query displayed below the parameter box. Note that you don’t need to enter the full url – the tool will do that for you.

Here’s an example:

Once you have completed the query, click the ‘Execute’ button to run the query against the selected server.

Here is an example of the result from running a query. The resources from the result bundle are displayed to the left, with various display options to the right. In this example, the Json tab has been selected.

The Ad hoc REST query allows you to enter the query directly. You don’t need to enter the server root, but you do need to enter the resource type. Once you’ve executed the query, the response viewer is the same. Here’s a screen shot:

Some general notes about querying and displaying the responses.

If you want to return a single resource by its id on the server, then you need to use a special syntax – querying by _id.  This will return a bundle with one resource rather than the resource itself. Actually, this is quite handy as it allows you to use other search parameters, such as _include. For example the following query returns a bundle containing a single observation with an id of 160250 and the Patient that is the subject of the observation (the server base url is added automatically).

Observation?_id=160250&_include=Observation:subject

The Validation sub-tab allows you to validate the selected resource against a given profile. You can choose a different server to perform the validation than the one you retrieved the resource from – useful when the server does not support validation.

There’s a link labelled ‘Show Bundle’ immediately above the list of resources in the bundle. Clicking that link will show the raw bundle received back from the server, plus the FHIRPath query facility that allows you to make queries directly against that bundle.

The Validate tab (the main one – not the one that appear when you select a resource returned in a query described above) allows you to validate that a resource instance you have created externally is valid – either against the core spec or against a particular profile. Selecting the tab will show a box where you can paste the resource (currently it must be a single resource in Json format) and then validate it against a given profile. Here’s an example of a valid resource:

And here’s an example where the resource is not valid (name.use has not got a valid value). Note that you may need to scroll the error text sideways to see the entire response.

If you don’t specify a profile to validate against, then the tool will validate against the core definition for that resource type. If you do enter a profile (and the server you have selected has a copy of that profile) then it will use the profile you enter. Here’s an example of seeing is a Patient resource instance is conformant to the CodeSystem profile. Unsurprisingly, it isn’t. Note that the profile was added to the meta.profile element on the resource instance by the tool.

Once an instance has been validated, a red ‘Send to Server’ button will appear at the bottom right. Clicking that will save the instance to the server – any errors will be displayed. If the instance has an id property, then an update will occur – otherwise a new resource will be created – and can be queried for on the query tab.

The Server capabilities tab displays the CapabilityStatement resource that was received from the server when selected. It has a number of sub-tabs:

• The Description tab shows – well – the description of the server
• The REST interface tab lists the resource types that are supported over a REST interface. There’s a ‘globe’ icon that will display the details of the type in the spec, and selecting a type will display a ‘tree view’ of the type.
• The operations tab shows the supported operations (without any documentation unfortunately – I’ll look into that)
• And the Json tab shows the raw json.

Here’s the REST interface tab:

Note that if the server specifies a base system profile for a resource type, then a tree view is displayed.

And finally the Query Help tab has a number of useful links.