REST APIs commonly use a polling method to configure notifications about changes in the system, meaning that to get informed about any new actions, a client has to send a request to the server to receive the new data. More than half of such requests are wasted, creating an additional unnecessary server load for the sender and receiver.
The FHIR specification describes a more efficient way of receiving notifications about changes on an FHIR API server called Subscription. The FHIR subscription mechanism implements a push-based notification approach.
In this article, we’ll demonstrate with examples how the process for FHIR notifications works and how to set it up for your FHIR server. For a comprehensive comparison between different FHIR server implementations and their approaches to subscription management, see our article on Kodjin vs. HAPI. Since the Kodjin FHIR Server, a low-code FHIR server designed for high-load projects, closely follows the FHIR specification, we’ll be using it for our examples.
How the FHIR Server Subscription mechanism works
To set up FHIR notifications, a client posts a subscription resource, which specifies notification criteria and a notification channel, to the FHIR server, and then, when a resource that meets the criteria is created or updated, the server will notify the client using the provided channel.
Subscription notification criteria
First, let’s define a notification criteria, a rule the FHIR server uses to determine when to generate notifications for a particular subscription. Technically, it’s a search string with the same interpretation as if it was appended to the base URL and submitted to the FHIR search using REST API.
Any valid search string can be used as notification criteria, including ones with modifiers and prefixes implemented by the Kodjin FHIR Server.
Examples:
Get notified when observations for the patient are ready:
"criteria": "Observation?patient=Patient/afdd5d70-b737-414d-81fa-5bba46e4bbf3&status=final"Get notified when a patient born after 2021 is registered or updated:
"criteria": "Patient?birthdate=gt2021"Get notified when a condition with a certain code is registered or updated:
"criteria": "Condition?code=http://snomed.info/sct|39065001”Subscription notification channel
Next, we need to specify the notification channel to use. There are several types of channels described by the FHIR specification. Each channel has its appropriate use, so you can choose the channel that suits your business case the most. See the table below.
Subscription resource content
The subscription resource contains the following information.
FHIR subscription example:
Example:
{
"resourceType": "Subscription",
"id": "998dfaf9-32c7-45d3-bebc-9d4d4da16b84",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">[Put rendering here]</div>"
},
"status": "requested",
"contact": [
{
"system": "phone",
"value": "ext 4123"
}
],
"end": "2022-09-03T09:46:37.079Z",
"reason": "Monitor new observations for patient",
"criteria": "Observation?patient=Patient/afdd5d70-b737-414d-81fa-5bba46e4bbf3&status=final",
"channel": {
"type": "rest-hook",
"endpoint": "https://test-subscription.free.beeceptor.com",
"payload": "application/json",
"header": [
"Authorization: Bearer secret-token-abc-123"
]
}How to establish a connection for WebSocket channel type
If you choose a WebSocket channel type for communication, then you will need to establish a WebSocket connection with the server to receive FHIR notifications.
Here’s how to do it:
- 1. Post a subscription resource with the channel type “websocket”.
- 2. Connect to the server’s WebSocket URL (see WebSocket extension in the server’s Capability Statement).
- 3. Send a bind :id message over the socket (using the logical id of the subscription, for example, bind 123).
- 4. If everything is okay, the FHIR server will respond with “bound :id”.
- 5. Receive a “ping :id” message each time a resource that meets the criteria is updated or created.
Delivery retry
The FHIR specification doesn’t describe a delivery retry mechanism for the subscriptions. We’ve implemented it for the Kodjin FHIR server to provide efficiency and a better user experience. Delivery retry is available only for rest-hook notifications in the Kodjin FHIR Server. When the server fails to send a notification, it will perform these next steps:
- change subscription.status to error
- write error notice to subscription.error
- retry for N (configured on a server level) times
- if successful, change subscription.status to active and clear subscription.error
- in case of failure, change subscription.status to off
To receive messages over the WebSocket channel, the client leaves the connection open. Missed notifications are not to be re-sent.
Note that if a message is re-sent, the original order of the messages may be changed. That way, older messages may be delivered after newer ones. Look for version_id in meta to handle this situation.
How to deactivate a subscription
You can deactivate a subscription anytime by changing the status to “off” or deleting the subscription. Also, you can set the “end” parameter in the subscription resource, so the FHIR Server will automatically disable it at a given time.
Conclusion
In many workflows, it is crucial to have the ability to send notifications to clients based on changes in the FHIR Server. We hope that with this tutorial, you’ll be able to configure an FHIR server to fit your needs.
If you have any additional questions or need help setting up or managing your FHIR server, don’t hesitate to contact us for a free consultation.
