Release 4 5 Preview #3
This page is part of the FHIR Specification (v4.0.1: R4 - Mixed Normative and STU ). This is the current published version in it's permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions

2.46 2.47 Resource Subscription - Content

FHIR Infrastructure Work Group Maturity Level : 3 2   Trial Use Security Category : Business Compartments : Not linked to any 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.

This document contains information about the Subscription resource and details specific to options in it. See Subscriptions for general information about using Subscriptions in FHIR.

The Subscription resource is used to establish proactive event notifications from a FHIR server to another system. Subscribers request event notifications within a predefined SubscriptionTopic that the server supports, and can further refine their notifications by supplying filters. Each SubscriptionTopic resource defines a set of allowed filters ( SubscriptionTopic.canFilterBy ), which a subscriber refer to within a Subscription resource ( Subscription.filterBy ). Once a subscription is created, any newly created or updated resources event matching a specified SubscriptionTopic that meet meets the filtering criteria in the resource will cause a notification to be sent using the provided channel. The criteria Notifications are Search Bundle 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 resources, of this is that there is no notification when type subscription-notification .

Subscriptions are active resources; a resource is deleted, or when server can only accept a resource is updated so that subscription if it will execute the specified channel for any resources subsequently received. The subscription is no longer meets active once it is deleted from the criteria. server.

The server is able to send By adjusting Subscription.content , subscribers can request event notifications without any information about the matching resource, that include full resource content; or with just the entire resource. ID of the triggering resource; or an empty notification body.

