This page is part of the FHIR Specification (v1.0.2: DSTU 2). The current version which supercedes this version is

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see the Directory of published versions . For a full list of available versions, see the Directory of published versions . Page versions: . Page versions: R5 R4B R4 R3 R2

• Content
• Examples
• Detailed Descriptions Detailed Descriptions
• Mappings
• Profiles Profiles & Extensions

6.14 12.20 Resource Subscription - Content Resource Subscription - Content

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.

FHIR Infrastructure FHIR Infrastructure Work Group Work Group

Maturity Level : 1 Maturity Level : 1

Compartments : Not linked to any defined compartments : 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.

6.14.3 Resource Content 12.20.3 Resource Content

 

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

6.14.3.1 Terminology Bindings 12.20.3.1 Terminology Bindings

Subscription.status Subscription.channel.type Subscription.tag

Path	Definition	Type	Reference
Subscription.status	The status of a subscription. The status of a subscription.	Required	SubscriptionStatus
Subscription.channel.type	The type of method used to execute a subscription. The type of method used to execute a subscription.	Required	SubscriptionChannelType
Subscription.tag	Tags to put on a resource after subscriptions have been sent. Tags to put on a resource after subscriptions have been sent.	Example	SubscriptionTag

6.14.4 Safety and Security 12.20.4 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 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

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

6.14.5 Managing Subscriptions and Errors 12.20.5 Managing Subscriptions and Errors A subscription is defined by creating the subscription 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.

A subscription is defined by creating the subscription 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.

6.14.6 Channels 12.20.6 Channels

6.14.6.1 12.20.6.1 REST Hook REST Hook This uses an empty POST message to alert the client that new results are available.

This uses an empty POST message to alert the client that new results are available.

POST /Subscription

{
  "resourceType": "Subscription",
  "criteria": "/Observation?name=http://loinc.org|1975-2&_format=json",
  "channel": {
    "type": "rest-hook",
    "url": "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
client
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

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

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",
    "url": "https://internal.acme.com/research/saturn",
    "payload": "application/xml+json"

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

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.

6.14.6.2 12.20.6.2 WebSockets WebSockets Subscriptions are created exclusively via the FHIR REST API. But notifications need not occur via REST. Indeed, some clients 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:

Subscriptions are created exclusively via the FHIR REST API. But notifications need not occur via REST. Indeed, some clients 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
client
would
then
initiate
a
Web
Socket
connection
to
the
server,
at
a
URL
advertised
in
the
FHIR
server's
conformance
statement
(subscriptions/webSocketUrl
(todo)).
A
simple
protocol
is
used
to
listen
for
notifications:
Client
connects
a
secure
Web
Socket
to
the
hospital's
webSocketUrl.
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

The client would then initiate a Web Socket connection to the server, at a URL advertised in the FHIR server's conformance statement (subscriptions/webSocketUrl (todo)). A simple protocol is used to listen for notifications:

• Client connects a secure Web Socket to the hospital's webSocketUrl.
• 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

6.14.6.3 12.20.6.3 Email/SMS Email/SMS A client can register for its user to receive notifications by email:

A client can register for its user to receive notifications by email:

  "channel": {
    "type": "email",
    "url": "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:

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",
    "url": "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.

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.

6.14.6.4 12.20.6.4 Messaging Messaging A client can register for its user to receive notifications by

A client can register for its user to receive notifications by messaging : :

  "channel": {
    "type": "message",
    "url": "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.
DSTU
Note:
The
details
of
the
message
-
mainly
the
event
code
-
are
still
to
be
resolved
during
the
trial
use
period.
Feedback
is
welcome
here

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.

DSTU Note: The details of the message - mainly the event code - are still to be resolved during the trial use period.

Feedback is welcome here . .

6.14.7 Search Parameters 12.20.7 Search Parameters Search parameters for this resource. The common parameters also apply. See

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

© HL7.org 2011+. FHIR DSTU2 (v1.0.2-7202) generated on Sat, Oct 24, 2015 07:44+1100. Links: Search | Version History | Table of Contents | Compare to DSTU1

Name	Type	Description	Paths
contact	token	Contact details for source (e.g. troubleshooting) Contact details for source (e.g. troubleshooting)	Subscription.contact
criteria	string	Rule for server push criteria Rule for server push criteria	Subscription.criteria
payload	string	Mimetype to send, or blank for no payload Mimetype to send, or omit for no payload	Subscription.channel.payload
status	token	requested | active | error | off requested | active | error | off	Subscription.status
tag	token	A tag to add to matching resources A tag to add to matching resources	Subscription.tag
type	token	rest-hook | websocket | email | sms | message rest-hook | websocket | email | sms | message	Subscription.channel.type
url	uri	Where the channel points to Where the channel points to	Subscription.channel.endpoint