19.0.1Subscription

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.

19.0.2The 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 MIME type 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.

19.0.3Subscription 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.

19.0.4Delivery Retry Handling

Subscriptions that fail to deliver to their specified channel will retry on error. By default, they will continue to retry indefinitely until they succeed.

19.0.4.1Extension: Subscription Delivery Retry Count

Some systems can use an extension to configure a subscription with a maximum retry count.

An example resource including this extension is shown below:

{
    "resourceType": "Subscription",
    "status": "active",
    "criteria": "Patient?name=Krabappel",
    "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"
            }
        ]
    }
}

19.0.4.2Dead Letter Queues

Dead Letter Queues (DLQs) are used to store undeliverable messages.

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

The name of the DLQ depends on the message broker, and is case-sensitive.

• KAFKA.DLQ for Kafka.
• ActiveMQ.DLQ for ActiveMQ
• PULSAR.DLQ for Pulsar

If delivery to the DLQ fails, then the message is dropped. Dropped messages are logged to the logs/smile-dlq-failures.log file for manual recovery.

19.0.5MultiTenancy and Subscriptions

Subscriptions will by default only listen to incoming resources from the same partition as the subscription. Cross-partition subscription can be enabled via the subscription.cross_partition.enabled setting, allowing subscriptions on the default partition to listen to all incoming changes. Cross-partition subscriptions will need to be distinguished using an extension on the subscription resource.

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": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-cross-partition",
        "valueBoolean": true
    } ]
}

Note that since 2024.05 cross partition is enabled by default.

19.0.6Criteria

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.

19.0.6.1In-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:

• Standard Parameters such as _id, _lastUpdated, _has, _tag, _text, _content, etc.
• Prefixes such as eq, gt, etc.
  • EXCEPTION: The following prefixes are supported for date comparisons: gt, ge, eq, lt, and le.
• Chained Parameters e.g. Patient?_has:Observation:patient:code=1234-5
• Composite Search Parameters e.g. Group?characteristic-value=gender$mixed
• Special Parameters e.g. Patient?_list=42

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.

19.0.6.2Multi-Type Criteria

HAPI FHIR and Smile CDR support a custom criteria format that can be used to match all resources of multiple resource types. This format takes the form [type1,type2,...], including the square brackets. The value inside the square brackets is a comma separated list of the resource type names you want to include. A star can be used to match all types except Subscription. For example:

• "criteria": "[Patient,Observation,Organization]" – Include all resources of type Patient, Observation, and Organization
• "[*]" – Include all resources of all types except Subscription

19.0.7Synchronization of Subscription updates

To correctly update or delete Subscription resources in a clustered Smile CDR with multiple Subscription Matcher modules, all of these modules must be restarted when subscriptions are changed or deleted.

19.0.8Troubleshooting Subscriptions

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