This page is part of the Continuous Integration Build of FHIR Specification (v4.0.1: R4 - Mixed Normative and STU ) in it's permanent home (it will always (will be available incorrect/inconsistent at this URL). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see times).
See the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Content
• Examples Detailed Descriptions
• Detailed Descriptions Search Params
• Mappings
• Examples
• Operations
• Profiles & Extensions
• R3 Conversions Extensions

2.46 2.12 Resource Subscription - Content

Responsible Owner: FHIR Infrastructure Work Group

Maturity Level : 3   Trial Use Normative

Security Category : Business

Compartments : Not linked to any No defined compartments

The subscription resource is used to define a push-based subscription from describes a server particular client's request to another system. Once a subscription is registered with the server, the server checks every resource that is created or updated, and if the resource matches the given criteria, it sends be notified about a message on the defined "channel" so that another system can take an appropriate action. SubscriptionTopic.

, or, more generally, W3C Pub/Sub 2.12.3 References to this Resource ).

• Resource References: SubscriptionStatus

2.46.3 2.12.4 Resource Content

 

See the Profiles & Extensions and the alternate Additional definitions: Master Definition XML + JSON , XML Schema / Schematron + JSON Schema , ShEx (for Turtle ) + see the extensions , the spreadsheet version & the dependency analysis

2.46.3.1 2.12.4.1 Terminology Bindings

Subscription.channel.payload

Path	Definition ValueSet	Type	Reference Documentation
Subscription.status	The status of a subscription. SubscriptionStatusCodes (a valid code from Subscription Status )	Required	SubscriptionStatus State values for FHIR Subscriptions.
Subscription.filterBy.resource	SubscriptionTypes	Extensible	Types used with Subscriptions
	All Resource Types Subscription.channel.type	ui
Subscription.filterBy.comparator	The type of method used to execute a subscription. SearchComparator	Required	What Search Comparator Codes are supported in search.
Subscription.filterBy.modifier	SearchModifierCode	Required	A supported modifier for a search parameter.
Subscription.filterBy.event	Hl7VSEventTypeCode (a valid code from eventType )	Example	Concepts specifying the trigger event for Version 2.x interface messages.
Subscription.channelType	SubscriptionChannelType (a valid code from SubscriptionChannel Type Codes )	Extensible	Core-defined FHIR channel types allowed for use in Subscriptions.
Subscription.contentType	The mime type of an attachment. Any MimeTypes (a valid mime type is allowed. code from urn:ietf:bcp:13 )	Required	This value set includes all possible codes from BCP-13 (see http://tools.ietf.org/html/bcp13)
Subscription.content	Mime Types SubscriptionPayloadContent	Required	Codes to represent how much resource content to send in notification payloads.

2.12.4.2 Constraints

2.46.4 2.12.5 Safety and Security

Executing each of the channels documented below involves the server sending a communication that will reveal information about the client and server relationship, and, if the entire resource is sent, administrative or clinical information that may be quite sensitive and/or protected under law. Servers Applications are responsible for ensuring appropriate following FHIR security is employed for each channel. The subscription resource does not address these concerns directly - it is assumed that these guidance . Some recommendations specific to subscriptions are administered by other configuration processes. For instance, a server might maintain a whitelist of acceptable servers for provided on the rest-create/rest-update methods. Emails should generally be secured using some technique such as Direct . Subscriptions Framework page.

2.46.5 2.12.6 Managing Multi-Resource Subscriptions and Errors

A subscription is defined by creating As indicated on the Subscription Subscriptions Framework and SubscriptionTopic resource pages, subscriptions can have more than a single resource in scope (e.g., a subscription that triggers on both Condition and Observation resources, a topic tied to all resources, etc.). If there are filters that do not apply to every resource available in a topic, clients SHOULD ensure that the server. When the subscription Subscription.filterBy.resourceType element is created by the client, it sets the status to "requested". After POSTing filled appropriately. More detail can be found in the subscription, Filters and Resource Types section of the client parses Subscriptions Framework page.

2.12.7 Notification Content

There are three options available when specifying the Location header amount of content a notification will contain: empty , id-only , and saves full-resource . These options change the new Subscription's logical id for use level of detail conveyed in subsequent operations. the notification Bundle .

When deciding which payload type to request, systems SHOULD consider both ease of processing and security of PHI (Personal health information). To mitigate the server receives a subscription, it risk of information leakage, systems SHOULD check that it is prepared to accept/process use the subscription. If it is, it sets minimum level of detail consistent with the subscription to use case. In practice, active , and then process it like id-only provides a normal create . good balance between security and performance for many real-world scenarios.

If it isn't, a server cannot or will not honor a payload type (e.g., will not send full-resource over HTTP), it SHOULD reject the Subscription request. A server MAY instead accept the subscription with modifications and return an error the accepted and modified version to the client.

When sending event notifications servers SHALL populate the SubscriptionStatus.notificationEvent structure with relevant information, depending on the payload type.

2.12.7.1 empty

An example notification with an OperationOutcome empty payload can be found here .

With the content type of empty , all information about the resources involved in triggering the notification is only available via channels other than the Subscription itself (e.g., the REST API or $events instead operation). This mitigates many security concerns by both removing most PHI from the notification and allows servers to consolidate authorization and authentication logic. When the subscriber receives a notification of processing this type, it may query the server to fetch all the relevant resources based on the create . SubscriptionTopic and applicable filters. The criteria are subject client might include a _lastUpdated query parameter, supplying its last query timestamp to retrieve only the same limitations as most recent resources. For example, if the client that created it, such notification is for a topic about patient admission, the subscriber will generally query for recent Encounters for a patient or group of patients, then fetch them as access needed.

When populating the SubscriptionStatus.notificationEvent structure for a notification with an empty payload, a server SHALL NOT include references to patient compartments etc. Note that resources (e.g., SubscriptionStatus.notificationEvent.focus and SubscriptionStatus.notificationEvent.additionalContext SHALL NOT be present).

When the subscription remains active after content type is empty , notification bundles SHALL NOT contain Bundle.entry elements other than the client access tokens expire. SubscriptionStatus for the notification.

2.12.7.2 id-only

Once An example notification with an id-only payload can be found here .

With the server has activated content type of id-only , the subscription, it sets resources involved in triggering the status notification are only available through other channels (e.g., REST API), but notifications include URLs which can be used to "active" (note: access those resources. This allows servers to consolidate authorization and authentication logic, while removing the server can do need for expensive queries by subscribers. When a subscriber receives a notification of this as type, it accepts may directly fetch all the relevant resources using the supplied resource ids. For example, if it wants). the notification is for a topic about patient admission, the subscriber may fetch the Encounter(s) for a patient or group of patients.

An appropriately authorized client can use search and/or history operations to see what subscriptions are currently active on the server. Once When the subscription content type is no longer desired, id-only , the client deletes SubscriptionStatus.notificationEvent structure SHALL include references to the subscription from appropriate focus resources in the server. SubscriptionStatus.notificationEvent.focus element. This provides clients a fixed location to consolidate IDs for all notification types.

The server may retry Additionally, notification bundles MAY contain, in addition to the SubscriptionStatus , at least one Bundle.entry for each resource relevant to the notification. For example, a notification for a fixed number of times and/or refer errors topic based on Encounter MAY include a reference to its own alert logs. If the notification fails, Encounter and MAY also include additional resources deemed relevant (e.g., the server should set linked Patient).

2.12.7.3 full-resource

An example notification with a full-resource payload can be found here .

With the status to 'error' and mark content type of full-resource , the error resources involved in triggering the resource. If notification are included in the notification succeeds, bundle. When a subscriber receives a notification of this type, resources are already present in the server should update bundle, though the status subscriber may need to "active again. If a subscription fails consistently fetch additional resources from the server. For example, the if the notification is for a server topic about patient admission, the subscriber may choose set require related Observation resources.

When the subscription status content type is full-resource , the SubscriptionStatus.notificationEvent structure SHALL include references to off and stop trying the appropriate focus resources in the SubscriptionStatus.notificationEvent.focus element. This provides clients a fixed location to send notifications. consolidate IDs for all notification types.

Notification bundles for full-resource subscriptions SHALL contain, in addition to the SubscriptionStatus , at least one Bundle.entry for each resource relevant to the notification. For example, a notification for a topic based on Encounter SHALL include an Encounter and MAY include additional resources deemed relevant (e.g., the relevant Patient). Each Bundle.entry for a full-resource notification SHALL contain a relevant resource in the entry.resource element. If a subscription nominates server cannot include the resource contents due to an issue with a fixed end date, specific notification, the server automatically deletes it at SHALL populate the specified time. entry.request and/or entry.response elements.

2.46.6 2.12.8 Tracking Subscription Notifications Batching Results

Applications that wish Subscriptions allow servers to track whether batch multiple notifications have been sent for particular resources (or versions of resources) can look at the AuditEvent resources. into a single subscription-notification Bundle. For example: GET [base]/AuditEvent?entity=Patient/103 This search will return all the AuditEvent resources example, if a server has a high-frequency of updates (e.g., several per second), it could be beneficial to combine notifications to reduce traffic and overhead. Note that are about Patient servers SHALL NOT delay sending notification longer than time span specified by 103 Subscription.heartbeat . At this time there is no deterministic way

The Subscription.maxCount element allows clients to tell say which of those AuditEvent resources come from specify the subscription sub-system maximum number of events that actually handles notifications. This is planned to can be resolved combined in a future version of this specification. In the mean time, single notification. When present, servers are encouraged to create AuditEvent records when performing notifications and document how clients can identify SHALL NOT include more than the relevant records when searching. In addition, servers might also create Communication resources for some specified number of the notifications that are sent events in response to a subscription, such as when sending emails. GET [base]/Communication?based-on=Subscription/103 This returns notification bundle. Note that this is not a list strict limit on the total number of communications sent by entries in a subscription. TODO: search on payload.... bundle, as dependent resources (e.g., included related resources) can be present in Bundles, in addition to the event notifications.

2.46.7 2.12.9 Channels

2.46.7.1

2.12.9.1 REST Hook Deciding on Channel Type

This uses an empty POST message specification defines a core set of channel types to alert cover the subscriber that new results are available - POST majority of common use cases. Servers MAY define additional channel types as needed. Below is some guidance for implementers to [base]/Subscription: consider when selecting a channel type.

{ "resourceType": "Subscription", "criteria": "Observation?name=http://loinc.org|1975-2&_format=json", "channel": { "type": "rest-hook", "endpoint": "https://biliwatch.com/customers/mount-auburn-miu/on-result", "header": "Authorization: Bearer secret-token-abc-123" } }

2.12.9.1.1 REST-Hook

When a resource is created or updated that meets The FHIR standard makes extensive use of the criteria, RESTful model. Given the server sends a POST request with no body to popularity of REST and widespread adoption, most implementers should consider using REST-hook channels whenever possible. In general, REST-based systems are well-supported (e.g., tooling, infrastructure, documentation, etc.), and will present the nominated URL. lowest bar for implementation.

2.12.9.1.2 Websocket

When the subscriber receives a POST to https://biliwatch.com/customers/mount-auburn-miu/on-result , it re-issues the criteria as a query to Websockets are unique in the server, appending &_since=:last (where :last is replaced by pre-defined channel types in being the time at which only channel that does not require the client last checked). In to have an endpoint. Due to this way it can fetch all new relevant Observations . property, the websocket channel is very useful for clients where creating an endpoint would be difficult or impossible (e.g., mobile clients, web-based clients, etc.).

Since payload The websocket channel type is missing, the data still undergoing testing and refinement - current details can be found in the resources FHIR Subscriptions Backport Implementation Guide .

2.12.9.1.3 Email

The Email channel is only available through the only channel that could contest REST API, which helps consolidate authorization in non-FHIR implementations. That said, Email communication is often high-latency and authentication logic. The server must append is typically used for communication to individuals - not applications. Email channels are particularly useful in the headers, context of these non-application use cases, such as public health notifications. For example, if any are given, to a public health agency does not have the POST request that ability or desire to build a custom RESTful solution (e.g., creating and maintaining an endpoint to receive notifications, as well as software to consume those notifications), it makes is straightforward to the client. map notifications to email addresses or aliases.

2.12.9.1.4 FHIR Messaging

Alternatively, the server can be asked to send the entire resource to FHIR Messaging is a nominated mechanism defined to allow for non-RESTful communication between FHIR end-point. This servers and clients. One common use case is usually appropriate when connectivity is an issue (e.g., remote sites that batch all communications when connections are available). This channel defines how to integrate topic-based subscriptions with the FHIR Messaging model.

2.12.9.1.5 Custom Channels

For use cases that are not well-met by any of the predefined channels, the Subscriptions Framework allows for defining routing rules within custom channel definitions. Some examples of scenarios where custom channels may be applicable include:

• requirements for reliable (guaranteed) delivery (e.g., message queues)
• implementations using other communication protocols (e.g., protocols specific to a managed eco-system such as cloud-based provider)
• implementations using a healthcare institution. { "channel": { "type": "rest-hook", "endpoint": "https://internal.acme.com/research/saturn", "payload": "application/fhir+json" } } non-standard serialization format

2.12.9.2 REST Hook

This requests that To receive notifications via HTTP/S POST, a server forward client requests a copy subscription with the channel type of any matching resource in JSON format to `rest-hook` (from the nominated server as subscription-channel-type Code System) and and an Update operation using endpoint ( Subscription.endpoint ) with the nominated desired URL. Note that this URL as must be accessible by the service base . In order to execute this channel, hosting server.

To convey an event notification, the server must know how POSTs a notification Bundle to authenticate appropriately with the destination server. This can be done by client's nominated endpoint URL per the subscription resource providing format requests in the Subscription:

• The content-type of the POST SHALL match the MIME type on the Subscription Subscription.contentType .
• Each Subscription.parameter indicates an authentication HTTP request header and SHALL be sent as {parameter.name}: {parameter.value} .

When a subscription is created for a REST Hook channel type, the server SHALL set initial status to use, or alternatively, requested , pending verification of the nominated endpoint URL. After a successful handshake notification has been sent and accepted, the server may be specifically configured to be able SHALL update the status to use active . Any errors in the nominated server. initial handshake SHALL result in the status being changed to error .

An example workflow for establishing a rest-hook subscription is shown below.

1. Client creates a Subscription with the channelType set to rest-hook .
2. Server responds with a success code and creates the subscription with a state of requested .
3. Server performs an HTTP POST to the requested endpoint with a handshake notification.
4. Client Endpoint accepts the POST and returns a success HTTP code (e.g., 200 ).
5. Server sends a notification of type heartbeat at any time (SHOULD at least once per heartbeatPeriod ).
6. Client Endpoint accepts a heartbeat via HTTP POST and returns an HTTP success code (e.g., 200 ).
7. Server sends a notification of type event-notification when triggered.
8. Client Endpoint accepts an event-notification via HTTP POST and returns an HTTP code (e.g., 200 ).

2.46.7.2 2.12.9.2.1 Channel Security Notes

HTTP is neither a secure nor an encrypted channel, nor does it provide endpoint verification. It is strongly recommended that implementations refuse requests to send notifications to URLs using the HTTP protocol (use HTTPS instead).

2.12.9.3 WebSockets Email

Subscriptions are created exclusively via While the primary interface for FHIR servers is the FHIR REST API. But API, notifications need not occur via REST. Indeed, some subscribers may be unable to expose maintain an outward-facing HTTP server to receive triggered notifications. For example, a pure client-side Web app or mobile app public health organization may want to subscribe to a data feed without polling using the /history operation. be notified of outbreaks of various illnesses. This can be accomplished using a websocket an email notification channel.

A client can declare its intention to listen To receive notifications via Web Sockets: Email, a client requests a subscription with the channel type ( Subscription.channelType ) of email (from the subscription-channel-type Code System) and an endpoint ( Subscription.endpoint ) with the desired email URI (e.g., mailto:public_health_notifications@example.org ).

{ "channel": { "type": "websocket" } }

The subscriber would then initiate server will send a Web Socket connection to the server, at new message each time a URL advertised notification should be sent (e.g., per event or per batch). The server will create a message based on the values present in the FHIR server's Capability statement (subscriptions/webSocketUrl (todo)). A simple protocol is used Subscription.contentType and Subscription.content fields. If a server cannot honor the requested combination, the server should reject the Subscription request rather than send unexpected email messages.

The email channel sets two guidelines about content:

• Message Body content SHALL be human readable
• Message Attachments SHOULD be machine readable

Due to listen these guidelines, the Subscription.contentType refers to the content of the body of the message. Attachment type information can be appended as a MIME parameter, for notifications: example:

• Client connects text/plain : a secure Web Socket plain-text body with no attachment
• text/html : an HTML body with no attachment
• text/plain;attach=application/fhir+json : a plain-text body with a FHIR JSON bundle attached
• text/html;attach=application/fhir+xml : an HTML body with a FHIR XML bundle attached

The Subscription.content field SHALL be applied to any attachments, and MAY be applied to body contents (depending on server implementation). However, a server must not include a body which exceeds the server's webSocketUrl (see websocket extension specified content level. For example, a server may choose to always include a standard message in the server's CapabilityStatement ). Client authenticates body of the message containing no PHI and vary the attachment, but cannot include PHI in the body of an email when the content is set to server empty .

An example workflow using the email channel type is included below.

1. Client sends creates a bind :id message over Subscription with the socket (using channelType set to email .
2. Server MAY respond with a success code and create the logical id subscription with a state of active .
3. Server MAY respond with a success code and create the subscription). For example, subscription with a state of requested .
4. Server sends an initial message via the client might issue: bind 123). specified email server (e.g., verify the request, opt-out instructions, etc.).
5. Email Server responds with a "bound :id" message to acknowledge. channel appropriate response code (e.g., 250: OK ).
6. Server sends may send an email for a "ping :id" message to notify the client each notification of type heartbeat at any time (SHOULD at least once per heartbeatPeriod ).
7. Server may send an email for a new result is available notification of type event-notification at any time.

2.46.7.3

2.12.9.3.1 Email/SMS Channel Security Notes

A client can register for its user Email (SMTP) is not a secure channel. Implementers must ensure that any messages containing PHI have been secured according to receive notifications by email: their policy requirements (e.g., use of a system such as Direct ).

{ "channel": { "type": "email", "endpoint": "mailto:mt-auburn-results@direct.biliwatch.com", "header": "A new bilirubin result has arrived!" } }

2.12.9.4 Messaging

The server would send There are times when it is desirable to use Subscriptions as a new message for each matching resource. The body communication channel between FHIR servers that are connected via Messaging instead of the email may REST. This can be empty, or it may contain accomplished using a reference to the search or Subscription with the matching resource. It is at channel type of message .

To receive notifications via messaging, a client should request a subscription with the discretion channel type ( Subscription.channelType ) of message and set the server as to how much information to provide. endpoint ( Subscription.channel.header Subscription.endpoint sets ) to the subject of destination FHIR server base URL. Note that this URL must be accessible by the email. hosting server.

The email should be secured appropriately, such FHIR server hosting the subscription (server) will send FHIR messages to the destination FHIR server (endpoint) as using Direct, needed. These messages will, as specified by the rules contents of the applicable jurisdictions. SMS works very similarly: message, have a fully-formed subscription-notification Bundle. An example message can be found here .

{ "channel": { "type": "sms", "endpoint": "tel:+1555-345-5555" } }

Note: SMS messages are extremely limited in size, so An example workflow using the channel.payload message will usually be omitted (signifying that no payload channel type is included below.

1. Client creates a Subscription with the channelType set to be sent). The recipient may be human, but this is not always message .
2. Server responds with a success code and creates the case. Irrespective subscription with a state of size, most servers will refuse requested .
3. Server sends a FHIR Message to send payloads in SMS for security reasons, the requested endpoint with a handshake notification.
4. Client Endpoint accepts the Message and returns success.
5. Server may refuse to send emails unless encrypted. A mime/type a Message containing a notification of text/plain can be useful for email and sms along with some extension describing how type heartbeat at any time (SHOULD at least once per heartbeatPeriod ).
6. Server may send a Message containing a notification of type event-notification at any time.

Note to convert resources Implementers: The Messaging channel type needs more testing and feedback to a text representation. This specification may provide supporting infrastructure for this in ensure all requirements are met before finalizing the future. specification.

2.46.7.4

2.12.9.4.1 Messaging Channel Security Notes A client can register for its user to receive notifications by messaging : { "channel": { "type": "message", "endpoint": "http://ehr.example.org/fhir/$process-message" } }

For each matching resource, a server will send a message to the nominated end-point. Most servers will Servers MAY require that the end-point is white-listed prior to allowing these kinds of subscriptions. Additionally, servers MAY impose authorization/authentication requirements for server to server communication (e.g., certificate pinning, etc.).

2.12.10 Defining Channel Types

Defining a new channel type requires clear communication to implementers of both clients and servers around requirements and expectations. Below are some areas which should be considered when creating a channel. Anyone defining a channel type is encouraged to publish their definition at registry.fhir.org .

STU Note: Note to Implementers: The details of Warning: This section is still in early drafting; feedback from topic authors is welcome to refine the message - mainly following guidance.

2.12.10.1 Channel Basics

At a minimum, the event following items should be defined:

• A system for Subscription.channelType that reflects the publisher of the definition (e.g., "https://myorg.example.org" instead of "urn:uuid:be35238b-0ed6-4062-93cf-818b8023a103")
• A generally descriptive code - for Subscription.channelType (e.g., 'secure-mq' instead of 'channel')
• The type of data required in Subscription.endpoint (e.g., URI, etc.)
• The meaning of Subscription.parameter field values (e.g., REST-hook defines as HTTP headers included in a POST). Note that channels can specify general behavior and/or specific parameters by name .
• Any additions or variations on MIME types for Subscription.contentType (e.g., email defines this as the email body, with allowable attachments.)
• Whether handshake notifications are still used, and guidance on usage if they are
• Whether heartbeat notifications are used, and guidance on timings if they are