Several different types of channels are supported: defined in the core specification:

  • rest-hook : A post is made : Notifications are sent via HTTPS POST to the Subscription.endpoint URL identified in the Subscription resource. If the subscription requests that the whole resource is included, the URL is interpreted as the service base (e.g., https://... )
  • websocket : A PING message is : Notifications are sent via WS/S to the designated URI a client connected via a WebSocket
  • email/sms : A notification is email : Notifications are sent via SMTP/S, S/MIME, or Direct SMTP to the nominated Subscription.endpoint email address or SMS number URI (e.g., mailto:... )
  • message : The resource is : Notifications are sent via FHIR messaging to the application identified in the Subscription.endpoint URI as a message

Additional channel types can be defined by external implementation guides. 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 The Subscription resource, resource is used in the FHIR server combines Subscriptions Framework . Information about the roles of publisher Boundaries and information distributer. Other arrangements of Relationships both within the publish Subscriptions Framework 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 to other pub/sub architectire (e.g. see FHIRCast areas of the FHIR specification can be found here .

This resource is referenced by SubscriptionStatus .

This resource does not implement any patterns.

Structure

Name Flags Card. Type Description & Constraints doco
. . Subscription Σ TU DomainResource Server push subscription criteria Notification about a SubscriptionTopic
Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
. . . identifier Σ 0..* Identifier Additional identifiers (business identifier)
... name Σ 0..1 string Human readable name for this subscription
. . . status ?! Σ 1..1 code requested | active | error | off | entered-in-error
SubscriptionStatus Subscription State ( Required )
... contact Σ 0..* ContactPoint Contact details for source (e.g. troubleshooting)
. . . end Σ 0..1 instant When to automatically delete the subscription
. . . reason Σ 1..1 0..1 string Description of why this subscription was created
. . . filterBy Σ 0..* BackboneElement Criteria for narrowing the subscription topic stream
.. . . criteria resourceType Σ 1..1 0..1 string uri Rule Allowed Data type or Resource (reference to definition) for server push this Subscription
FHIRDefinedType ( Extensible )
. . . . error searchParamName Σ 0..1 1..1 string Latest error note Filter label defined in SubscriptionTopic
. . channel . . searchModifier Σ 1..1 0..1 BackboneElement code The channel on which to report matches to the criteria = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
Subscription Search Modifier ( Required )
. . . . type value Σ 1..1 code string rest-hook | websocket | email | sms | message Literal value or resource path
... channelType Σ 1..1 Coding Channel type for notifications
SubscriptionChannelType Subscription Channel Type ( Required Extensible )
. . . endpoint Σ 0..1 url Where the channel points to
. . . header Σ 0..* string Usage depends on the channel type
. . . payload heartbeatPeriod Σ 0..1 unsignedInt Interval in seconds to send 'heartbeat' notification
... timeout Σ 0..1 unsignedInt Timeout in seconds to attempt notification delivery
... contentType Σ 0..1 code MIME type to send, or omit for no payload
MimeType ( Required )
. . . header content Σ 0..* 0..1 string code Usage depends on the channel type empty | id-only | full-resource
SubscriptionPayloadContent ( Required )
... notificationUrlLocation Σ 0..1 code none | full-url | request-response | all
SubscriptionUrlLocation ( Required )
... maxCount Σ 0..1 positiveInt Maximum number of triggering resources included in notification bundles

doco Documentation for this format

UML Diagram ( Legend )

Subscription ( DomainResource ) A formal identifier that is used to identify this code system when it is represented in other formats, or referenced in a specification, model, design or an instance identifier : Identifier [0..*] A natural language name identifying the subscription name : string [0..1] 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 SubscriptionState ! » The reference to the subscription topic to be notified about topic : canonical [1..1] « SubscriptionTopic » Contact details for a human to contact about the subscription. The primary use of this for system administrator troubleshooting contact : ContactPoint [0..*] The time for the server to turn the subscription off end : instant [0..1] A description of why this subscription is defined reason : string [1..1] The rules that the server should use to determine when to generate notifications for this subscription criteria : string [1..1] A record of the last error that occurred when the server processed a notification error : string [0..1] Channel The type of channel to send notifications on type channelType : code Coding [1..1] « The type of method used to execute a subscription. (Strength=Required) (Strength=Extensible) SubscriptionChannelType ! + » The url that describes the actual end-point to send messages to endpoint : url [0..1] Additional headers / information to send as part of the notification header : string [0..*] If present, a 'hearbeat" notification (keepalive) is sent via this channel with an the interval period equal to this elements integer value in seconds. If not present, a heartbeat notification is not sent heartbeatPeriod : unsignedInt [0..1] If present, the maximum amount of time a server will allow before failing a notification attempt timeout : unsignedInt [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 notification. The mime type MIME types "text/plain" and "text/html" may also be used for Email and SMS subscriptions payload contentType : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required) Mime Types ! » Additional headers / information How much of the resource content to deliver in the notification payload. The choices are an empty payload, only the resource id, or the full resource content content : code [0..1] « Codes to represent how much resource content to send as part in the notification payload. (Strength=Required) SubscriptionPayloadContent ! » If present, where to place URLs of resources in notifications notificationUrlLocation : code [0..1] « The location, in Bundle.entry, where URLs for resources should be located. (Strength=Required) SubscriptionUrlLocation ! » If present, the maximum number of triggering resources that will be included in a notification bundle (e.g., a server will not include more than this number of trigger resources in a single notification). Note that this is not a strict limit on the number of entries in a bundle, as dependent resources can be included header maxCount : positiveInt [0..1] FilterBy If the element is a reference to another resource, this element contains "Reference", and the targetProfile element defines what resources can be referenced. The targetProfile may be a reference to the general definition of a resource (e.g. http://hl7.org/fhir/StructureDefinition/Patient) resourceType : uri [0..1] « Either a resource or a data type, including logical model types. (Strength=Extensible) FHIRDefinedType + » The filter label (=key) as defined in the `SubscriptionTopic.canfilterBy.searchParamName` element searchParamName : string [0..*] [1..1] The operator to apply to the filter value when determining matches (Search modifiers) searchModifier : code [0..1] « Operator to apply to filter label. (Strength=Required) SubscriptionSearchModifier ! » The literal value or resource path as is legal in search - for example, "Patient/123" or "le1950" value : string [1..1] Details where The filter properties to send notifications when resources be applied to narrow the subscription topic stream. When multiple filters are received that meet applied, evaluates to true if all the criteria conditions are met; otherwise it returns false. (i.e., logical AND) channel filterBy [1..1] [0..*]

XML Template

<Subscription xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <

 <identifier><!-- 0..* Identifier Additional identifiers (business identifier) --></identifier>
 <name value="[string]"/><!-- 0..1 Human readable name for this subscription -->
 <status value="[code]"/><!-- 1..1 requested | active | error | off | entered-in-error -->
 <topic><!-- 1..1 canonical(SubscriptionTopic) Reference to the subscription topic being subscribed to --></topic>

 <contact><!-- 0..* ContactPoint Contact details for source (e.g. troubleshooting) --></contact>
 <end value="[instant]"/><!-- 0..1 When to automatically delete the subscription -->
 <
 <
 <
 <
  <
  <
  <
  <
 </channel>

 <reason value="[string]"/><!-- 0..1 Description of why this subscription was created -->
 <filterBy>  <!-- 0..* Criteria for narrowing the subscription topic stream -->
  <resourceType value="[uri]"/><!-- 0..1 Allowed Data type or Resource (reference to definition) for this Subscription -->
  <searchParamName value="[string]"/><!-- 1..1 Filter label defined in SubscriptionTopic -->
  <searchModifier value="[code]"/><!-- 0..1 = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type -->
  <value value="[string]"/><!-- 1..1 Literal value or resource path -->
 </filterBy>
 <channelType><!-- 1..1 Coding Channel type for notifications --></channelType>
 <endpoint value="[url]"/><!-- 0..1 Where the channel points to -->
 <header value="[string]"/><!-- 0..* Usage depends on the channel type -->
 <heartbeatPeriod value="[unsignedInt]"/><!-- 0..1 Interval in seconds to send 'heartbeat' notification -->
 <timeout value="[unsignedInt]"/><!-- 0..1 Timeout in seconds to attempt notification delivery -->
 <contentType value="[code]"/><!-- 0..1 MIME type to send, or omit for no payload -->
 <content value="[code]"/><!-- 0..1 empty | id-only | full-resource -->
 <notificationUrlLocation value="[code]"/><!-- 0..1 none | full-url | request-response | all -->
 <maxCount value="[positiveInt]"/><!-- 0..1 Maximum number of triggering resources included in notification bundles -->

</Subscription>

JSON Template

{doco
  "resourceType" : "",

  "resourceType" : "Subscription",

  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "

  "identifier" : [{ Identifier }], // Additional identifiers (business identifier)
  "name" : "<string>", // Human readable name for this subscription
  "status" : "<code>", // R!  requested | active | error | off | entered-in-error
  "topic" : { canonical(SubscriptionTopic) }, // R!  Reference to the subscription topic being subscribed to

  "contact" : [{ ContactPoint }], // Contact details for source (e.g. troubleshooting)
  "end" : "<instant>", // When to automatically delete the subscription
  "
  "
  "
  "
    "
    "
    "
    "
  }

  "reason" : "<string>", // Description of why this subscription was created
  "filterBy" : [{ // Criteria for narrowing the subscription topic stream
    "resourceType" : "<uri>", // Allowed Data type or Resource (reference to definition) for this Subscription
    "searchParamName" : "<string>", // R!  Filter label defined in SubscriptionTopic
    "searchModifier" : "<code>", // = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
    "value" : "<string>" // R!  Literal value or resource path
  }],
  "channelType" : { Coding }, // R!  Channel type for notifications
  "endpoint" : "<url>", // Where the channel points to
  "header" : ["<string>"], // Usage depends on the channel type
  "heartbeatPeriod" : "<unsignedInt>", // Interval in seconds to send 'heartbeat' notification
  "timeout" : "<unsignedInt>", // Timeout in seconds to attempt notification delivery
  "contentType" : "<code>", // MIME type to send, or omit for no payload
  "content" : "<code>", // empty | id-only | full-resource
  "notificationUrlLocation" : "<code>", // none | full-url | request-response | all
  "maxCount" : "<positiveInt>" // Maximum number of triggering resources included in notification bundles

}

Turtle Template

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

[ 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:

  fhir:Subscription.identifier [ Identifier ], ... ; # 0..* Additional identifiers (business identifier)
  fhir:Subscription.name [ string ]; # 0..1 Human readable name for this subscription
  fhir:Subscription.status [ code ]; # 1..1 requested | active | error | off | entered-in-error
  fhir:Subscription.topic [ canonical(SubscriptionTopic) ]; # 1..1 Reference to the subscription topic being subscribed to

  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:
  fhir:
  fhir:
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
  ];

  fhir:Subscription.reason [ string ]; # 0..1 Description of why this subscription was created
  fhir:Subscription.filterBy [ # 0..* Criteria for narrowing the subscription topic stream
    fhir:Subscription.filterBy.resourceType [ uri ]; # 0..1 Allowed Data type or Resource (reference to definition) for this Subscription
    fhir:Subscription.filterBy.searchParamName [ string ]; # 1..1 Filter label defined in SubscriptionTopic
    fhir:Subscription.filterBy.searchModifier [ code ]; # 0..1 = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
    fhir:Subscription.filterBy.value [ string ]; # 1..1 Literal value or resource path
  ], ...;
  fhir:Subscription.channelType [ Coding ]; # 1..1 Channel type for notifications
  fhir:Subscription.endpoint [ url ]; # 0..1 Where the channel points to
  fhir:Subscription.header [ string ], ... ; # 0..* Usage depends on the channel type
  fhir:Subscription.heartbeatPeriod [ unsignedInt ]; # 0..1 Interval in seconds to send 'heartbeat' notification
  fhir:Subscription.timeout [ unsignedInt ]; # 0..1 Timeout in seconds to attempt notification delivery
  fhir:Subscription.contentType [ code ]; # 0..1 MIME type to send, or omit for no payload
  fhir:Subscription.content [ code ]; # 0..1 empty | id-only | full-resource
  fhir:Subscription.notificationUrlLocation [ code ]; # 0..1 none | full-url | request-response | all
  fhir:Subscription.maxCount [ positiveInt ]; # 0..1 Maximum number of triggering resources included in notification bundles

]

