FHIR® tutorials

Patient with References tutorial

This tutorial will build on the foundation laid out in the Simple Patient tutorial to introduce resource linking in FHIR by the way of references.

Step 1: Setup

Prior to doing the tutorial, a set of FHIR resources needs to be uploaded to the tutorial FHIR server so you can query them. Press the Upload button below to send your resources up:


Step 2: Find your patient

The patient you'll be working with is:

(press Upload to get a Patient)

Open Postman and retrieve the resource, if you have forgotten how then revisit the Simple Patient tutorial. You should see this in Postman when successful.

Our sample patient today is Pieter van de Heuvel, who came into the hospital for his scheduled heart valve replacement, but fainted before the procedure could begin - for this reason, the medical staff decided to do some blood tests on the patient first.

There are 6 resources we'll be working with in this use case - Patient, Encounter, ProcedureRequest, DiagnosticReport, and two Observations.

Step 3: Observe external references

In FHIR resources are referenced, or linked, in one direction only. For example, if you have two resources - a Patient and an Observation - a Patient will not be linked to any of the Observations; instead all Observations will be linked to the Patient. This is an optimisation measure - it means that as you add more Observations, you do not have to keep updating your Patient resource with the new references. This also means that the Patient doesn't have an explicit link to any of the Observations - but not to worry, there is a way to see all Observations that a Patient has, which we'll cover later.

In order to see which resource links to which, open up the FHIR specification for a specific resource and observe the list of resources that reference it. In our example, you can find out if it is a Patient linking to an Observation or an Observation linking to a Patient by opening both the Patient and Observation FHIR specification pages. You'll notice that Patient mentions that it's referenced by the Observation resource and Observation does not, instead it has a subject field which references Patient.

In the same Postman window, press Ctrl/⌘+F and copy/paste reference - you'll find that the Patient contains just one reference, which is the medical organisation that the Patient belongs to. Even though our patient had an encounter (when he came into the hospital for his procedure), it is not listed here.

Instead, it is the Encounter that has a reference to the Patient. That way more Encounters can be added without having to update the Patient resource every time (which can become very time-consuming in a large system). In the next section, you'll see how you can find the Encounter that's associated with your Patient.

Step 4: Search for a resource using a reference

FHIR has a notion of Search Parameters, which allow you to locate resources given certain information you know about them. As a sample use case, let's find the Encounter that's associated with our patient. Scrolling down to the Search Parameters section of Encounter, we see that there's one named patient which allows us to search for the patient present in the encounter.

Thus, given the patient's server ID of (press Upload first) (this can be seen at the end of the URL and in the <id> field), in order to find which encounters our patient has, the query follows this format:

(press Upload first)/Encounter?patient=Patient/<patient id>

It essentially says - "give me all Encounters that have this patient ID as the subject patient". Try entering (press Upload first)/Encounter?patient=Patient/ into Postman - you'll see a result like this:

.

Three things are of interest are:

  1. We get a Bundle resource back. A Bundle is essentially a container for resources, used in many places including search results.
  2. Our Bundle has 1 result in it, which is...
  3. The expected Encounter resource, given our Patient has just one recorded encounter.

We've now successfully located which encounters our patient has using a reference - congratulations!

Step 5: Observe contained resource references

References don't always have to point to a resource located elsewhere, they can also point to resources that are contained (embedded) in the resource. Load up our ProcedureRequest in Postman:

(press Upload first)

Press Ctrl/⌘+F and copy/paste practitionerid - you'll find two references to it, one in <reference value="#practitionerid" /> and another in a <contained> field:

Whenever you see an identifier start with the hash sign (#), you will see a corresponding resource within the <contained> field, embedded in the parent resource. Such embedding should only be done in the cases where the embedded resource can't exist on its own - for example it can't have an identifier to uniquely identify it or it only makes sense in a particular transaction scope.