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 Bundle.link element – along with the following comment:

Both bundle.link and Bundle.entry.link are defined to support providing additional context when bundles are used (e.g. HATEOAS). Bundle.entry.link corresponds to links found in the HTTP header if the resource in the entry was read directly. This specification defines some specific uses of Bundle.link for searching and paging, but no specific uses for Bundle.entry.link, 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 Conformance.rest.resource.searchParam.documentation 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.