Changes since R3

Subscription
Subscription.identifier
  • Added Element
Subscription.name
  • Added Element
Subscription.status
  • Change value set from http://hl7.org/fhir/ValueSet/subscription-status http://hl7.org/fhir/ValueSet/subscription-status|4.0.0 to http://hl7.org/fhir/ValueSet/subscription-status|4.0.1 http://hl7.org/fhir/ValueSet/subscription-state|4.5.0
Subscription.channel.type Subscription.topic
  • Change value set from http://hl7.org/fhir/ValueSet/subscription-channel-type to http://hl7.org/fhir/ValueSet/subscription-channel-type|4.0.1 Added Mandatory Element
Subscription.channel.endpoint Subscription.reason
  • Type Min Cardinality changed from uri 1 to url 0
Subscription.channel.payload Subscription.filterBy
  • Type changed from string to code Added Element
Subscription.filterBy.resourceType
  • Added Element
Subscription.filterBy.searchParamName
  • Add Binding http://hl7.org/fhir/ValueSet/mimetypes|4.0.1 (required) Added Mandatory Element
Subscription.filterBy.searchModifier
  • Added Element
Subscription.filterBy.value
  • Added Mandatory Element
Subscription.channelType
  • Added Mandatory Element
Subscription.endpoint
  • Added Element
Subscription.header
  • Added Element
Subscription.heartbeatPeriod
  • Added Element
Subscription.timeout
  • Added Element
Subscription.contentType
  • Added Element
Subscription.content
  • Added Element
Subscription.notificationUrlLocation
  • Added Element
Subscription.maxCount
  • Added Element
Subscription.tag Subscription.criteria
  • deleted
Subscription.error
  • deleted
Subscription.channel
  • deleted

See the Full Difference for further information

This analysis is available as XML or JSON .

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

Structure

Name Flags Card. Type Description & Constraints doco
. . Subscription Σ TU DomainResource Server push subscription criteria Notification about a SubscriptionTopic
Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
. . . identifier Σ 0..* Identifier Additional identifiers (business identifier)
... name Σ 0..1 string Human readable name for this subscription
. . . status ?! Σ 1..1 code requested | active | error | off | entered-in-error
SubscriptionStatus Subscription State ( Required )
... contact Σ 0..* ContactPoint Contact details for source (e.g. troubleshooting)
. . . end Σ 0..1 instant When to automatically delete the subscription
. . . reason Σ 1..1 0..1 string Description of why this subscription was created
. . . filterBy Σ 0..* BackboneElement Criteria for narrowing the subscription topic stream
. . . . criteria resourceType Σ 1..1 0..1 string uri Rule Allowed Data type or Resource (reference to definition) for server push this Subscription
FHIRDefinedType ( Extensible )
. . . . error searchParamName Σ 0..1 1..1 string Latest error note Filter label defined in SubscriptionTopic
. . channel . . searchModifier Σ 1..1 0..1 BackboneElement code The channel on which to report matches to the criteria = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
Subscription Search Modifier ( Required )
. . . . type value Σ 1..1 code string rest-hook | websocket | email | sms | message Literal value or resource path
... channelType Σ 1..1 Coding Channel type for notifications
SubscriptionChannelType Subscription Channel Type ( Required Extensible )
. . . endpoint Σ 0..1 url Where the channel points to
. . . header Σ 0..* string Usage depends on the channel type
. . . payload heartbeatPeriod Σ 0..1 unsignedInt Interval in seconds to send 'heartbeat' notification
... timeout Σ 0..1 unsignedInt Timeout in seconds to attempt notification delivery
... contentType Σ 0..1 code MIME type to send, or omit for no payload
MimeType ( Required )
. . . header content Σ 0..* 0..1 string code Usage depends on the channel type empty | id-only | full-resource
SubscriptionPayloadContent ( Required )
... notificationUrlLocation Σ 0..1 code none | full-url | request-response | all
SubscriptionUrlLocation ( Required )
... maxCount Σ 0..1 positiveInt Maximum number of triggering resources included in notification bundles

