Skip to content

Subscriptions

The Subscription mechanism implements a push-based notification approach. In order to receive a notification, client posts a Subscription resource, which specifies notification criterias and notification channel, and then, when a resource, that meets the criteria, is created or updated, server will notify the client, using the provided channel.

Process overview

  1. Client subscribes to notifications by posting a Subscription resource.
  2. Kodjin validates the subscription and changes the subscription status to active.
  3. Whenever a resource that meets the criteria, described in the subscription, is updated or created, Kodjin sends a notification to the client, using the provided channel.
  4. Subscription can be deleted by the client or its status can be changed to "off" by the server, in case of issues with the provided channel.

Notification criteria

the notification criteria is a rule the Kodjin FHIR Server uses to determine when to generate notifications for a subscription. It’s a Search string that has 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 a notification criteria, including ones with modifiers and prefixes implemented by Kodjin FHIR Server.

Examples of criteria

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”

Notification channel

There are several types of channels described by the FHIR specification. You can choose the channel that suits your business case the most. See descriptions in the table below.

Channel Description
rest-hook Rest-hook notification channel is great for server-to-server communication. It is very reliable and provides the ability to send not only notification but the resource itself. When a resource that meets the criteria, is created or updated, the server sends a POST request with no body to the nominated URL or , alternatively, the entire resource with a PUT request. In order to configure that, specify "payload": "application/fhir+json" for a PUT request or no payload at all for POST request. You can also specify headers, required by the nominated server, such as an authorization header.
websocket WebSocket channel is great for client-side web applications and mobile applications. There is no need to have an outward-facing HTTP server, instead notifications are delivered as ping messages over a Web Socket connection. For this case payload and headers won`t be specified, only the channel type.
email Email channel works best if the recipient of a notification is a human. The body of the message can be either empty or include search criteria (configured on the server). Use channel.endpoint to specify the recipient’s the email address and channel.header to specify email subject.
sms SMS channel works similarly to email. Use channel.endpoint to specify the recipient's phone number. Headers and payload should be omitted.

Resource Content

Name Description
status When the resource is posted, the status should always be set to requested. Kodjin will validate the resource and, in case of no errors, set status to active automatically.
contact Contact details for source (e.g. troubleshooting).
end The date when Kodjin will automatically set subscription status to off.
reason Description of why this subscription was created.
criteria Search string is a rule that Kodjin uses to determine when to generate notifications for a subscription.
error Latest error note.
channel.type The type of channel to send notifications on.
channel.endpoint Depending on a channel:
  • for rest-hook it is actual end-point to send messages to
  • for email it is email address of the recipient
  • for sms it's a phone number
channel.payload Used only for rest-hook notifications. If declared, PUT request with resource in the body will be sent instead of empty POST request. Only mime-type application/fhir+json is supported.
channel.header Depending on a channel:
  • for rest-hook, these are actual http headers appended to the request
  • for email, it is email subject

Example of Subscription Resource

{
  "resourceType": "Subscription",
  "id": "998dfaf9-32c7-45d3-bebc-9d4d4da16b84",
  "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"
    ]
  }
}

Try subscriptions with our Kodjin FHIR Server Postman Collection

Establishing 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 in order to receive notifications.

  1. Post a Subscription resource with the channel type “websocket”
  2. Connect to the server's webSocketUrl (see websocket extension in the server's CapabilityStatement).
  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, Kodjin 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

Delivery retry is available only for rest-hook notifications in Kodjin. When Kodjin fails to send a notification, it will perform the next steps:

  1. change subscription.status to error
  2. write error notice to subscription.error
  3. retry for N (configured on a server level) times
  4. in case of success, change subscription.status to active and clear subscription.error
  5. in case of failure, change subscription.status to off

In order to receive messages over the WebSocket channel, the client shall keep the connection open. Missed notifications are not to be re-sent.

Note that, in case of re-sending a message, 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 in order to differentiate older and newer messages.

Deactivating subscription

You can deactivate a subscription at any time by changing the status to “off” or deleting the subscription. Additionally, you can set the “end” parameter in the Subscription resource, so Kodjin will automatically disable it in a given time.