Providing UI hints for FHIR queries

One of the requirements we were given when developing a patient based Observation query at Orion Health was that the response bundle needed to indicate that the user making the request was able to add new Observations for that patient. This was so that the User Interface (UI) could provide the appropriate link – or not, as the case may be.

Now this is a bit of a tricky one for a number of reasons.

  • It is context specific – the answer will depend on the user and the patient as well as the resource type (Observation in this case).
  • There is currently no direct support for this in FHIR (that we could determine)
  • We weren’t sure that this was even an appropriate thing to do. Granted that it was good for the UI, as it could enable/disable an ‘add Observation’ button, but given that the server responding to the query would need access to some service that can answer the question (Is this user allowed to add Observations for this patient) – wouldn’t it be tidier for the UI app to just call that service itself?

However, our arguments against it were not deemed persuasive, so a solution was needed.

Because it is context dependent, it couldn’t be anything attached to the resource (as it would change depending on the user accessing it). This meant that it needed to be something on the response Bundle. Examining the spec, we see the element – along with the following comment:

Both and are defined to support providing additional context when bundles are used (e.g. HATEOAS). corresponds to links found in the HTTP header if the resource in the entry was read directly. This specification defines some specific uses of for searching and paging, but no specific uses for, and no defined function in a transaction. Meaning is implementation specific

So it seems that this is a reasonable element to use. The reference to HATEOAS is intriguing. In a way, this is what we’re needing to do – using the response to a query to tell the user what they are able to do next – so it does feel right.

The link element has 2 parts:

  • A relation element that defines the meaning of the link.
  • A Uri that is the actual link.

We couldn’t find an appropriate entry in the ‘official list’ of relations – so we created one ourselves. Because it’s implementation specific, we’re going to use ‘oh.add’ (short for Orion Health add) and the link will be a uri that indicates how a resource could be added – thus the value would be ‘ Observation’ – indicating that the current user can add Observations by POSTing to the Observation end point. (We assume that a client knows how to add an Observation). Of course this is only a hint to the UI – the normal security will kick in when the user actually attempts to add the Observation.

The name ‘oh.add’ was chosen to be consistent with the naming for custom operations – to avoid any future ‘collision’ with an official name. (the dot (.) is kind of like a namespace).

So now the UI can look for the presense of the ‘oh.add’ link, and render the appropriate control to add a new resource. And it doesn’t matter if it doesn’t understand it – securiity will always be enforced by the server regardless.

Because this is specific to our implementation, we need to be sure to document it in our conformance resource – in the element probably.

On reflection, it does have the advantage that it can be extended to cover more complex workflows.

For example, suppose a particular observation can be edited only by the author. You could add a link to the entry for that observation – say oh.edit – that the UI can interpret and add an edit link (Again, the actual edit attempt will be subject to security of course)

Or – maybe the user was able to access the basic patient details, but had to enter a reason to view the observations (a variant on ‘Break the Glass’). When the system made the initial query, it could return an empty bundle, with a link having the relation value of ‘oh.view’ and the uri pointing to a custom operation that could accept the reason and set whatever tokens were required to allow the access (the details are left as an exercise for the reader!).

So I’m not too uncomfortable with the approach.


About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

One Response to Providing UI hints for FHIR queries

  1. An additional benefit of the HATEOAS approach in this kind of scenario is it allows an free downgrade of both client and server capabilities in the event that one doesn’t support this extension.

    E.g. if a client expecting these extensions talks to a server without, Observations will still be visible, but adding will be disabled since the client is unaware of whether the server will allow it for this user.

    Similarly, a client that is unaware of these extensions will still correctly list observations, and if it tries to add them will receive an appropriate error.

Leave a Reply