doco Documentation for this format

UML Diagram ( Legend )

Subscription ( DomainResource ) A formal identifier that is used to identify this code system when it is represented in other formats, or referenced in a specification, model, design or an instance identifier : Identifier [0..*] A natural language name identifying the subscription name : string [0..1] 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 SubscriptionState ! » The reference to the subscription topic to be notified about topic : canonical [1..1] « SubscriptionTopic » Contact details for a human to contact about the subscription. The primary use of this for system administrator troubleshooting contact : ContactPoint [0..*] The time for the server to turn the subscription off end : instant [0..1] A description of why this subscription is defined reason : string [1..1] The rules that the server should use to determine when to generate notifications for this subscription criteria : string [1..1] A record of the last error that occurred when the server processed a notification error : string [0..1] Channel The type of channel to send notifications on type channelType : code Coding [1..1] « The type of method used to execute a subscription. (Strength=Required) (Strength=Extensible) SubscriptionChannelType ! + » The url that describes the actual end-point to send messages to endpoint : url [0..1] Additional headers / information to send as part of the notification header : string [0..*] If present, a 'hearbeat" notification (keepalive) is sent via this channel with an the interval period equal to this elements integer value in seconds. If not present, a heartbeat notification is not sent heartbeatPeriod : unsignedInt [0..1] If present, the maximum amount of time a server will allow before failing a notification attempt timeout : unsignedInt [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 notification. The mime type MIME types "text/plain" and "text/html" may also be used for Email and SMS subscriptions payload contentType : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required) Mime Types ! » Additional headers / information How much of the resource content to deliver in the notification payload. The choices are an empty payload, only the resource id, or the full resource content content : code [0..1] « Codes to represent how much resource content to send as part in the notification payload. (Strength=Required) SubscriptionPayloadContent ! » If present, where to place URLs of resources in notifications notificationUrlLocation : code [0..1] « The location, in Bundle.entry, where URLs for resources should be located. (Strength=Required) SubscriptionUrlLocation ! » If present, the maximum number of triggering resources that will be included in a notification bundle (e.g., a server will not include more than this number of trigger resources in a single notification). Note that this is not a strict limit on the number of entries in a bundle, as dependent resources can be included header maxCount : positiveInt [0..1] FilterBy If the element is a reference to another resource, this element contains "Reference", and the targetProfile element defines what resources can be referenced. The targetProfile may be a reference to the general definition of a resource (e.g. http://hl7.org/fhir/StructureDefinition/Patient) resourceType : uri [0..1] « Either a resource or a data type, including logical model types. (Strength=Extensible) FHIRDefinedType + » The filter label (=key) as defined in the `SubscriptionTopic.canfilterBy.searchParamName` element searchParamName : string [0..*] [1..1] The operator to apply to the filter value when determining matches (Search modifiers) searchModifier : code [0..1] « Operator to apply to filter label. (Strength=Required) SubscriptionSearchModifier ! » The literal value or resource path as is legal in search - for example, "Patient/123" or "le1950" value : string [1..1] Details where The filter properties to send notifications when resources be applied to narrow the subscription topic stream. When multiple filters are received that meet applied, evaluates to true if all the criteria conditions are met; otherwise it returns false. (i.e., logical AND) channel filterBy [1..1] [0..*]

XML Template

<Subscription xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <

 <identifier><!-- 0..* Identifier Additional identifiers (business identifier) --></identifier>
 <name value="[string]"/><!-- 0..1 Human readable name for this subscription -->
 <status value="[code]"/><!-- 1..1 requested | active | error | off | entered-in-error -->
 <topic><!-- 1..1 canonical(SubscriptionTopic) Reference to the subscription topic being subscribed to --></topic>

 <contact><!-- 0..* ContactPoint Contact details for source (e.g. troubleshooting) --></contact>
 <end value="[instant]"/><!-- 0..1 When to automatically delete the subscription -->
 <
 <
 <
 <
  <
  <
  <
  <
 </channel>

 <reason value="[string]"/><!-- 0..1 Description of why this subscription was created -->
 <filterBy>  <!-- 0..* Criteria for narrowing the subscription topic stream -->
  <resourceType value="[uri]"/><!-- 0..1 Allowed Data type or Resource (reference to definition) for this Subscription -->
  <searchParamName value="[string]"/><!-- 1..1 Filter label defined in SubscriptionTopic -->
  <searchModifier value="[code]"/><!-- 0..1 = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type -->
  <value value="[string]"/><!-- 1..1 Literal value or resource path -->
 </filterBy>
 <channelType><!-- 1..1 Coding Channel type for notifications --></channelType>
 <endpoint value="[url]"/><!-- 0..1 Where the channel points to -->
 <header value="[string]"/><!-- 0..* Usage depends on the channel type -->
 <heartbeatPeriod value="[unsignedInt]"/><!-- 0..1 Interval in seconds to send 'heartbeat' notification -->
 <timeout value="[unsignedInt]"/><!-- 0..1 Timeout in seconds to attempt notification delivery -->
 <contentType value="[code]"/><!-- 0..1 MIME type to send, or omit for no payload -->
 <content value="[code]"/><!-- 0..1 empty | id-only | full-resource -->
 <notificationUrlLocation value="[code]"/><!-- 0..1 none | full-url | request-response | all -->
 <maxCount value="[positiveInt]"/><!-- 0..1 Maximum number of triggering resources included in notification bundles -->

</Subscription>

JSON Template

{doco
  "resourceType" : "",

  "resourceType" : "Subscription",

  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "

  "identifier" : [{ Identifier }], // Additional identifiers (business identifier)
  "name" : "<string>", // Human readable name for this subscription
  "status" : "<code>", // R!  requested | active | error | off | entered-in-error
  "topic" : { canonical(SubscriptionTopic) }, // R!  Reference to the subscription topic being subscribed to

  "contact" : [{ ContactPoint }], // Contact details for source (e.g. troubleshooting)
  "end" : "<instant>", // When to automatically delete the subscription
  "
  "
  "
  "
    "
    "
    "
    "
  }

  "reason" : "<string>", // Description of why this subscription was created
  "filterBy" : [{ // Criteria for narrowing the subscription topic stream
    "resourceType" : "<uri>", // Allowed Data type or Resource (reference to definition) for this Subscription
    "searchParamName" : "<string>", // R!  Filter label defined in SubscriptionTopic
    "searchModifier" : "<code>", // = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
    "value" : "<string>" // R!  Literal value or resource path
  }],
  "channelType" : { Coding }, // R!  Channel type for notifications
  "endpoint" : "<url>", // Where the channel points to
  "header" : ["<string>"], // Usage depends on the channel type
  "heartbeatPeriod" : "<unsignedInt>", // Interval in seconds to send 'heartbeat' notification
  "timeout" : "<unsignedInt>", // Timeout in seconds to attempt notification delivery
  "contentType" : "<code>", // MIME type to send, or omit for no payload
  "content" : "<code>", // empty | id-only | full-resource
  "notificationUrlLocation" : "<code>", // none | full-url | request-response | all
  "maxCount" : "<positiveInt>" // Maximum number of triggering resources included in notification bundles

}

Turtle Template

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

[ 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:

  fhir:Subscription.identifier [ Identifier ], ... ; # 0..* Additional identifiers (business identifier)
  fhir:Subscription.name [ string ]; # 0..1 Human readable name for this subscription
  fhir:Subscription.status [ code ]; # 1..1 requested | active | error | off | entered-in-error
  fhir:Subscription.topic [ canonical(SubscriptionTopic) ]; # 1..1 Reference to the subscription topic being subscribed to

  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:
  fhir:
  fhir:
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
  ];

  fhir:Subscription.reason [ string ]; # 0..1 Description of why this subscription was created
  fhir:Subscription.filterBy [ # 0..* Criteria for narrowing the subscription topic stream
    fhir:Subscription.filterBy.resourceType [ uri ]; # 0..1 Allowed Data type or Resource (reference to definition) for this Subscription
    fhir:Subscription.filterBy.searchParamName [ string ]; # 1..1 Filter label defined in SubscriptionTopic
    fhir:Subscription.filterBy.searchModifier [ code ]; # 0..1 = | eq | ne | gt | lt | ge | le | sa | eb | ap | above | below | in | not-in | of-type
    fhir:Subscription.filterBy.value [ string ]; # 1..1 Literal value or resource path
  ], ...;
  fhir:Subscription.channelType [ Coding ]; # 1..1 Channel type for notifications
  fhir:Subscription.endpoint [ url ]; # 0..1 Where the channel points to
  fhir:Subscription.header [ string ], ... ; # 0..* Usage depends on the channel type
  fhir:Subscription.heartbeatPeriod [ unsignedInt ]; # 0..1 Interval in seconds to send 'heartbeat' notification
  fhir:Subscription.timeout [ unsignedInt ]; # 0..1 Timeout in seconds to attempt notification delivery
  fhir:Subscription.contentType [ code ]; # 0..1 MIME type to send, or omit for no payload
  fhir:Subscription.content [ code ]; # 0..1 empty | id-only | full-resource
  fhir:Subscription.notificationUrlLocation [ code ]; # 0..1 none | full-url | request-response | all
  fhir:Subscription.maxCount [ positiveInt ]; # 0..1 Maximum number of triggering resources included in notification bundles

]

Changes since Release 3

Subscription
Subscription.identifier
  • Added Element
Subscription.name
  • Added Element
Subscription.status
  • Change value set from http://hl7.org/fhir/ValueSet/subscription-status http://hl7.org/fhir/ValueSet/subscription-status|4.0.0 to http://hl7.org/fhir/ValueSet/subscription-status|4.0.1 http://hl7.org/fhir/ValueSet/subscription-state|4.5.0
Subscription.channel.type Subscription.topic
  • Change value set from http://hl7.org/fhir/ValueSet/subscription-channel-type to http://hl7.org/fhir/ValueSet/subscription-channel-type|4.0.1 Added Mandatory Element
Subscription.channel.endpoint Subscription.reason
  • Type Min Cardinality changed from uri 1 to url 0
Subscription.channel.payload Subscription.filterBy
  • Type changed from string to code Added Element
