Current Build

2.48 Resource Subscription - Content

FHIR Infrastructure Work GroupMaturity Level: 3 Trial UseCompartments: Not linked to any defined compartments

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 is able to take an appropriate action.

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:

  • rest-hook: A post is made to the URL identified in the Subscription resource. If the subscription requests that the whole resource is included, the URL is interpreted as the service base
  • websocket: A PING message is sent to the designated URI
  • email/sms: A notification is sent to the nominated email address or SMS number
  • message: The resource is sent to the application identified in the URI as a message

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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Subscription ΣDomainResourceA server push subscription criteria
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... status ?!Σ1..1coderequested | active | error | off
SubscriptionStatus (Required)
... contact Σ0..*ContactPointContact details for source (e.g. troubleshooting)
... end Σ0..1instantWhen to automatically delete the subscription
... reason Σ1..1stringDescription of why this subscription was created
... criteria Σ1..1stringRule for server push criteria
... error Σ0..1stringLatest error note
... channel Σ1..1BackboneElementThe channel on which to report matches to the criteria
.... type Σ1..1coderest-hook | websocket | email | sms | message
SubscriptionChannelType (Required)
.... endpoint Σ0..1uriWhere the channel points to
.... payload Σ0..1stringMimetype to send, or omit for no payload
.... header Σ0..*stringUsage depends on the channel type
... tag Σ0..*CodingA tag to add to matching resources
SubscriptionTag (Example)

doco Documentation for this format

UML Diagram (Legend)

Subscription (DomainResource)The status of the subscription, which marks the server state for managing the subscription (this element modifies the meaning of other elements)status : code [1..1] « The status of a subscription. (Strength=Required)SubscriptionStatus! »Contact details for a human to contact about the subscription. The primary use of this for system administrator troubleshootingcontact : ContactPoint [0..*]The time for the server to turn the subscription offend : instant [0..1]A description of why this subscription is definedreason : string [1..1]The rules that the server should use to determine when to generate notifications for this subscriptioncriteria : string [1..1]A record of the last error that occurred when the server processed a notificationerror : string [0..1]A tag to add to any resource that matches the criteria, after the subscription is processedtag : Coding [0..*] « Tags to put on a resource after subscriptions have been sent. (Strength=Example)SubscriptionTag?? »ChannelThe type of channel to send notifications ontype : code [1..1] « The type of method used to execute a subscription. (Strength=Required)SubscriptionChannelType! »The uri that describes the actual end-point to send messages toendpoint : uri [0..1]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 notificationpayload : string [0..1]Additional headers / information to send as part of the notificationheader : string [0..*]Details where to send notifications when resources are received that meet the criteriachannel[1..1]

XML Template

<Subscription xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <status value="[code]"/><!-- 1..1 requested | active | error | off -->
 <contact><!-- 0..* ContactPoint Contact details for source (e.g. troubleshooting) --></contact>
 <end value="[instant]"/><!-- 0..1 When to automatically delete the subscription -->
 <reason value="[string]"/><!-- 1..1 Description of why this subscription was created -->
 <criteria value="[string]"/><!-- 1..1 Rule for server push criteria -->
 <error value="[string]"/><!-- 0..1 Latest error note -->
 <channel>  <!-- 1..1 The channel on which to report matches to the criteria -->
  <type value="[code]"/><!-- 1..1 rest-hook | websocket | email | sms | message -->
  <endpoint value="[uri]"/><!-- 0..1 Where the channel points to -->
  <payload value="[string]"/><!-- 0..1 Mimetype to send, or omit for no payload -->
  <header value="[string]"/><!-- 0..* Usage depends on the channel type -->
 </channel>
 <tag><!-- 0..* Coding A tag to add to matching resources --></tag>
</Subscription>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:Subscription;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:Subscription.status [ code ]; # 1..1 requested | active | error | off
  fhir:Subscription.contact [ ContactPoint ], ... ; # 0..* Contact details for source (e.g. troubleshooting)
  fhir:Subscription.end [ instant ]; # 0..1 When to automatically delete the subscription
  fhir:Subscription.reason [ string ]; # 1..1 Description of why this subscription was created
  fhir:Subscription.criteria [ string ]; # 1..1 Rule for server push criteria
  fhir:Subscription.error [ string ]; # 0..1 Latest error note
  fhir:Subscription.channel [ # 1..1 The channel on which to report matches to the criteria
    fhir:Subscription.channel.type [ code ]; # 1..1 rest-hook | websocket | email | sms | message
    fhir:Subscription.channel.endpoint [ uri ]; # 0..1 Where the channel points to
    fhir:Subscription.channel.payload [ string ]; # 0..1 Mimetype to send, or omit for no payload
    fhir:Subscription.channel.header [ string ], ... ; # 0..* Usage depends on the channel type
  ];
  fhir:Subscription.tag [ Coding ], ... ; # 0..* A tag to add to matching resources
]

Changes since DSTU2

Subscription
Subscription.channel.payload
  • Min Cardinality changed from 1 to 0
Subscription.channel.header
  • Max Cardinality changed from 1 to *

See the Full Difference for further information

This analysis is available as XML or JSON.

See R2 <--> R3 Conversion Maps (status = 2 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.).

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Subscription ΣDomainResourceA server push subscription criteria
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... status ?!Σ1..1coderequested | active | error | off
SubscriptionStatus (Required)
... contact Σ0..*ContactPointContact details for source (e.g. troubleshooting)
... end Σ0..1instantWhen to automatically delete the subscription
... reason Σ1..1stringDescription of why this subscription was created
... criteria Σ1..1stringRule for server push criteria
... error Σ0..1stringLatest error note
... channel Σ1..1BackboneElementThe channel on which to report matches to the criteria
.... type Σ1..1coderest-hook | websocket | email | sms | message
SubscriptionChannelType (Required)
.... endpoint Σ0..1uriWhere the channel points to
.... payload Σ0..1stringMimetype to send, or omit for no payload
.... header Σ0..*stringUsage depends on the channel type
... tag Σ0..*CodingA tag to add to matching resources
SubscriptionTag (Example)

