On this page:

8.0Subscription

 

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.

8.0.1The Subscription Resource

 

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).
  • channel.extension - Providing an extension allows finer control of subscription handling. Some extensions are channel specific, while others are used to define retry handling.

8.0.2Subscription Activation

 

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.

Delivery Retry Handling

Subscriptions that fail to deliver to their specified channel (REST, EMAIL, etc) will retry on error. By default, they will retry until they succeed, or indefinitely.

Some systems can be configured with a maximum retry count, via a channel.extension.

URLTypeDescription
http://hapifhir.io/fhir/StructureDefinition/subscription-delivery-retry-count integer If specified, this extension defines the maximum number of attempts made to deliver the subscription to the configured channel (with exponential backoff). After which, the failed subscription will be added to the systems [DeadLetterQueue](#dlq).

An example resource including this extension is shown below:

{
    "resourceType": "Subscription",
    "status": "requested",
    "criteria": "Patient?name=smith",
    "channel": {
        "type": "rest-hook",
        "endpoint": "http://localhost:1234/endpoint",
        "payload": "application/json",
        "extension": [
            {
                "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-delivery-retry-count",
                "valueInteger": "5"
            }
        ]
    }
}

NB: Only messaging systems using Kafka or Remote (not embedded) ActiveMQ support this extension.

# Dead Letter Queue

Dead Letter Queues are used to store undeliverable messages.

If the message system is configured to create queues/topics, they will be created when they are first needed. If not, however, the queues must be created ahead of time.

The name of the DLQ depends on the system, and is case sensitive.

KAFKA.DLQ for Kafka.

ActiveMQ.DLQ for ActiveMQ

8.0.3Criteria

 

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.

In-Memory Matching

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:

If 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.

8.0.4Troubleshooting Subscriptions

 

The Subscription Troubleshooting Log can be helpful in diagnosing issues relating to subscriptions.