Data flows into FHIR servers from many sources. That same data is often consumed by a host of applications and processes over time.
How do we track this?
The starting point is being able to identify the Who, What and When of every request that comes in.
Who created or requested the data?
What exact data was changed or returned?
When did the action occur?
There are a number of ways to store this information in FHIR.
- Meta.source element
- Provenance resource
- AuditEvent resource
Let’s look at these in more detail.
The Meta.source element
One of the less commonly used attributes of a resource’s Meta element is ‘source.’ This contains a single uri that can identify where the resource’s details came from. When used, it should be populated by the application that creates the resource.
Examples of what might be stored in a source uri:
- Another FHIR server
- A Hospital Information System
- A database or data warehouse
The Meta.source element holds a limited amount of information. It may be suitable to use when a single FHIR resource is being created or updated and where that resource is coming from a very specific source.
I’ve rarely seen this element populated, and in most cases recommend using the richer Provenance resource instead.
The Provenance resource
A Provenance resource can provide enough information to identify the origin of the data in a resource or in a bundle of resources. It should be created by the party sending the data, not by the server that receives it.
There are three key elements in a Provenance resource.
Agent
The parties involved in creating the data. There can be more than one Agent, each playing different roles in the data creation. Examples are people or organizations and software or devices.
There are some constraints around how the Agent elements should be populated, so be careful when mapping them.
Target
The list of FHIR resources created or updated as part of the transaction. Where possible, these resource references should specify a particular version of each resource, as different agents may update a resource at different times.
Including a versionId for each Target resource might not be possible for the sending party. The server that receives the bundle may have a role to play here in ensuring correct versions are documented in the Target element.
Recorded
When the activity was recorded.
Lesser used Provenance features
- A digital signature can also be included in a Provenance, though I’ve seldom seen this in practice.
- A Provenance resource can be sent as a JSON string using the x-provenance request header. Be cautious about using this as some servers restrict header length and not all servers support the x-provenance header.
You should read the official documentation surrounding the Provenance resource as deeply as possible before implementing it.
The AuditEvent resource
Different FHIR servers and implementations use AuditEvent in different ways.
Our current use case is ‘Who did What and When?’
Unlike Provenance, AuditEvent resources are created and populated by the server. They can be used to store detailed information on ALL server requests, not just updates.
Here’s an example.
A front end application makes a GET request for data relating to a patient’s visit to a hospital. The query string includes a number of _include and _revInclude parameters.
The FHIR server returns the following resources:
- Patient
- Practitioner
- Appointment
- Encounter
- Flag
Before the request completes, the server creates an AuditEvent resource documenting the request with the following elements populated.
- Recorded time of the request
- Agent details identifying the front end application, and possibly the user
- Subtype showing that it was a GET request
- Entity list of all resources sent in the request, with specific versions
There is some crossover between the information captured in the AuditEvent and Provenance resources, especially when transaction bundles are received and processed. In these cases the AuditEvent may duplicate some of the information in the Provenance resource.
The two resources serve different functions and are usually accessed by different applications or processes.
Proper use of the Provenance and AuditEvent resources allows a FHIR server to answer the Who, What and When questions.
But there are other elements scattered across resources that play roles here too.
FHIR defines a pattern called the FiveWs that goes deeper. This pattern is incomplete, but highlights elements and resources that contribute in identifying the Who, What, When, Where and Why.
It’s not easy reading, but it’s well worth spending some time examining the pattern mappings for the resource types you work with.
---