Subscription.filterBy.resourceType
  • Add Binding http://hl7.org/fhir/ValueSet/mimetypes|4.0.1 (required) Added Element
Subscription.filterBy.searchParamName
  • Added Mandatory Element
Subscription.filterBy.searchModifier
  • Added Element
Subscription.filterBy.value
  • Added Mandatory Element
Subscription.channelType
  • Added Mandatory Element
Subscription.endpoint
  • Added Element
Subscription.header
  • Added Element
Subscription.heartbeatPeriod
  • Added Element
Subscription.timeout
  • Added Element
Subscription.contentType
  • Added Element
Subscription.content
  • Added Element
Subscription.notificationUrlLocation
  • Added Element
Subscription.maxCount
  • Added Element
Subscription.tag Subscription.criteria
  • deleted
Subscription.error
  • deleted
Subscription.channel
  • deleted

See the Full Difference for further information

This analysis is available as XML or JSON .

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

 

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

Subscription.channel.type
Path Definition Type Reference
Subscription.status The status of a subscription. Required SubscriptionStatus SubscriptionState
Subscription.filterBy.resourceType Either a resource or a data type, including logical model types. Extensible FHIRDefinedType
Subscription.filterBy.searchModifier Operator to apply to filter label. Required SubscriptionSearchModifier
Subscription.channelType The type of method used to execute a subscription. Required Extensible SubscriptionChannelType
Subscription.channel.payload Subscription.contentType The mime type of an attachment. Any valid mime type is allowed. Required Mime Types
Subscription.content Codes to represent how much resource content to send in the notification payload. Required SubscriptionPayloadContent
Subscription.notificationUrlLocation The location, in Bundle.entry, where URLs for resources should be located. Required SubscriptionUrlLocation

Trial-Use Note:

TODO

  1. Updates to "Managing Subscriptions and Errors"

    • Discuss error codes (Extensible Codeable Concept)
    • Define basic error codes here
    • Need to discuss eventCount and error detection (insert appropriate examples/workflows)
  2. Updates to "Tracking Subscription Notifications" SHOULD define what the AuditEvent looks like

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.

A subscription is defined by creating the Subscription resource on the server. When There are three options available when specifying the subscription is created by contents of a Notification: empty , id-only , and full-resource . These options change the client, it sets level of detail conveyed in the status notification Bundle .

When deciding which payload type to "requested". After POSTing request, systems SHOULD consider both ease of processing and security of PHI. To mitigate the subscription, risk of information leakage, systems SHOULD use the client parses minimum level of detail consistent with the Location header use case. In practice, id-only provides a good balance between security and saves the new Subscription's logical id performance for use in subsequent operations. many real-world scenarios.

When the If a server receives will not honor a subscription, payload type (e.g., will not send full-resource over HTTP), it SHOULD check that it is prepared to accept/process reject the subscription. If it is, it sets Subscription request, but the server MAY accept the subscription to active , and then process it like a normal create . If it isn't, it SHOULD return an error with an OperationOutcome modificaitons.

instead of processing the

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

The criteria are subject to the same limitations as With the client that created it, such as access to patient compartments etc. Note that content type of empty , all information about the subscription remains active after resources involved in triggering the client access tokens expire. Once notification is only available via channels other than the server has activated Subscription itself (e.g., the subscription, it sets REST API). This mitigates many security concerns by both removing most PHI from the status notification and allows servers to "active" (note: consolidate authorization and authentication logic. When the server can do subscriber receives a notification of this as type, it accepts may query the resource if it wants). An appropriately authorized client can use search and/or history operations server to see what subscriptions are currently active on the server. Once fetch all the subscription is no longer desired, relevant resources based on the SubscriptionTopic and applicable filters. The client deletes might include a _since= query parameter, supplying its last query timestamp to retrieve only the subscription from most recent resources. For example, if the server. 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 needed.

The server may retry When the content type is empty , notification a fixed number of times and/or refer errors to its own alert logs. If bundles SHALL not contain Bundle.entry elements other than the SubscriptionStatus for the notification.

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

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

When the content type is id-only , notification bundles SHALL contain, in addition to "active again. If the SubscriptionStatus , at least one Bundle.entry for each resource relevant to the notification. For example, a subscription fails consistently notification for a server may choose set the subscription status topic based on Encounter SHALL include a reference to off the Encounter and stop trying to send notifications. MAY include additional resources deemed relevant (e.g., the linked Patient ).

If a subscription nominates Each Bundle.entry for id-only notification SHALL contain a fixed end date, relevant resource URL in the server automatically deletes it at fullUrl , request , and/or response elements. The Subscription's notificationUrlLocation element describes the specified time. behavior which should be used.

Applications that wish to track whether notifications have been sent for particular resources (or versions of resources) An example notification with a full-resource payload can look at the AuditEvent resources. For example: be found here .

GET [base]/AuditEvent?entity=Patient/103

This search will return all With the content type of full-resource , the AuditEvent resources that involved in triggering the notification are about Patient 103 . At included in the notification bundle. When a subscriber receives a notification of this time there is no deterministic way type, resources are already present in the bundle, though the subscriber may need to tell say which of those AuditEvent fetch additional resources come from the subscription sub-system that actually handles notifications. This server. For example, the if the notification is planned to be resolved in for a future version of this specification. In topic about patient admission, the mean time, servers are encouraged subscriber may require related Observation resources.

When the content type is full-resource , notification bundles SHALL contain, in addition to create AuditEvent records when performing notifications 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 document how clients can identify MAY include additional resources deemed relevant (e.g., the relevant records when searching. Patient ).

