Groups of patients in FHIR

I was approached by one of the Dev teams here at Orion Health for some help in ‘FHIR-enabling’ a patient selection service that they have been asked to build. My initial reaction was that we could model this directly as a restful query against /Patient, but after talking to them, the requirements were a bit more complex.

The application/module that they want to query against is a Clinical Pathways one. Patients are registered against a pathway – like diabetes management – and the requirement is to be able to return a list of patients on that pathway. The current requirement is just to return the list, but at some time in the future it is likely that there will be other query parameters as well.

The ‘twist’ to the story was that they wanted to be able to include in the returned list the ‘access level’ of the user making the query for each patient. This would be used by the client to display ‘hints’ to the user in the list UI – eg if the user would need to ‘break the glass’ to view that patients records then the UI would display a lock icon & so forth.

There may also be situations where the user should not even know if the patient is on a pathway, and in that case the patient should not even be in the list. In this scenario the client needs to know that the returned list is incomplete (but not the details of course).

Lets think about this in two parts – the format of the List, and how to represent the access levels.

We talked over a number of options for the list format.

Initially we were thinking of a DSTU-2 style operation to allow for different query parameters and back-end processing – but after some discussion this seemed overkill, and also we preferred to use DSTU-1 at this stage, as that is what the other FHIR initiatives in Orion Health are using – and consistency across the organization is important (especially as we are using the HAPI library to handle the manipulation of resources).

Eventually we settled on the Group resource. From the spec: “To define a group of specific people, animals, devices, etc. that is being tracked, examined or otherwise referenced as part of healthcare-related activities” so that seemed ideal. We can use the identifier property to identify the specific pathway that we want to list the patients on, and the type property to indicate that we are expecting Patient resources in the list.

So now for the ‘security’ aspects of the list.

What this requires is that the server, when processing the query will need to perform the following actions:

  1. Retrieve the list of patients from the pathway.
  2. For each patient in the list, call the internal privacy service to determine the level of access of the user making the query (naturally it will be an authenticated user). Depending on the access level, then the server will place the appropriate annotation in the list so the client can render the UI.

There a quirk though – If the user is unable to access a patient – but is allowed to know that they are on the list then that is just another annotation – but what to do if they aren’t even allowed to know? Maybe the patient is a VIP of some sort? We should let the client know that the list is incomplete, but no more than that. In the end we decided that an OperationOutcome resource in the returned bundle would be the best approach – and we can add an extension to the type property (of datatype CodeableConcept) that indicates the reason why the list is incomplete (and we’ll create a ValueSet that has the list of possible values, with a Profile connecting the two).

So how do we do the annotation? Well, that seems a good fit with the tags ability of FHIR. All we need to do is place the appropriate tag against each patient and we’re done. Initially we looked at the defined security labels (which are a specific type of tag), but after some discussion on the skype implementers chat we decided that this wasn’t the best fit. We were wanting to indicate the outcome of privacy processing rather than attributes of a resource that would be the inputs into such a decision so the fit wasn’t really all that good. We decided to use a custom set of tags with a ValueSet that lists the possible values for the tags.

So there you have it.

The query (which would be made by an authenticated user) will look something like:


The response will be a bundle that contains:

  • A Group resource representing the pathway group. We may add extensions to this resource if there’s more we want to tell the client about the pathway, though we do have the text property if we just want to display text to the user.
  • Zero or more Patient resources, each patient being referenced by the member property of the Group. Note that the client didn’t need to tell the server to include the Patient resources – the server is allowed to add other resources as it sees fit, though it can also respond to an _include request if it has the functionality.
  • Similarly there may be some Practitioner resources from the Patient.careProvider property
  • Each patient will have one of our custom tags to indicate the action the user will need to take if they select that patient (obviously security will be applied when the patient is selected – not when the list is generated!). Of course, if this service is consumed by a client that doesn’t understand our tags then no harm has been done – the security will still be applied when the patient is selected regardless.
  • An optional OperationOutcome resource – at this stage only when the list is incomplete, but we could use it in any other situation when we want to notify the user of something.

We should also create a profile that describes this service, binds the various ValueSets to the coded properties, and includes the definitions of the extensions as well. Perhaps a topic for another post!

It also raises questions about whether every internal ‘end point’ that is FHIR related should have a Conformance resource exposed by it (I suspect that the answer is yes, as it helps with documentation if nothing else).

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.

8 Responses to Groups of patients in FHIR

  1. John Moehrke says:

    David, you should look again at security tags. What you want are the nonpersistent tags from the Obligations valueset.


    • David Hay says:

      Thanks John! Certainly will…


    • Ed Costello says:

      Hi John & David,

      As I understand it, the Obligations valueset give some of the capabilities discussed in this post, however only if used in a context where the caller is a system that can be trusted to adhere to the annotations.

      If the client of the FHIR API is a trusted system actor, then returning the full data and an ANONY label is OK as the client can be trusted to annoanamise the data.

      However, if the client of the FHIR REST API is an end user (via a client side web-UI or mobile app) then we can’t rely on the handling restriction actually being applied. Even if the application does apply the restriction, a malicious user can always bypass it by calling the REST service directly.

      So when the client is an end user rather than a trusted system, these kinds of restrictions essentially need to be applied by the FHIR server rather than the client.

      That said, thinking about these operations in terms of the handling restrictions is a really good conceptual model even when the server is the one applying those restrictions.

  2. Pale FHIR says:

    Sorry, this is a tangential question. How are you identifying each pathway – what’s the identifier and what other attributes distinguishes one pathway from another?

    • David Hay says:

      This is an internal identifier – I’d have to go to the dev guys for more details! Feel free to contact me directly if you want to follow this up…


  3. John Moehrke says:

    David, We are working in IHE on PIX on FHIR. In the original PIX it allows a client to ask for all patient identities that cross-reference to the one the client supplies. The desire is to return ONLY those identifiers. NOT the whole Patient resource. And the results might be represented by more than one Patient resource, in the cases where they have not been merged. Seems Operation is our friend, but I am not clear… Can you help?

    • David Hay says:

      Hi John, as I understand how the Operation works in DSTU-2 there’s no reason why you couldn’t use it for this purpose. You would define an input parameter of type ‘Identifier’ for the supplied identifier and an output parameter also of type ‘Identifier’ with a maximum cardinality of ‘*’ for the results. Once you have the cross-referenced identifiers, you could use a standard GET ( [host]/Patient?Identifier={x} ) to retrieve the actual resources if you wanted them.

      Here’s a link to the operation definition for those unfamiliar with operation: and heres how you define it:


  4. Lin Zhang says:

    Link to Chinese translation of this post:

Leave a Reply to Pale FHIRCancel reply

%d bloggers like this: