Path | Short | Definition | Comments |
---|---|---|---|
Server push subscription criteria | The subscription resource is used to define a push-based subscription from a server 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 a message on the defined "channel" so that another system can take an appropriate action. | ||
status | requested | active | error | off | The status of the subscription, which marks the server state for managing the subscription. | A client can only submit subscription resources in the requested or off state. Only the server can move a subscription from requested to active, and then to error. Either the server or the client can turn a subscription off. This element is labeled as a modifier because the status contains codes that mark the resource as not currently valid. |
contact | Contact details for source (e.g. troubleshooting) | Contact details for a human to contact about the subscription. The primary use of this for system administrator troubleshooting. | |
end | When to automatically delete the subscription | The time for the server to turn the subscription off. | The server is permitted to deviate from this time but should observe it. |
reason | Description of why this subscription was created | A description of why this subscription is defined. | |
criteria | Rule for server push | The rules that the server should use to determine when to generate notifications for this subscription. | The rules are search criteria (without the [base] part). Like Bundle.entry.request.url, it has no leading "/". |
error | Latest error note | A record of the last error that occurred when the server processed a notification. | |
channel | The channel on which to report matches to the criteria | Details where to send notifications when resources are received that meet the criteria. | |
channel.id | Unique id for inter-element referencing | Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. | |
channel.extension | Additional content defined by implementations | May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
channel.modifierExtension | Extensions that cannot be ignored even if unrecognized | May be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself). | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
channel.type | rest-hook | websocket | email | sms | message | The type of channel to send notifications on. | |
channel.endpoint | Where the channel points to | The url that describes the actual end-point to send messages to. | For rest-hook, and websocket, the end-point must be an http: or https: URL; for email, a mailto: url, for sms, a tel: url, and for message the endpoint can be in any form of url the server understands (usually, http: or mllp:). The URI is allowed to be relative; in which case, it is relative to the server end-point (since there may be more than one, clients should avoid using relative URIs). |
channel.payload | MIME type to send, or omit for no payload | The mime type to send the payload in - either application/fhir+xml, or application/fhir+json. If the payload is not present, then there is no payload in the notification, just a notification. The mime type "text/plain" may also be used for Email and SMS subscriptions. | Sending the payload has obvious security implications. The server is responsible for ensuring that the content is appropriately secured. |
channel.header | Usage depends on the channel type | Additional headers / information to send as part of the notification. | Exactly what these mean depend on the channel type. They can convey additional information to the recipient and/or meet security requirements; for example, support of multiple headers in the outgoing notifications for rest-hook type subscriptions. |
Once a subscription is created, any newly created or updated resources that meet the criteria in the resource cause a notification to be sent using the provided channel. The criteria are Search strings that have the same interpretation as if they were appended to the base URL and submitted using the REST API. Note that the search criteria are applied to the new value of the resource. The consequence of this is that there is no notification when a resource is deleted, or when a resource is updated so that it no longer meets the criteria.
The server is able to send notifications without any information about the matching resource, or with the entire resource.
Several different types of channels are supported:
See below for further discussion of the various channels. Note that sending the entire resource creates security concerns that must be managed by the server.
Subscriptions are active resources; a server can only accept a subscription if it will execute the specified channel for any resources subsequently received. The subscription is no longer active once it is deleted from the server.
As an alternative to subscriptions, the RESTful API describes a polling-based subscription method using bundles and the history operation. This method of polling allows for a much tighter relationship between the client and the server that doesn't involve missing updates and/or deletes.
When using the Subscription
resource, the FHIR server combines
the roles of publisher and information distributer. Other arrangements
of the publish and subscribe pattern describe separate agents for the two roles.
Implementers may implement the Subscription
resource using an
architecture with separate agents, or using any other pub/sub architectire
(e.g. see FHIRCast, or, more generally,
W3C Pub/Sub).
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 are responsible for ensuring appropriate security is employed for each channel. The subscription resource does not address these concerns directly - it is assumed that these are administered by other configuration processes. For instance, a server might maintain a whitelist of acceptable servers for the rest-create/rest-update methods.
Emails should generally be secured using some technique such as Direct.
A subscription is defined by creating the Subscription resource on the server. When the subscription is created by the client, it sets the status to "requested". After POSTing the subscription, the client parses 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 active
, and then 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 remains active after the client access tokens expire.
Once the server has activated the subscription, it sets the status to "active" (note: the server can do this as it accepts the resource if it wants).
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 again. If a subscription fails consistently a server may choose set the subscription status to off and stop trying to send notifications.
If a subscription nominates a fixed end date, the server automatically deletes it at the specified time.
Applications that wish to track whether notifications have been sent for particular resources (or versions of resources) can look at the AuditEvent resources. For example:
GET [base]/AuditEvent?entity=Patient/103
This search will return all the AuditEvent resources that are about
Patient 103
. At this time
there is no deterministic way to tell say which of those AuditEvent
resources come from the subscription sub-system that actually handles
notifications. This is planned to be resolved in a future version
of this specification. In the mean time, servers are encouraged to
create AuditEvent records when performing notifications and document
how clients can identify the relevant records when searching.
In addition, servers might also create Communication resources for some of the notifications that are sent in response to a subscription, such as when sending emails.
GET [base]/Communication?based-on=Subscription/103
This returns a list of communications sent by a subscription. TODO: search on payload....
This uses an empty POST message to alert the subscriber that new results are available - POST to [base]/Subscription:
{ "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" } }
When a resource is created or updated that meets the criteria, the server sends a POST request with no body to the nominated URL.
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 the server, appending &_since=:last
(where :last is
replaced by the time at which the client last checked). In this way it can fetch all new
relevant Observations.
Since payload is missing, the data in the resources is only available through the REST API, which helps consolidate authorization and authentication logic. The server must append the headers, if any are given, to the POST request that it makes to the client.
Alternatively, the server can be asked to send the entire resource to a nominated FHIR end-point. This is usually appropriate for defining routing rules within a managed eco-system such as a healthcare institution.
{ "channel": { "type": "rest-hook", "endpoint": "https://internal.acme.com/research/saturn", "payload": "application/fhir+json" } }
This requests that a server forward a copy of any matching resource in JSON format to the nominated server as an Update operation using the nominated URL as the service base. In order to execute this channel, the server must know how to authenticate appropriately with the destination server. This can be done by the subscription resource providing an authentication header for the server to use, or alternatively, the server may be specifically configured to be able to use the nominated server.
Subscriptions are created exclusively via the FHIR REST API. But notifications need not occur via REST. Indeed, some subscribers may be unable to expose an outward-facing HTTP server to receive triggered notifications. For example, a pure client-side Web app or mobile app may want to subscribe to a data feed without polling using the /history operation. This can be accomplished using a websocket notification channel.
A client can declare its intention to listen via Web Sockets:
{ "channel": { "type": "websocket" } }
The subscriber would then initiate a Web Socket connection to the server, at a URL advertised in the FHIR server's Capability statement (subscriptions/webSocketUrl (todo)). A simple protocol is used to listen for notifications:
A client can register for its user to receive notifications by email:
{ "channel": { "type": "email", "endpoint": "mailto:mt-auburn-results@direct.biliwatch.com", "header": "A new bilirubin result has arrived!" } }
The server would send a new message for each matching resource.
The body of the email may be empty, or it may contain a reference
to the search or the matching resource. It is at the discretion
of the server as to how much information to provide.
Subscription.channel.header
sets the subject of the
email. The email should be secured appropriately, such as using Direct, as specified
by the rules of the applicable jurisdictions.
SMS works very similarly:
{ "channel": { "type": "sms", "endpoint": "tel:+1555-345-5555" } }
Note: SMS messages are extremely limited in size, so channel.payload
will
usually be omitted (signifying that no payload is to be sent). The recipient may be
human, but this is not always the case. Irrespective of size, most servers will refuse
to send payloads in SMS for security reasons, and may refuse to send emails unless
encrypted.
A mime/type of text/plain can be useful for email and sms along with some extension describing how to convert resources to a text representation. This specification may provide supporting infrastructure for this in the future.
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 require that the end-point is white-listed prior to allowing these kinds of subscriptions.
STU Note: The details of the message - mainly the event code - are still to be resolved during the trial use period.
Feedback is welcome here.
add-tag | A tag to be added to the resource matching the criteria | undefined |
contact | Contact details for the subscription | Subscription.contact |
criteria | The search rules used to determine when to send a notification | Subscription.criteria |
payload | The mime-type of the notification payload | Subscription.channel.payload |
status | The current state of the subscription | Subscription.status |
type | The type of channel for the sent notifications | Subscription.channel.type |
url | The uri that will receive the notifications | Subscription.channel.endpoint |