Release 5 Ballot
ExchangeThis page is part of the FHIR Specification (v5.0.0-ballot: R5 Ballot - see ballot notes). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions 
| FHIR Infrastructure Work Group | Maturity Level: 0 | Standards Status: Draft |
Subscriptions are used to establish proactive event notifications from a FHIR server to another system. Servers which have implemented support for Subscriptions will advertise their use via the resources Subscription and SubscriptionTopic. Interactions and operations allowed on these resources may be discovered via the FHIR Application's CapabilityStatement.
Any FHIR application may support the use of Subscriptions. In this documentation:
SubscriptionTopics, managing Subscriptions, and sending notifications.Subscription) and receiving notifications on a supported channel.rest-hook channel type the endpoint is the HTTP server listening for notifications. While part of the client, it is often useful to refer to the endpoint separately for clarity.The Subscriptions Framework in FHIR is a mechanism used to send notifications from a server to a client based on activity occurring in the server.
The Subscription mechanism is composed of three parts:
SubscriptionTopicSubscriptionTopic
Definitionally, a Subscription requires a SubscriptionTopic - without a resource describing an event or change of interest, a Subscription would have no meaning.
While active, a Subscription relies on both Bundle and SubscriptionStatus for sending notifications.
When using the Subscription resource, the FHIR server combines
the roles of publisher and information distributer. Some arrangements
of the 'publish and subscribe' pattern describe separate agents for the two roles.
This specification makes no recommendations towards the internal architecture of
server implementations.
While the FHIR REST API describes a polling-based method for observing events using bundles and the history operation, polling can cause processing delays (e.g., time between polling operations) and incur costs in:
FHIRcast is a framework for user-activity synchronization across applications. FHIRcast and Subscription are both conceptually based W3 WebSub , and while the mechanics of two projects look similar, they are fundamentally different projects used to address different use cases. In particular:
FHIRcast is designed to be used by multiple applications perhaps with the same user and typically on the same device
Subscriptions are designed to be used by multiple distinct systems, often outside of a user workflow
FHIRcast sends only single-event notifications
Subscriptions allow servers to batch multiple notifications in high-frequency scenarios
FHIRcast is designed around short-lived sessions
Subscriptions are intented to be long-lived resources
FHIR Messaging is a message-based protocol which can be used for communication. When combining Messaging and Subscriptions, complete notifications are wrapped into Messaging Bundles. More details are provided below.
This section gives an overview of the workflow for both Servers and Clients to work with Subscriptions. Each channel MAY vary slightly from this general overview - specifically around interactions involving the Endpoint (e.g., when using a rest-hook the client must pre-configure an HTTP endpoint which the server validates, but when using a websocket the client simply connects to the server).
A workflow for creating a subscription is below:
HTTP POST, HTTP PUT, etc.).
Once the subscription is active, notifications will be sent according to the channel. Note that error states may occur, see Managing Subscriptions and Errors for more information.
The SubscriptionTopic resource is used to define conceptual or computable events for Subscription resources. Conceptually, subscription topics specify:
http://example.com/fhir/events#something-interesting-happened) or by describing a resource state change in a resource trigger (e.g., an Encounter is created or updated to have an Encounter.state of active).Encounter resource, since that is the resource that is updated, it is likely desireable to include the patient information, observations, diagnosed conditions, location information, etc.Subscription Topics are intended to be discoverable, reusable, and extensible. Definitions should be computably defined whenever possible, but the conceptual definition is the arbiter between any discrepancies. For example, a query-based and a FHIRPath-based definition may differ slightly because of what is expressable in each language. In such cases, the goal is correct implementation of the concept - not literal translations between computable definitions.
More details about defining and deriving subscriptions topics can be found on the SubscriptionTopic resource page, specifically in the sections Defining Subscription Topics and Deriving from Existing Subscription Topics.
Example and Canonical Subscription Topics can be found at registry.fhir.org . It is strongly suggested that implementers reuse existing topics and submit new topics whenever possible for better compatibility.
The Subscription resource is used to request notifications for a specific client about a specific topic (as defined by a SubscriptionTopic). Conceptually, a subscription specifies: a topic (SubscriptionTopic), the notification channel (e.g., REST, websockets, email, etc.), and the notification payload (e.g., MIME type, amount of detail, etc.). Detailed information about channel-types and payload configuration can be found on the Subscription resource page.
When a FHIR Server accepts a request to create a Subscription, the server is indicating to the client that the server:
SubscriptionTopic occur, and attempt at delivering a notification for each occurance of a matching event.When processing a request for a subscription, following are some checks that a server SHOULD validate:
SubscriptionTopic is valid and implemented by the server
The SubscriptionStatus resource is used to encapsulate information about a subscription and meta-information about the notification itself (e.g., how many events are included, etc.). There are currently two areas where the resource is used: in subscription-notification Bundles and as the return type for the $status operation.
Unless otherwise specified by a server implementation and channel, the Subscriptions Framework does not involve guaranteed delivery of notifications. While the Subscriptions Framework is able to support such mechanisms, defining them is beyond the scope of the standard.
Subscribers should be aware of some limitations regarding delivery. In particular:
In order to mitigate the impact from the above issues, the Subscriptions Framework includes mechanisms to detect both scenarios. More information can be found below.
Applications are responsible for following FHIR security guidance. Some recommendations specific to subscriptions are provided below.
A subscription is a request for future event notifications. As with any client-initiated interaction, a Subscription could request information a client is not allowed to see. Applications SHALL enforce authorization in accordance with their policy requirements. Applications SHOULD take a subscription's SubscriptionTopic and filters into account when authorizing the creation of a Subscription, and SHOULD ensure that authorization is (still) in place when sending any event notifications.
When sending an event notification, applications can adopt various strategies to ensure that authorization is still in place. Some strategies may provide imperfect assurance (e.g., a server might rely on signed tokens with some pre-specified lifetime as evidence of authorization). In addition to these strategies, servers can mitigate the risk of disclosing sensitive information by limiting the payload types it supports (e.g., by prohibiting certain clients from requesting full-resource notification payloads and relying instead on id-only payloads).
Subscription resources are not intended to be secure storage for secrets (e.g., OAuth Client ID or Tokens, etc.). Implementers MAY use their judgement on including limited-use secrets (e.g., a token supplied in Subscription.header to verify that a message is from the desired source).
Each notification sent by the application could reveal information about the application and subscriber relationship, as well as sensitive administrative or clinical information. Applications are responsible for ensuring appropriate security is employed for each channel they support. The Subscription resource does not address these concerns directly; it is assumed that these are administered by other configuration processes. For instance, an application might maintain a whitelist of acceptable endpoints or trusted certificate authorities for rest-hook channels.
Some topic and server implementation combinations may trigger internal notification workflows when notifications SHOULD NOT be sent. For example, if a topic is designed around Observation resources being removed (e.g., deleted), an implementation may be triggered if an Observation is moved to a higher security level and is no longer available to a user. These types of situations are implementation-specific, so this note is to raise awareness of potential pitfalls when implementing subscriptions.
Subscribers should ensure an appropriate process to validate incoming messages. For example, if the full-resource content type is used, clients should provide a header or some other secret to the server so that messages can be verified prior to being used for health decisions. Using content types of empty or id-only can mitigate this risk, as resources must be retrieved from a trusted location prior to use.
Subscribers should be aware of, and protect against, the possibility of being used as part of an attack on a FHIR server. For example, a malicious client may send a large volume of fake notifications with empty notifications, which would cause the subscriber to send many (potentially expensive) queries to a server.
Servers implementing Subscriptions are responsible for complying with their policies on information logging. Servers are encouraged to track all sent notifications, for example with the use of AuditEvent or Communication resources.
Unless otherwise specified by a server implementation and channel, the Subscriptions Framework does not involve guaranteed delivery of notifications. While the Subscriptions Framework is able to support such mechanisms, defining them are beyond the scope of this specification.
Servers SHOULD detect errors and take appropriate action where possible. In general, this boundary is when the notification is delivered. For example, during a REST-hook notification, the subscription server can detect errors up until the REST endpoint returns a HTTP status code (e.g., 200). This does not imply that a client successfully processed (or even received) a notification - simply that the server has sent the notification successfully.
Therefore, clients SHOULD be aware of some limitations regarding delivery. In particular:
In order to mitigate the impact from the above issues, the Subscriptions Framework includes mechanisms to detect both scenarios.
The subscription resource is authored by the client with an initial status of requested. A new subscription is created on the server using the RESTful create or update interaction. After a successful "create" interaction, the client parses HTTP response's the Location header and saves the new Subscription's logical id for use in subsequent operations.
When the server receives a subscription, it SHOULD check that it is prepared to accept/process the subscription. If it is, it sets the subscription to requested and process it like a normal create. If it isn't, it SHOULD return an error with an OperationOutcome instead of processing the create.
The criteria are subject to the same limitations as the client that created it, such as access to patient compartments etc. Note that the subscription MAY remain active after the client access tokens expire (e.g., if the client's authorization period outlasts the access token lifetime).
Once the server has activated the subscription, it sets the status to active. Note that the server MAY choose to activate a subscription immediately on creation (without any additional processing).
An appropriately authorized client can use search and/or history operations to see what subscriptions are currently active on the server. Once the subscription is no longer desired, the client deletes the subscription from the server.
The server may retry the notification a fixed number of times and/or refer errors to its own alert logs. If the notification fails, the server SHOULD set the status to error and mark the error in the resource. If the notification succeeds, the server SHOULD update the status to active and may remove any error codes. If a subscription fails consistently a server may choose set the subscription status to off and stop trying to send notifications.
Errors a server wishes to make accessible to clients are stored in Subscription.error. Servers should provide a mechanism for clearing errors (e.g., when resetting a Subscription.status back to requested after an error). Since Subscription.error represents server errors, a server SHOULD NOT allow clients to add errors.
There are several mechanisms available to subscribers in order to understand the current state of notification delivery. Below are some example error scenarios with details about how a subscriber can detect the problem state.
The diagram below shows how a subscriber can use the SubscriptionStatus.eventsSinceSubscriptionStart parameter on received notifications to determine that an event has been missed.
In the above sequence, the subscriber tracks the eventsSinceSubscriptionStart of each received notification (per Subscription). When the subscriber received event 23, the subscriber was aware that the last notification it received was a single notification for event 21. The subscriber then waited an amount of time to ensure that event 22 was indeed missing (and not, for example, still being processed) and started a recovery process. The recovery process itself will vary by subscriber, but should be a well-understood method for recovering in the event of errors.
The diagram below show how a subscriber can use the Subscription.heartbeatPeriod to determine errors which prevent notifications from reaching the endpoint.
In the above sequence, the subscriber is aware that the heartbeatPeriod has elapsed for a subscription without receiving any notifications. The subscriber then asks the server for the $status of the subscription, and seeing an error, begins a recovery process. As in the previous scenario, the recovery process itself will vary by subscriber, but should be a well-understood method for recovering in the event of errors.
Clients are responsible for devising an appropriate method for recovering from errors. Often, this process will include a series or batch of requests that allow a client to know the current state or a request to the $events operation when available. For example, an application may need to query all relevant resources for a patient in order to ensure nothing has been missed. Once an application has returned to a functional state, it should request the subscription is reactivated by updating the status to either requested or active as appropriate.
$events operation
Servers MAY choose to support the $events operation, as defined on the Subscription resource. The $events operation allows clients to request events which have occurred in the past. Servers which implement the operation MAY use implementation-specific criteria to restrict availability of events (e.g., most recent 10 events, events within the past 30 days, etc.).
During a recovery process, clients MAY try to retrieve missing events via the $events operation, which should allow processing to continue as normal.
FHIR ®© HL7.org 2011+. FHIR R5 Ballot hl7.fhir.core#5.0.0-ballot generated on Sat, Sep 10, 2022 05:08+1000.
Links: Search |
Version History |
Contents |
Glossary |
QA |
Compare to R4B |
Compare to R5 Draft |
|
Propose a change