2.12.10.2 Channel Security Considerations

Defining a channel has security implications. While it is not expected that authors cover all aspects of security, guidance specific to be resolved during the trial use period. channel SHOULD be provided. For example, when discussing REST-hooks, this specification includes guidance about using HTTPS over HTTP.

Feedback If the channel CANNOT be secured, that should be stated with a warning not to transfer PHI. If the channel is welcome here or can be secured, guidance should be given on how configurations relate to PHI safety, for example:

• Does the channel determine the legitimacy of both endpoints?
• Is the channel secure from third-party monitoring?

.

2.12.11 Managing Subscriptions and Errors

Subscriptions can be used to manage long-lived requests for notifications. For details about management and expectations regarding errors, see Managing Subscriptions and Errors on the Subscriptions Framework page.

2.12.12 Authorization Hinting in Notifications

It can be appropriate for a server to include authorization information alongside notifications. This information could be used to inform a recipient about how authorization should be done when querying-for or retrieving resources from a notification (e.g., when querying based on an empty notification), or to provide tokens or other information needed to access resources referenced in the notification (e.g., when retrieving resources based on an id-only notification).

Depending on the channel used, notifications MAY or MAY NOT be secure from third parties. Implementers SHOULD ensure that any authorization information included complies with security best practices (e.g., providing a token exchanged during an OAuth workflow, along with other data such as a client authentication token, for an access token).

When including authorization information in a notification, servers SHOULD use security best practices (e.g., short-lived and single-use tokens, temporary access codes, etc). For more information, see the FHIR Security Guidance document.

2.46.8 2.12.13 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
contact	token	Contact details for the subscription	Subscription.contact
content-level	token	Content level included in notifications	Subscription.content
filter-event	token criteria	Filter event used to narrow notifications	Subscription.filterBy.event
filter-value	string	The search rules Filter value used to determine when to send a notification narrow notifications	Subscription.filterBy.value
identifier	token	Subscription.criteria A subscription identifier	Subscription.identifier
name	string	A human-readable name	Subscription.name
owner	reference	The managing entity	Subscription.managingEntity ( Practitioner , Group , Organization , CareTeam , Device , Patient , HealthcareService , PractitionerRole , RelatedPerson )
payload	token	The mime-type of the notification payload notifications	Subscription.channel.payload Subscription.contentType
status	token	The current state of the subscription	Subscription.status
topic	uri	The canonical topic url that triggers notifications	Subscription.topic
type	token	The type of channel for the sent notifications	Subscription.channel.type Subscription.channelType
url	uri	The uri that will receive the notifications	Subscription.channel.endpoint Subscription.endpoint