So in the previous post about the upcoming Trans-Tasman connectathon I mentioned that I was going to work on a couple of applications in the IPS track – a way of visualizing IPS documents (actually any kind of FHIR document), and a ‘façade’ application that could produce an IPS document on demand from a back-end data source.
This post is an update of where I’ve got to.
We’ll start by looking at the viewing application – the clinFHIR Bundle Visualizer. This module has actually been around for quite a while – I started it when we were looking at v2 to FHIR messages a number of years ago but in the last few days I’ve simplified it a bit.
As you’ll probably be aware, the Bundle resource is a ‘collection’ resource – it has within it any number of other resources, and it is used in a variety of scenarios such as the collection of resources from a REST query or the resources that represent a Document or Message.
Note that the use of a Bundle to contain resources is quite different to ‘contained’ resources. The latter is where you place one resource inside another and its use is really quite limited – you use it when the ‘contained’ resource has no separate identity of its own. If you’re interested, take a look at a discussion on the use of contained resource in the context of MedicationStatement.
There are 2 ways to get a Bundle into the Visualizer:
- It can be pasted directly into the app, either in XML or Json format (it uses the Lantana library to convert from XML to Json)
- The app can make an HTTP query (generally against a FHIR server) to retrieve the Bundle, which is currently expected to be Json. The server must implement the CORS protocol, as the call is coming from a web page.
Here’s the main UI:
There are 3 top level tabs.
The home tab has some documentation and configuration options, as well as a list of saved queries to the right. The ‘data server’ is the default server for queries as we’ll see in a moment. The ‘validation server’ is a server that exposes a $validate operation used for checking the resources. Validation usually occurs automatically, though this can be disabled using the checkbox at the bottom.
Note that the validation occurs for each individual resource – it’s a separate call to the $validate for the resource type. The implication of this is that it won’t handle ‘Bundle’ level validation very well. For example, the IPS expects that there is a medication section in the Composition with at least 1 MedicationStatement resource conforming to the IPS profile on MedicationStatement. But, because the Composition is validated separately, it doesn’t know about any other resources and hence the validation fails.
What’s needed is a ‘whole bundle’ validation option – something I’ll be working on over the Connectathon.
The Paste in bundle tab is where an existing bundle is added directly into the app and the Enter query url is where a query url is entered – and optionally saved in the browser cache.
Let’s start with the query. Here’s a screen shot:
The query url is entered midway down the left side, and the ‘Test query’ button is clicked. The app executes the query, and displays the result to the right. Note that the full query including server is entered, and that the result is – as expected – a bundle (though not a Document bundle in this case).
To import the bundle into the app and construct the different visualizations, click the green ‘View Bundle’ button. If you want to save the query for later use (it will appear on the home page) then enter a name in the text box and a red button labelled ‘Add query to list and view’ will appear that does the same thing, but also adds the query to the home page list as well. This list is stored in the Browser, and so will only appear when using the same Browser.
The bundle display looks like this:
The display has 4 main tabs.
- Bundle entries lists all the entries in the bundle (each of which contains a resource) and allows you to view each one. This is the tab you’ll use most often.
- References graph will display a single graph of all the resources in the bundle. Depending on the number of resources in the bundle, this can be quite cluttered – there are more focused graphs that we’ll see in a moment.
- The Canonical graph uses canonical references rather than direct references for the graph. Canonical resources are where the target resource is specified by its canonical url rather than id, and is commonly used in the Clinical Reasoning space.
- The Json tab displays the raw Json content of the bundle.
To return to the home page (eg to select another bundle) click the Show Selector link at the top of the page.
The bundle entries tab is further divided into 2 panes. The left pane displays resources in the bundle in a number of formats and the right pane displays the visualizations for a selected resource.
Visualizations that are available are:
- The Json content of the resource
- The Json content of the entry that holds the resource
- The text of the resource – i.e. the content of the .text element
- A tree view of the resource
- The references to and from the resource in a graph. This is often more useful than the complete bundle graph described above. Selecting a resource in the graph will display the Json content of that resource to the right
- Validation errors – if any (and if validation is enabled). Not all the errors and warnings are significant – for example the validator will complain if there is no .text element, or if it cannot find a referenced resource, which will generally occur if the validation server is not the same server as the query.
Here’s a screen shot of the graph with a resource selected:
If you already have the bundle you want to examine (e.g. in a file somewhere) then click the ‘show selector’ link at the top of the app, which will return you to the main selector screen. You can then select the ‘Paste in bundle’ tab, and paste the bundle directly into the text box as shown in the screen shot below:
Click the ‘View Bundle’ button to get the same visualizations as before. Note that there is no option to save the bundle (which was present in earlier versions of the app). Given that you already have the bundle, this isn’t all that useful. And on the subject of changes, there is no longer any ‘log in’ option – it isn’t needed any more.
One last thing to point out is that if the bundle is a Document (Bundle.type = ‘document’) then there is an additional view available – the document view – that generates the document from the bundle contents as defined by the spec.
So that’s really all we’re going to talk about the Bundle Visualizer for now. Next up is a discussion of the Node-Red façade – probably after the Connectathon.