Introduction
The FHIR standard specifies a powerful mechanism for push-based notification of changes in the repository. This mechanism is called Subscription.
A Subscription is a publish-subscribe (pub/sub) mechanism built into the FHIR specification. Subscriptions are defined using the Subscription resource, which specifies what type of data is being subscribed to and how the recipient should be notified.
A simple example of a Subscription resource follows:
{
"resourceType": "Subscription",
"status": "requested",
"criteria": "Patient?name=smith",
"channel": {
"type": "rest-hook",
"endpoint": "http://example.com:8080/fhir",
"payload": "application/json"
}
}
The Subscription resource contains several important fields:
status – When a Subscription is created by a client, it should have a status of requested. Smile CDR will process this Subscription, and if it is valid, the status will automatically be changed to active, meaning that the Subscription is now being processed.
criteria – This is a FHIR search query URL that will be used to determine which resources apply to the Subscription. These resources will trigger a notification when they change. See Criteria below for more information.
channel.type – This is the mechanism for delivery, such as rest-hook, websocket, email, sms, or message. See Channel Types for more information.
channel.endpoint – For channel types that require the server to initiate a connection to the client, this is the URL of the endpoint to which the server should connect.
channel.payload – This is the mimetype encoding to use (e.g. application/fhir+json for JSON data).
To create a new Subscription, the subscription should be submitted to the server via a FHIR create operation (i.e. exactly the same way that any other resource is created).
Subscriptions should be requested by submitting the subscription in REQUESTED state. The server will examine the subscription, and if it is able to activate it, the status will automatically be changed to ACTIVE. Only subscription types which have been enabled on that FHIR Storage module (e.g. REST_HOOK, EMAIL) will be activated. All other incoming subscriptions will be left in the REQUESTED state.
When any resources that match Subscription.criteria are created or updated, the specified notification will occur. For example, if the Subscription specifies a criteria of Patient?name=smith then a notification will occur any time a Patient named "smith" is created or updated.
Smile CDR tries to match subscription criteria against an incoming resource using only the data available within the resource. If this isn't possible, it queries the database to determine a match, either via a database call. The following subscription criteria elements are not supported by the in-memory matcher:
_id, _lastUpdated, _has, _tag, _text, _content, etc.eq, gt, etc.
date comparisons: gt, ge, eq, lt, and le.Patient?_has:Observation:patient:code=1234-5Group?characteristic-value=gender$mixedPatient?_list=42If any of these elements is present in a subscription criteria, then Smile CDR will not match the resource against the subscription criteria in-memory, but instead fall back to querying the repository directly.
The Subscription Troubleshooting Log can be helpful in diagnosing issues relating to subscriptions.