In addition, servers might also create Communication resources most scenarios, each Bundle.entry for a full-resource notification SHALL contain a relevant resource in the resource element. In some of scenarios, it is not possible to include the notifications that resource, in which case entry.request and/or entry.response are sent required. For example, in response to the case of a subscription, such as when sending emails. GET [base]/Communication?based-on=Subscription/103 This returns notification about a list of communications sent by deleted resource, the server may no longer have access to the resource. In this case, information in the entry.response is critical for a subscription. TODO: search on payload.... subscriber to process the notification (e.g., the etag ).

2.46.7.1

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 Subscription is created or updated that meets the criteria, for a REST Hook channel type, the server sends a POST request with no body SHALL set initial status to requested , pending verification of the nominated endpoint URL. When the subscriber receives After a POST to https://biliwatch.com/customers/mount-auburn-miu/on-result , it re-issues successful handshake notification has been sent and accepted, the criteria as a query to server SHALL update the server, appending status to &_since=:last (where :last is replaced by active . Any errors in the time at which initial handshake SHALL result in the client last checked). In this way it can fetch all new relevant Observations . status being changed to error .

Since payload is missing, the data in To receive notifications via HTTP/S POST, a client should request a subscription with the resources is only available through channel type ( Subscription.channelType ) of rest-hook (from the REST API, which helps consolidate authorization subscription-channel-type Code System) and authentication logic. The server must append set the headers, if any are given, endpoint ( Subscription.endpoint ) to the POST request appropriate client URL. Note that it makes to this URL must be accessible by the client. hosting server.

Alternatively, To convey an event notification, the server can be asked POSTs a Bundle to send the entire resource to a client's nominated FHIR end-point. This is usually appropriate for defining routing rules within a managed eco-system such endpoint URL per the format requests in the Subscription. The content-type of the POST SHALL match the contentType ( channel.contentType ) requested during creation of the Subscription. Each Subscription.header value SHALL be conveyed as a healthcare institution. an HTTP request header.

{ "channel": { "type": "rest-hook", "endpoint": "https://internal.acme.com/research/saturn", "payload": "application/fhir+json" } }

This requests that An example workflow for establishing a server forward rest-hook subscription is included below.

Diagram with a worflow for a Subscription using REST hooks
  1. Client creates a copy of any matching resource in JSON format Subscription with the channelType set to rest-hook .
  2. Server responds with a success code and creates the nominated server as subscription with a state of requested .
  3. Server performs an Update operation using the nominated URL as the service base . In order HTTP POST to execute this channel, the server must know how to authenticate appropriately requested endpoint with a handshake notification.
  4. Client Endpoint accepts the destination server. This can be done by the subscription resource providing POST and returns a success HTTP code (e.g., 200).
  5. Server may send a notification of type heartbeat at any time.
  6. Server may send a notificaiton of type event-notificaiton at any time.

HTTP is neither a secure nor an authentication header for the server encrypted channel. It is strongly recommended that production implementations refuse requests to use, or alternatively, send notifications to URLs using the server may be specifically configured HTTP protocol (use HTTPS instead).

HTTP does not provide endpoint verification. It is strongly recommended that implementations refuse requests to be able send notifications to use URLs using the nominated server. HTTP protocol (use HTTPS instead).

