Viewing an IPS Document

Many people reading this post will be aware of the International Patient Summary (IPS) Implementation Guide that describes a consistent set of key clinical data such as Medications, Allergies and significant conditions for use as a concise summary of a person’s health status when seeing an unfamiliar provider. It is widely used internationally, and even has its own website. 

There are a number of important things about the IPS (apart from the fact that it is globally usable).

Firstly, it defines the key aspects of a health record Clinicians need when treating a patient they are not familiar with – things like usual medications, any allergies (or a specific affirmation that there are none), important conditions and so forth.

And secondly, it defines these aspects in a way that is not only human readable, but also capable of updating an Electronic Health Record by defining specific codes for the elements, and the capacity to include specific resources such as MedicationStatement, Condition and AllergyIntolerance.

In this post, we’ll use the clinFHIR Bundle Viewer to take a look inside an IPS document and review those resources. We’ll note in passing that you could also use the Patient Viewer to view the bundle – it has a very similar display, but less technically focussed – no validation for example – so more suited to the business or clinical viewer.

To start with, let’s find an IPS document to view. We should note that there’s nothing technically special about IPS – it’s a standard FHIR document bundle that conforms to the IPS Implementation guide – largely by profiling the Composition resource. This means that you can use any of the usual methods to load the document bundle into the viewer.

You could:

• Directly paste the bundle (as json) into the viewer (or upload it from a file)
• Enter a link to a document on a server somewhere and retrieve it from there. The server could be a FHIR REST endpoint (perhaps using the $summary) operation, or a link to a static bundle on github (or similar). (you can save the link for later if you want)
• Use the IPS bundles selection option to call the $summary operation for a patient on a server or known documents (more on that later)
•  Use one of the sample documents in the viewer.

We’ll use the last approach as you can see in the following screenshot:

and here’s a direct link to it. When you load the bundle, you’ll note that the spinner at the top stays turning for a few seconds. That’s the validation in process – we’ll cover that shortly. This is Peter Jordan’s IPS – used with permission.

Once the bundle is loaded, take a look first at the Document tab, which shows when the bundle contains a Composition resource.

This tab presents a nice looking display of the document. As described in the spec, it is derived using the narrative (.text) elements of the Patient, Composition and Composition.section – i.e. it is rendered according to how the author defined it (potentially affected by external CSS).

To dig a little deeper, click on the ‘Sections’ sub tab, and then the ‘Resources’ tab to the right.

Now we’re looking at the actual resources within the section (Immunizations in this case). You can see the list of resources to the left and the actual Json of the selected resource to the right. Above the Json is a link called ‘Details’. Click that. You’ll jump to the ‘Bundle entries’ tab with that resource selected. Now you have the specific views for any resource in the bundle. As an example, take a look at the ‘Graph’ sub tab.

This shows the references – to and from – the selected resource. 

There’s another view that is useful with a document (but shows with all bundles). Click the top level ‘Clinical Resources’ tab.

This shows details of some of the sections in the Document – Observations, Medications, Conditions, Allergies, Procedures. 

And finally, you also have the full bundle graph. Pretty, but can be quite complex – and only shown if there are less than 200 resources in the bundle because of performance issues with larger numbers.

Earlier we mentioned validation. This is a complex subject, so we’ll just focus on how to use it. Just be aware that not all servers will expose the $validate operation that the viewer uses – and there’s no guarantee that the result will always be correct – especially for servers that can be publicly updated.

When a bundle is loaded, it is automatically validated using the $validate operation provided by the configured validation server. There are a number of these that can are configured in the Viewer by default, and you can add others if needed.

Validation results are displayed in the Validate tab.

You can change the Validation server by selecting it in the dropdown to the upper right and clicking the ‘Validate’ link to execute the operation. This is especially useful if the current validation server is missing a given CodeSystem. Clicking the ‘Servers’ link shows a dialog where new servers can be added, and servers tested for online status.

There are a couple of views of the validation results. The following screenshot shows issues separately for each resource in the bundle (if it has any issues). Clicking on the resource at left displays the issues and resource contents. This view hides a couple of issue types:  the one that complains about a missing narrative (.text) and errors relating to profiles.

You can jump to the details view of the resource (shows references as well as other views) and take a look at the resource type in the specification (R4B at present).

The next screenshot displays issues by severity. All issues are included. You can filter by severity. Again, clicking on an issue displays the resource contents, and there are links to details and specification as well.

One particular issue that is common is where the server reports that a particular coded value is not in the ValueSet defined in the profile (or core definition). This is not always an actual error (it depends on the underlying binding strength) but we have seen issues where the server reports this incorrectly due to issues on the server (such as a missing CodeSystem). For this reason there is a tab that allows you to list the contents of a ValueSet. You do need to carefully copy the ValueSet url from the error message, but can then paste it into the textbox and list the ValueSet contents (assuming the server supports the $expand operation as well as the ValueSet and supporting code systems.) 

It’s also possible to select a different server using the dropdown at the upper right for the search.

We mentioned at the beginning of this article that there are a number of ways to select a document.  The ‘IPS bundle’ option brings them together in a single place:

• Bundles that have been stored in the Library and contain a Composition resource
• Stored links that have been tagged with ‘ips’. These can (but don’t have to be) to FHIR REST servers – but a link to a static document is also quite possible (in fact, the app currently has links to Australian IPS documents)
• RESTful queries to servers that expose a $summary endpoint. You can add new servers using the ‘servers’ link.

The following screen shot shows the Servers dialog, where new servers can be added and existing servers test to see if they are online.

As mentioned above, do note that the validation is not always correct – for a variety of reasons such as:

• If the server does not contain a CodeSystem, it will generally say it can’t validate.
• Many of the servers are writable public servers which means conformance and terminology resources can be updated, sometimes with unexpected consequences.
• And sometimes the validation is just plain wrong!

So that’s a quick run through viewing an IPS document. 

Support for clinFHIR is on the zulip channel