doco Documentation for this format

UML Diagram (Legend)

Subscription (DomainResource)The status of the subscription, which marks the server state for managing the subscription (this element modifies the meaning of other elements)status : code [1..1] « The status of a subscription. (Strength=Required)SubscriptionStatus! »Contact details for a human to contact about the subscription. The primary use of this for system administrator troubleshootingcontact : ContactPoint [0..*]The time for the server to turn the subscription offend : instant [0..1]A description of why this subscription is definedreason : string [1..1]The rules that the server should use to determine when to generate notifications for this subscriptioncriteria : string [1..1]A record of the last error that occurred when the server processed a notificationerror : string [0..1]A tag to add to any resource that matches the criteria, after the subscription is processedtag : Coding [0..*] « Tags to put on a resource after subscriptions have been sent. (Strength=Example)SubscriptionTag?? »ChannelThe type of channel to send notifications ontype : code [1..1] « The type of method used to execute a subscription. (Strength=Required)SubscriptionChannelType! »The uri that describes the actual end-point to send messages toendpoint : uri [0..1]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 notificationpayload : string [0..1]Additional headers / information to send as part of the notificationheader : string [0..*]Details where to send notifications when resources are received that meet the criteriachannel[1..1]

XML Template

<Subscription xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <status value="[code]"/><!-- 1..1 requested | active | error | off -->
 <contact><!-- 0..* ContactPoint Contact details for source (e.g. troubleshooting) --></contact>
 <end value="[instant]"/><!-- 0..1 When to automatically delete the subscription -->
 <reason value="[string]"/><!-- 1..1 Description of why this subscription was created -->
 <criteria value="[string]"/><!-- 1..1 Rule for server push criteria -->
 <error value="[string]"/><!-- 0..1 Latest error note -->
 <channel>  <!-- 1..1 The channel on which to report matches to the criteria -->
  <type value="[code]"/><!-- 1..1 rest-hook | websocket | email | sms | message -->
  <endpoint value="[uri]"/><!-- 0..1 Where the channel points to -->
  <payload value="[string]"/><!-- 0..1 Mimetype to send, or omit for no payload -->
  <header value="[string]"/><!-- 0..* Usage depends on the channel type -->
 </channel>
 <tag><!-- 0..* Coding A tag to add to matching resources --></tag>
</Subscription>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:Subscription;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:Subscription.status [ code ]; # 1..1 requested | active | error | off
  fhir:Subscription.contact [ ContactPoint ], ... ; # 0..* Contact details for source (e.g. troubleshooting)
  fhir:Subscription.end [ instant ]; # 0..1 When to automatically delete the subscription
  fhir:Subscription.reason [ string ]; # 1..1 Description of why this subscription was created
  fhir:Subscription.criteria [ string ]; # 1..1 Rule for server push criteria
  fhir:Subscription.error [ string ]; # 0..1 Latest error note
  fhir:Subscription.channel [ # 1..1 The channel on which to report matches to the criteria
    fhir:Subscription.channel.type [ code ]; # 1..1 rest-hook | websocket | email | sms | message
    fhir:Subscription.channel.endpoint [ uri ]; # 0..1 Where the channel points to
    fhir:Subscription.channel.payload [ string ]; # 0..1 Mimetype to send, or omit for no payload
    fhir:Subscription.channel.header [ string ], ... ; # 0..* Usage depends on the channel type
  ];
  fhir:Subscription.tag [ Coding ], ... ; # 0..* A tag to add to matching resources
]

Changes since DSTU2

Subscription
Subscription.channel.payload
  • Min Cardinality changed from 1 to 0
Subscription.channel.header
  • Max Cardinality changed from 1 to *

See the Full Difference for further information

This analysis is available as XML or JSON.

See R2 <--> R3 Conversion Maps (status = 2 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.).

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron + JSON Schema, ShEx (for Turtle)

PathDefinitionTypeReference
Subscription.status The status of a subscription.RequiredSubscriptionStatus
Subscription.channel.type The type of method used to execute a subscription.RequiredSubscriptionChannelType
Subscription.tag Tags to put on a resource after subscriptions have been sent.ExampleSubscriptionTag

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

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.

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:

  • Client connects a secure Web Socket to the servers's webSocketUrl (see websocket extension in the server's CapabilityStatement).
  • Client authenticates to server using a server-specified Web socket protocol (e.g. OAuth bearer token presentation).
  • Client sends a bind :id message over the socket (using the logical id of the subscription). For example, the client might issue: bind 123).
  • Server responds with a "bound :id" message to acknowledge.
  • Server sends a "ping :id" message to notify the client each time a new result is available

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. 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 payload should be set to false Irrespective of size, most servers will refuse to send payloads in SMS for security reasons.

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 .

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

NameTypeDescriptionExpressionIn Common
add-tagtokenA tag to be added to the resource matching the criteriaSubscription.tag
contacttokenContact details for the subscriptionSubscription.contact
criteriastringThe search rules used to determine when to send a notificationSubscription.criteria
payloadstringThe mime-type of the notification payloadSubscription.channel.payload
statustokenThe current state of the subscriptionSubscription.status
typetokenThe type of channel for the sent notificationsSubscription.channel.type
urluriThe uri that will receive the notificationsSubscription.channel.endpoint