2.46.7.2

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 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 receive notifications via Web Sockets: { "channel": { "type": "websocket" } } The subscriber would then initiate Sockets by requesting a Web Socket connection to subscription with the server, at a URL advertised in channel type ( Subscription.channelType ) of websocket (from the FHIR server's Capability statement (subscriptions/webSocketUrl (todo)). A simple protocol is used to listen subscription-channel-type Code System).

An example workflow for notifications: receiving notifications via websockets is shown below:

Diagram with a worflow for a Subscription using websockets
  1. Client connects creates a secure Web Socket Subscription with the channelType set to websocket .
  2. Server responds with a success code and creates the subscription.
  3. Client requests FHIR server's CapabilityStatement to find the server's webSocketUrl (see websocket URL via the websocket extension in the server's .
  4. Server returns its CapabilityStatement ). .
  5. Client authenticates connects to the server using via websockets (ws:// or wss://).
  6. Client requests a websocket binding token, by invoking the $get-ws-binding-token operation via REST. Note: this call is intended to be repeated as necessary (e.g., prior to a server-specified Web socket protocol (e.g. OAuth bearer token presentation). expiring, a client should request a new one).
  7. Server returns Parameters with a token and an expiration .
  8. Client sends a bind :id bind-with-token message over the socket (using via websockets, with the logical id of token provided by the subscription). For example, server. Note: this operation can be repeated concurrently for multiple subscriptions, and serially for continued operation over a single websocket connection.
  9. Server sends one or more handshake messages via websockets (one per Subscription included in the client might issue: bind 123). token). Note: some servers may additionally send one or more event-notification messages at this time (e.g., all messages since last connected, last 'n' messages, etc.). Clients are expected to handle either flow.
  10. Server responds with may send a "bound :id" heartbeat message to acknowledge. via websockets at any time.
  11. Server sends a "ping :id" may send an event-notification message via websockets at any time.
  12. Either the server or the client may close the websocket connection.

Note: all notifications sent from the server SHALL be in the format specified by the Subscription it is for (e.g., contentType and content fields).

Trial-Use Note: The Websocket channel type needs more testing and feedback to notify ensure all requirements are met before finalizing the specification.

WebSocket security poses several challenges specific to the channel. When implementing websockets for notifications, please keep in mind the following list of some areas of concern:

  • Authentication of WebSockets is not generically interoperable with JWT or other 'Authentication header' protocols - WS and WSS do NOT allow for the required headers.
  • Given client each time a new result limitations on concurrent WebSocket connections (commonly 6), it is available recommended that a single connection be able to authenticate to multiple Subscription resources.
  • Unlike HTTP/S requests, WebSockets can be long-lived. Because of this, the case of revoking access of an active connection must be considered.
2.46.7.3

While the primary interface for FHIR servers is the FHIR REST API, notifications need not occur via REST. Indeed, some subscribers may be unable to maintain an outward-facing HTTP server to receive triggered notifications. For example, a public health organization may want to be notified of outbreaks of various illnesses. This can be accomplished using an email notification channel.

A client can register for declare its user intention to receive notifications via Email by email: requesting a subscription with the channel type ( Subscription.channelType ) of email (from the subscription-channel-type Code System) and setting the endpoint ( Subscription.endpoint ) to the appropriate email URI (e.g., mailto:public_health_notifications@example.org ).

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

The server would will send a new message for each matching resource. The body of the email may time a notification should be empty, sent (e.g., per event or it may contain per batch). The server will create a reference to message based on the search or values present in the matching resource. It is at Subscription.contentType and Subscription.content fields. If a server cannot honor the discretion of requested combination, the server as to how much information 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 provide. these guidelines, the Subscription.channel.header Subscription.contentType sets refers to the subject content of the email. The email should be secured appropriately, such as using Direct, as specified by the rules body of the applicable jurisdictions. SMS works very similarly: message. Attachment type information can be appended as a MIME parameter, for example:

{ "channel": { "type": "sms", "endpoint": "tel:+1555-345-5555" } }
  • text/plain : a 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

Note: SMS messages are extremely limited in size, so The channel.payload Subscription.content will usually field SHALL be omitted (signifying that no payload is applied to any attachments, and MAY be sent). The recipient may be human, but this is applied to body contents (depending on server implementation). However, a server must not always include a body which exceeds the case. Irrespective of size, most servers will refuse specified content level. For example, a server may choose to send payloads always include a standard message in SMS for security reasons, the body of the message containing no PHI and may refuse vary the attachment, but cannot include PHI in the body of an email when the content is set to send emails unless encrypted. empty .

A mime/type of text/plain can be useful for An example workflow using the email channel type is included below.

Diagram with a worflow for a Subscription using email
  1. Client creates a Subscription with the channelType set to email .
  2. Server responds with a success code and sms along creates the subscription with some extension describing how a state of either requested or active .
  3. Optional: Server sends a email message to convert resources the requested endpoint with a handshake notification. If the subscription was set to requested , it should be updated to active after successfully sending the email (pending additional steps such as user confirmation, etc.).
  4. Server may send an email for a text representation. This specification notification of type heartbeat at any time.
  5. Server may provide supporting infrastructure send an email for this in the future. a notificaiton of type event-notificaiton at any time.

Email (SMTP) is not a secure channel. Implementers must ensure that any messages containing PHI have been secured according to their policy requirements (e.g., use of a system such as Direct ).

A client can register for its user There are times when it is desireable to use Subscriptions as a communication channel between FHIR servers. This can be accomplished using a Subscription with the channel type of message .

To receive notifications via messaging, a client should request a subscription with the channel type ( Subscription.channelType ) of message and set the endpoint ( Subscription.endpoint ) to the destination FHIR server base URL. Note that this URL must be accessible by messaging : the hosting server.

{ "channel": { "type": "message", "endpoint": "http://ehr.example.org/fhir/$process-message" } }

For each matching resource, a The FHIR server hosting the subscription (server) will send FHIR messages to the destination FHIR server (endpoint) as needed. These messages will, as the contents of the message, have a fully-formed subscription-notification Bundle. An example message can be found here .

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

Diagram with a worflow for a Subscription using FHIR messaging
  1. Client creates a Subscription with the channelType set to message .
  2. Server responds with a success code and creates the nominated end-point. Most servers will subscription with a state of requested .
  3. Server sends a FHIR Message to the requested endpoint with a handshake notification.
  4. Client Endpoint accepts the Message and returns success.
  5. Server may send a Message containing a notification of type heartbeat at any time.
  6. Server may send a Message containing a notificaiton of type event-notificaiton at any time.

Trial-Use Note: The Messaging channel type needs more testing and feedback to ensure all requirements are met before finalizing the specification.

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

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 Trial-Use Note: Warning: This section is still in early drafting.

At a minimum, the following items should be defined:

  • A generally useful name for Subscription.channelType (e.g., 'secure-mq' isntead of 'channel0012')
  • The details type of data required in Subscription.endpoint (e.g., URI, etc.)
  • The meaning of the message - mainly Subscription.header field values (e.g., REST-hook defines as Auth headers included in a POST)
  • Any variations on MIME types for Subscription.contentType (e.g., email defines this as the event code - email body, with allowable attachments.)
  • Whether heartbeat notifications are still used (and guidance on timings if they are)
  • Defining a channel has security implications.
  • If the channel CANNOT be secured, that should be stated with a warning not to transfer PHI.
  • If the channel is/can be resolved during scured, guidance should be given on how configurations relate to PHI safety:
    • Does the trial channel determine the legitimacy of both endpoints?
    • Is the channel secure for third-party monitoring?
    • ...

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 transaction, the client parses the Location header and saves the new Subscription's logical id for use period. in subsequent operations.

Feedback When the server receives a subscription, it SHOULD check that it is welcome here 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.

Once the server has activated the subscription, it sets the status to active (note: the server may 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 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.

Search parameters for 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
criteria identifier string token The search rules used to determine when to send a notification A subscription identifier Subscription.criteria Subscription.identifier
payload token The mime-type of the notification payload Subscription.channel.payload
status N token The current state of the subscription Subscription.status
type token The type of channel for the sent notifications Subscription.channel.type
url uri The uri that will receive the notifications Subscription.channel.endpoint