Release 5 FHIR CI-Build

This page is part of the Continuous Integration Build of FHIR Specification (v5.0.0: R5 - STU ). This is the current published version in it's permanent home (it will always (will be available incorrect/inconsistent at this URL). For a full list of available versions, see times).
See the Directory of published versions icon . Page versions: R5 R4B

2.13 Resource SubscriptionStatus - Content

Responsible Owner: FHIR Infrastructure icon Work Group Maturity Level : 2   Trial Use Normative Security Category : Business Compartments : No defined compartments

The SubscriptionStatus resource describes the state of a Subscription during notifications.

2.13.1 Scope and Usage

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

The SubscriptionStatus resource is used to convey information about the current state of a Subscription during client notifications. It is not persisted or allowed to be referenced by other resources except as described below.

2.13.2 Boundaries and Relationships

The SubscriptionStatus resource is used in the Subscriptions Framework . Information about the Boundaries and Relationships both within the Subscriptions Framework and to other areas of the FHIR specification can be found here .

2.13.3 References to this Resource

No references for this Resource.

2.13.4 Resource Content

Structure

Name Flags Card. Type Description & Constraints      Filter: Filters doco
. . SubscriptionStatus TU N DomainResource Status information about a Subscription provided during event notification
+ Rule: Event notifications must contain events
+ Rule: Status messages must contain status

Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
. . . status Σ C 0..1 code requested | active | error | off | entered-in-error
Binding: Subscription Status ( Required )
. . . type ?! Σ C 1..1 code handshake | heartbeat | event-notification | query-status | query-event
Binding: Subscription Notification Type ( Required )
. . . eventsSinceSubscriptionStart Σ 0..1 integer64 Events since the Subscription was created
. . . . eventNumber Σ 1..1 integer64 Sequencing index of this event
. . . . triggerEvent 0..* CodeableConcept Event that triggered this notification

.... timestamp 0..1 instant The instant this event occurred
. . . . focus 0..1 Reference ( Any ) Reference to the primary resource or information of this event
. . . . additionalContext 0..* Reference ( Any ) References related to the focus resource and/or context of this event

. . . . relatedQuery Σ 0..* BackboneElement Query describing data relevant to this notification

... . subscription . queryType Σ 0..1 Coding Coded information describing the type of data this query provides
..... query Σ 1..1 string Query to perform
.... authorizationHint 0..* BackboneElement Authorization information relevant to a notification

..... authorizationType 1..1 Coding Classification of the authorization hint, e.g., 'oAuthChallengeToken'
..... value 0..1 string Authorization value, as defined by the 'authorizationType'
... subscription Σ 1..1 Reference ( Subscription ) Reference to the Subscription responsible for this notification
. . . topic Σ 0..1 canonical ( SubscriptionTopic ) Reference to the SubscriptionTopic this notification relates to
. . . error Σ 0..* CodeableConcept List of errors on the subscription
Binding: Subscription Error Codes ( Example )


doco Documentation for this format icon

See the Extensions for this resource

UML Diagram ( Legend )

SubscriptionStatus ( DomainResource ) The status of the subscription, which marks the server state for managing the subscription status : code [0..1] « null (Strength=Required) SubscriptionStatusCodes ! » « This element has or is affected by some invariants C » The type of event being conveyed with this notification (this element modifies the meaning of other elements) type : code [1..1] « null (Strength=Required) SubscriptionNotificationType ! » « This element has or is affected by some invariants C » The total number of actual events which have been generated since the Subscription was created (inclusive of this notification) - regardless of how many have been successfully communicated. This number is NOT incremented for handshake and heartbeat notifications eventsSinceSubscriptionStart : integer64 [0..1] The reference to the Subscription which generated this notification subscription : Reference [1..1] « Subscription » The reference to the SubscriptionTopic for the Subscription which generated this notification topic : canonical [0..1] « SubscriptionTopic » A record of errors that occurred when the server processed a notification error : CodeableConcept [0..*] « null (Strength=Example) SubscriptionErrorCodes ?? » NotificationEvent Either the sequential number of this event in this subscription context or a relative event number for this notification eventNumber : integer64 [1..1] If present, one or more event codes specifying the events which triggered this notification triggerEvent : CodeableConcept [0..*] The actual time this event occurred on the server timestamp : instant [0..1] The focus of this event. While this will usually be a reference to the focus resource of the event, it MAY contain a reference to a non-FHIR object focus : Reference [0..1] « Any » Additional context information for this event. Generally, this will contain references to additional related resources included with the event (e.g., the Patient relevant to an Encounter), however it MAY refer to non-FHIR objects additionalContext : Reference [0..*] « Any » RelatedQuery Coded value(s) used to describe the type of information that evaluating this query will provide. Subscribers can use the values to ensure the data they request are relevant and necessary for their use queryType : Coding [0..1] Query a subscriber can use to retrieve additional information. The exact contents of the query MAY depend on the value of the `queryType`, however this SHOULD be a query suitable for use as an HTTP GET request (either fully-qualified or partial) query : string [1..1] AuthorizationHint Used by clients to determine what kind of authorization hint is being suggested by the sender authorizationType : Coding [1..1] A value related to the authorization (e.g., a token) value : string [0..1] Queries and codes that could be included with notifications of this shape. Servers MAY include these queries if supported and desired in the workflow relatedQuery [0..*] Authorization context information and value (e.g., token) authorizationHint [0..*] Detailed information about events relevant to this subscription notification notificationEvent [0..*]

XML Template 

<SubscriptionStatus xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <status value="[code]"/><!-- I 0..1 requested | active | error | off | entered-in-error -->
 <type value="[code]"/><!-- I 1..1 handshake | heartbeat | event-notification | query-status | query-event -->
 <eventsSinceSubscriptionStart value="[integer64]"/><!-- 0..1 Events since the Subscription was created -->
 <notificationEvent>  <!-- I 0..* Detailed information about any events relevant to this notification -->
  <eventNumber value="[integer64]"/><!-- 1..1 Sequencing index of this event -->
  <triggerEvent><!-- 0..* CodeableConcept Event that triggered this notification --></triggerEvent>

  <timestamp value="[instant]"/><!-- 0..1 The instant this event occurred -->
  <focus><!-- 0..1 Reference(Any) Reference to the primary resource or information of this event --></focus>
  <</additionalContext>

  <additionalContext><!-- 0..* Reference(Any) References related to the focus resource and/or context of this event --></additionalContext>
  <relatedQuery>  <!-- 0..* Query describing data relevant to this notification -->
   <queryType><!-- 0..1 Coding Coded information describing the type of data this query provides --></queryType>
   <query value="[string]"/><!-- 1..1 Query to perform -->
  </relatedQuery>
  <authorizationHint>  <!-- 0..* Authorization information relevant to a notification -->
   <authorizationType><!-- 1..1 Coding Classification of the authorization hint, e.g., 'oAuthChallengeToken' --></authorizationType>
   <value value="[string]"/><!-- 0..1 Authorization value, as defined by the 'authorizationType' -->
  </authorizationHint>

 </notificationEvent>
 <subscription><!-- 1..1 Reference(Subscription) Reference to the Subscription responsible for this notification --></subscription>
 <topic><!-- 0..1 canonical(SubscriptionTopic) Reference to the SubscriptionTopic this notification relates to --></topic>
 <error><!-- 0..* CodeableConcept List of errors on the subscription --></error>
</SubscriptionStatus>

JSON Template 

{doco
  "resourceType" : "SubscriptionStatus",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "status" : "<code>", // I requested | active | error | off | entered-in-error
  "type" : "<code>", // I R!  handshake | heartbeat | event-notification | query-status | query-event
  "eventsSinceSubscriptionStart" : "<integer64>", // Events since the Subscription was created
  "notificationEvent" : [{ // I Detailed information about any events relevant to this notification
    "eventNumber" : "<integer64>", // R!  Sequencing index of this event
    "triggerEvent" : [{ CodeableConcept }], // Event that triggered this notification

    "timestamp" : "<instant>", // The instant this event occurred
    "focus" : { Reference(Any) }, // Reference to the primary resource or information of this event
    "

    "additionalContext" : [{ Reference(Any) }], // References related to the focus resource and/or context of this event
    "relatedQuery" : [{ // Query describing data relevant to this notification
      "queryType" : { Coding }, // Coded information describing the type of data this query provides
      "query" : "<string>" // R!  Query to perform
    }],
    "authorizationHint" : [{ // Authorization information relevant to a notification
      "authorizationType" : { Coding }, // R!  Classification of the authorization hint, e.g., 'oAuthChallengeToken'
      "value" : "<string>" // Authorization value, as defined by the 'authorizationType'
    }]

  }],
  "subscription" : { Reference(Subscription) }, // R!  Reference to the Subscription responsible for this notification
  "topic" : "<canonical(SubscriptionTopic)>", // Reference to the SubscriptionTopic this notification relates to
  "error" : [{ CodeableConcept }] // List of errors on the subscription
}

Turtle Template 

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


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

  # from 
  # from 

  # from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language
  # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir:modifierExtension

  fhir:status [ code ] ; # 0..1 I requested | active | error | off | entered-in-error
  fhir:type [ code ] ; # 1..1 I handshake | heartbeat | event-notification | query-status | query-event
  fhir:eventsSinceSubscriptionStart [ integer64 ] ; # 0..1 Events since the Subscription was created
  fhir:notificationEvent ( [ # 0..* I Detailed information about any events relevant to this notification
    fhir:eventNumber [ integer64 ] ; # 1..1 Sequencing index of this event
    fhir:triggerEvent  ( [ CodeableConcept ] ... ) ; # 0..* Event that triggered this notification

    fhir:timestamp [ instant ] ; # 0..1 The instant this event occurred
    fhir:focus [ Reference(Any) ] ; # 0..1 Reference to the primary resource or information of this event
    fhir:

    fhir:additionalContext  ( [ Reference(Any) ] ... ) ; # 0..* References related to the focus resource and/or context of this event
    fhir:relatedQuery ( [ # 0..* Query describing data relevant to this notification
      fhir:queryType [ Coding ] ; # 0..1 Coded information describing the type of data this query provides
      fhir:query [ string ] ; # 1..1 Query to perform
    ] ... ) ;
    fhir:authorizationHint ( [ # 0..* Authorization information relevant to a notification
      fhir:authorizationType [ Coding ] ; # 1..1 Classification of the authorization hint, e.g., 'oAuthChallengeToken'
      fhir:value [ string ] ; # 0..1 Authorization value, as defined by the 'authorizationType'
    ] ... ) ;

  ] ... ) ;
  fhir:subscription [ Reference(Subscription) ] ; # 1..1 Reference to the Subscription responsible for this notification
  fhir:topic [ canonical(SubscriptionTopic) ] ; # 0..1 Reference to the SubscriptionTopic this notification relates to
  fhir:error  ( [ CodeableConcept ] ... ) ; # 0..* List of errors on the subscription
]

Changes from both R4 and R4B

This resource did not exist in Release R4

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON .

Structure

Name Flags Card. Type Description & Constraints      Filter: Filters doco
. . SubscriptionStatus TU N DomainResource Status information about a Subscription provided during event notification
+ Rule: Event notifications must contain events
+ Rule: Status messages must contain status

Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
. . . status Σ C 0..1 code requested | active | error | off | entered-in-error
Binding: Subscription Status ( Required )
. . . type ?! Σ C 1..1 code handshake | heartbeat | event-notification | query-status | query-event
Binding: Subscription Notification Type ( Required )
. . . eventsSinceSubscriptionStart Σ 0..1 integer64 Events since the Subscription was created
. . . . eventNumber Σ 1..1 integer64 Sequencing index of this event
. . . . triggerEvent 0..* CodeableConcept Event that triggered this notification

.... timestamp 0..1 instant The instant this event occurred
. . . . focus 0..1 Reference ( Any ) Reference to the primary resource or information of this event
. . . . additionalContext 0..* Reference ( Any ) References related to the focus resource and/or context of this event

. . . . relatedQuery Σ 0..* BackboneElement Query describing data relevant to this notification

... . subscription . queryType Σ 0..1 Coding Coded information describing the type of data this query provides
..... query Σ 1..1 string Query to perform
.... authorizationHint 0..* BackboneElement Authorization information relevant to a notification

..... authorizationType 1..1 Coding Classification of the authorization hint, e.g., 'oAuthChallengeToken'
..... value 0..1 string Authorization value, as defined by the 'authorizationType'
... subscription Σ 1..1 Reference ( Subscription ) Reference to the Subscription responsible for this notification
. . . topic Σ 0..1 canonical ( SubscriptionTopic ) Reference to the SubscriptionTopic this notification relates to
. . . error Σ 0..* CodeableConcept List of errors on the subscription
Binding: Subscription Error Codes ( Example )


doco Documentation for this format icon

See the Extensions for this resource

UML Diagram ( Legend )

SubscriptionStatus ( DomainResource ) The status of the subscription, which marks the server state for managing the subscription status : code [0..1] « null (Strength=Required) SubscriptionStatusCodes ! » « This element has or is affected by some invariants C » The type of event being conveyed with this notification (this element modifies the meaning of other elements) type : code [1..1] « null (Strength=Required) SubscriptionNotificationType ! » « This element has or is affected by some invariants C » The total number of actual events which have been generated since the Subscription was created (inclusive of this notification) - regardless of how many have been successfully communicated. This number is NOT incremented for handshake and heartbeat notifications eventsSinceSubscriptionStart : integer64 [0..1] The reference to the Subscription which generated this notification subscription : Reference [1..1] « Subscription » The reference to the SubscriptionTopic for the Subscription which generated this notification topic : canonical [0..1] « SubscriptionTopic » A record of errors that occurred when the server processed a notification error : CodeableConcept [0..*] « null (Strength=Example) SubscriptionErrorCodes ?? » NotificationEvent Either the sequential number of this event in this subscription context or a relative event number for this notification eventNumber : integer64 [1..1] If present, one or more event codes specifying the events which triggered this notification triggerEvent : CodeableConcept [0..*] The actual time this event occurred on the server timestamp : instant [0..1] The focus of this event. While this will usually be a reference to the focus resource of the event, it MAY contain a reference to a non-FHIR object focus : Reference [0..1] « Any » Additional context information for this event. Generally, this will contain references to additional related resources included with the event (e.g., the Patient relevant to an Encounter), however it MAY refer to non-FHIR objects additionalContext : Reference [0..*] « Any » RelatedQuery Coded value(s) used to describe the type of information that evaluating this query will provide. Subscribers can use the values to ensure the data they request are relevant and necessary for their use queryType : Coding [0..1] Query a subscriber can use to retrieve additional information. The exact contents of the query MAY depend on the value of the `queryType`, however this SHOULD be a query suitable for use as an HTTP GET request (either fully-qualified or partial) query : string [1..1] AuthorizationHint Used by clients to determine what kind of authorization hint is being suggested by the sender authorizationType : Coding [1..1] A value related to the authorization (e.g., a token) value : string [0..1] Queries and codes that could be included with notifications of this shape. Servers MAY include these queries if supported and desired in the workflow relatedQuery [0..*] Authorization context information and value (e.g., token) authorizationHint [0..*] Detailed information about events relevant to this subscription notification notificationEvent [0..*]

XML Template 

<SubscriptionStatus xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <status value="[code]"/><!-- I 0..1 requested | active | error | off | entered-in-error -->
 <type value="[code]"/><!-- I 1..1 handshake | heartbeat | event-notification | query-status | query-event -->
 <eventsSinceSubscriptionStart value="[integer64]"/><!-- 0..1 Events since the Subscription was created -->
 <notificationEvent>  <!-- I 0..* Detailed information about any events relevant to this notification -->
  <eventNumber value="[integer64]"/><!-- 1..1 Sequencing index of this event -->
  <triggerEvent><!-- 0..* CodeableConcept Event that triggered this notification --></triggerEvent>

  <timestamp value="[instant]"/><!-- 0..1 The instant this event occurred -->
  <focus><!-- 0..1 Reference(Any) Reference to the primary resource or information of this event --></focus>
  <</additionalContext>

  <additionalContext><!-- 0..* Reference(Any) References related to the focus resource and/or context of this event --></additionalContext>
  <relatedQuery>  <!-- 0..* Query describing data relevant to this notification -->
   <queryType><!-- 0..1 Coding Coded information describing the type of data this query provides --></queryType>
   <query value="[string]"/><!-- 1..1 Query to perform -->
  </relatedQuery>
  <authorizationHint>  <!-- 0..* Authorization information relevant to a notification -->
   <authorizationType><!-- 1..1 Coding Classification of the authorization hint, e.g., 'oAuthChallengeToken' --></authorizationType>
   <value value="[string]"/><!-- 0..1 Authorization value, as defined by the 'authorizationType' -->
  </authorizationHint>

 </notificationEvent>
 <subscription><!-- 1..1 Reference(Subscription) Reference to the Subscription responsible for this notification --></subscription>
 <topic><!-- 0..1 canonical(SubscriptionTopic) Reference to the SubscriptionTopic this notification relates to --></topic>
 <error><!-- 0..* CodeableConcept List of errors on the subscription --></error>
</SubscriptionStatus>

JSON Template 

{doco
  "resourceType" : "SubscriptionStatus",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "status" : "<code>", // I requested | active | error | off | entered-in-error
  "type" : "<code>", // I R!  handshake | heartbeat | event-notification | query-status | query-event
  "eventsSinceSubscriptionStart" : "<integer64>", // Events since the Subscription was created
  "notificationEvent" : [{ // I Detailed information about any events relevant to this notification
    "eventNumber" : "<integer64>", // R!  Sequencing index of this event
    "triggerEvent" : [{ CodeableConcept }], // Event that triggered this notification

    "timestamp" : "<instant>", // The instant this event occurred
    "focus" : { Reference(Any) }, // Reference to the primary resource or information of this event
    "

    "additionalContext" : [{ Reference(Any) }], // References related to the focus resource and/or context of this event
    "relatedQuery" : [{ // Query describing data relevant to this notification
      "queryType" : { Coding }, // Coded information describing the type of data this query provides
      "query" : "<string>" // R!  Query to perform
    }],
    "authorizationHint" : [{ // Authorization information relevant to a notification
      "authorizationType" : { Coding }, // R!  Classification of the authorization hint, e.g., 'oAuthChallengeToken'
      "value" : "<string>" // Authorization value, as defined by the 'authorizationType'
    }]

  }],
  "subscription" : { Reference(Subscription) }, // R!  Reference to the Subscription responsible for this notification
  "topic" : "<canonical(SubscriptionTopic)>", // Reference to the SubscriptionTopic this notification relates to
  "error" : [{ CodeableConcept }] // List of errors on the subscription
}

Turtle Template 

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


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

  # from 
  # from 

  # from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language
  # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir:modifierExtension

  fhir:status [ code ] ; # 0..1 I requested | active | error | off | entered-in-error
  fhir:type [ code ] ; # 1..1 I handshake | heartbeat | event-notification | query-status | query-event
  fhir:eventsSinceSubscriptionStart [ integer64 ] ; # 0..1 Events since the Subscription was created
  fhir:notificationEvent ( [ # 0..* I Detailed information about any events relevant to this notification
    fhir:eventNumber [ integer64 ] ; # 1..1 Sequencing index of this event
    fhir:triggerEvent  ( [ CodeableConcept ] ... ) ; # 0..* Event that triggered this notification

    fhir:timestamp [ instant ] ; # 0..1 The instant this event occurred
    fhir:focus [ Reference(Any) ] ; # 0..1 Reference to the primary resource or information of this event
    fhir:

    fhir:additionalContext  ( [ Reference(Any) ] ... ) ; # 0..* References related to the focus resource and/or context of this event
    fhir:relatedQuery ( [ # 0..* Query describing data relevant to this notification
      fhir:queryType [ Coding ] ; # 0..1 Coded information describing the type of data this query provides
      fhir:query [ string ] ; # 1..1 Query to perform
    ] ... ) ;
    fhir:authorizationHint ( [ # 0..* Authorization information relevant to a notification
      fhir:authorizationType [ Coding ] ; # 1..1 Classification of the authorization hint, e.g., 'oAuthChallengeToken'
      fhir:value [ string ] ; # 0..1 Authorization value, as defined by the 'authorizationType'
    ] ... ) ;

  ] ... ) ;
  fhir:subscription [ Reference(Subscription) ] ; # 1..1 Reference to the Subscription responsible for this notification
  fhir:topic [ canonical(SubscriptionTopic) ] ; # 0..1 Reference to the SubscriptionTopic this notification relates to
  fhir:error  ( [ CodeableConcept ] ... ) ; # 0..* List of errors on the subscription
]

Changes from both R4 and R4B

This resource did not exist in Release R4

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON .

 

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

2.13.4.1 Terminology Bindings

Path ValueSet Type Documentation
SubscriptionStatus.status SubscriptionStatusCodes (a valid code from Subscription Status ) Required

State values for FHIR Subscriptions.

SubscriptionStatus.type SubscriptionNotificationType Required

The type of notification represented by the status message.

SubscriptionStatus.error SubscriptionErrorCodes Example

Codes to represent subscription error details

2.13.4.2 Constraints

UniqueKey Level Location Description Expression
img  sst-1 Rule (base) Event notifications must contain events (type = 'event-notification' or type = 'query-event') implies notificationEvent.exists()
img  sst-2 Rule (base) Status messages must contain status type = 'query-status' implies status.exists()

2.13.5 Timing and Currency

This resource is used to communicate information about a Subscription and the events represented by a notification bundle. The process of sending a notification (e.g., a notification this status is included with) can change the status of that subscription. Servers SHALL populate elements with the most recent information at the time of generation (e.g., when a notification is created) and receivers SHOULD be aware that this information might not be current at the time a notification is processed (e.g., a subscription was active but has subsequently moved to an error state).

2.13.6 Content and PHI (Personal health information)

Subscription notifications MAY contain PHI. Applications are responsible for following FHIR security guidance and compliance with relevant security requirements (e.g., corporate policy, government regulation, etc.). Hinting for the allowed amount of PHI is available in the relevant Subscription resource, via the channel and payload information.

Since Subscription Topic definitions contain human-readable descriptions and definitions, the purpose of a topic may be understood by viewing the resource. Given that canonical links to topics are intended to be resolvable and/or searchable (e.g., indexed in a registry), it is assumed that anyone with a link to a topic also knows what that topic is about. Thus, topics MAY be considered PHI and SHOULD be reviewed before inclusion in a notification.

Hinting about when a canonical topic URL may be included with a notification can be derived from a subscription's payload level. E.g.:

  • empty : SHOULD NOT be present
  • id-only : MAY be present
  • full-resource : SHOULD be present

2.13.7 Subscription Reference

The SubscriptionStatus.subscription element contains a reference to the Subscription resource responsible for the notification. In most cases, this reference will resolve to an accessible Subscription resource on the server. However, in some workflows, particularly those involving implicit or server-controlled subscriptions, the Subscription resource might not be externally accessible or shared. In such cases, the Reference may use Reference.identifier to represent an identifier or placeholder known only to the sender, or even Reference.display for a relevant literal (e.g., friendly-name that can be referenced in support requests). Implementers SHOULD be aware that resolution of this reference might not be possible on the receiving end.

2.13.8 Event Numbering

Since this specification does not currently define any channel types that guarantee client receipt of notifications, a monotonically-increasing event number is critical to detecting several classes of delivery errors (more information is available at Detecting Delivery Errors ). However, with the availability of custom-defined channels , notifications can be sent across channels that provide guaranteed delivery (e.g., a message queue), which removes the need for global tracking of event numbers.

For channels that do not need event numbers, it is still desireable desirable for clients to have an index for the events present in a notification. In all cases, a value for SubscriptionStatus.notificationEvent.eventNumber is required - either the number in-sequence based on the total number of events on a subscription or a notification-bundle relative index (e.g., 1, 2, 3, etc.).

Element Delivery Type Optionality Notes
SubscriptionStatus.eventsSinceSubscriptionStart Best Effort Required Servers SHALL include this value when sending event notifications in order to allow clients to detect missing events.
This value is inclusive of this notification (e.g., the first event notification sent would include one (1) in this element).
SubscriptionStatus.eventsSinceSubscriptionStart Guaranteed Optional Servers MAY include this value when sending event notifications.
SubscriptionStatus.notificationEvent.eventNumber Best Effort Required Event numbers SHALL match the index in the subscription event sequence. E.g., the highest-numbered event in the notification will match the number in eventsSinceSubscriptionStart .
SubscriptionStatus.notificationEvent.eventNumber Guaranteed Required A relative index of events in a single notification, e.g., 1, 2, 3, etc..

2.13.8 2.13.9 Notification Types

This specification describes five distinct outbound notification types: Event , Handshake , Heartbeat , Query Status , and Query Event . For each, the notification body is a subscription-notification Bundle with a SubscriptionStatus resource used to convey Subscription and notification details.

2.13.8.1 2.13.9.1 Event Notification

The primary notification bundle type is a notification about an event.

Element Optionality Notes
SubscriptionStatus.status Recommended Current status of the relevant subscription (e.g., active ).
SubscriptionStatus.type Required SHALL be event-notification
SubscriptionStatus.eventsSinceSubscriptionStart Special Required for subscriptions with best-effort delivery, optional for subscriptions with guaranteed delivery. See Event Numbering for details.
SubscriptionStatus.notificationEvent Required For notifications that include events, this element SHALL be present. Details about specific elements within this structure are included in this table.
SubscriptionStatus.notificationEvent.eventNumber Special Required for subscriptions with best-effort delivery, optional for subscriptions with guaranteed delivery. See Event Numbering for details.
SubscriptionStatus.notificationEvent.timestamp Recommended So that clients can discover when an event actually occurred, timestamp is recommended.
SubscriptionStatus.notificationEvent.focus Special Links contained in the focus element contain resource IDs, so will or will not be present based on the payload level relevant to the notification:
  • empty : SHALL NOT be present
  • id-only : SHALL be present
  • full-resource : SHALL be present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.notificationEvent.additionalContext Special Links contained in the additionalContext element contain resource IDs and MAY or MAY not NOT exist. Presence is determined based on the payload level relevant to the notification, if they are available:
  • empty : SHALL NOT be present
  • id-only : SHOULD be present
  • full-resource : SHOULD be present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.topic Optional See Content and PHI .

2.13.8.2 2.13.9.2 Handshake Notification

When a connection to an Endpoint is established or re-established, a server MAY send a Handshake notification to the endpoint.

The client expectations upon receipt of a Handshake notification differ for each channel type (e.g., for the rest-hook channel type, a client endpoint responds to event notifications with standard HTTP response codes).

Element Optionality Notes
SubscriptionStatus.status Recommended Current status of the relevant subscription (e.g., active ).
SubscriptionStatus.type Required SHALL be handshake
SubscriptionStatus.eventsSinceSubscriptionStart Optional For a new Subscription, if this value is present it SHALL be zero (0).
A sender MAY send a handshake with a non-zero number of events, for example as process for re-establishing communication after an error state.
Note: this value SHALL NOT be incremented by sending a handshake notification.
SubscriptionStatus.notificationEvent Special A server MAY include historical events for a client with a handshake , if any exist. For example, during a reconnection process, a server MAY opt to include all events since the last successful transmission to the client. Details about specific elements within this structure are included in this table.
SubscriptionStatus.notificationEvent.eventNumber Special Required for subscriptions with best-effort delivery, optional for subscriptions with guaranteed delivery. See Event Numbering for details.
SubscriptionStatus.notificationEvent.timestamp Special If a server is including prior events, timestamp is recommended, so that clients can process historical events with proper context.
SubscriptionStatus.notificationEvent.focus Special Links contained in the focus element contain resource IDs, so will or will not be present based on the payload level relevant to the notification:
  • empty : SHALL NOT be present
  • id-only : SHALL be present if a notificationEvent is included
  • full-resource : SHALL be present if a notificationEvent is present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.notificationEvent.additionalContext Special Links contained in the additionalContext element contain resource IDs and MAY or MAY not NOT exist. Presence is determined based on the payload level relevant to the notification, if they are available:
  • empty : SHALL NOT be present
  • id-only : SHOULD be present if a notificationEvent is present
  • full-resource : SHOULD be present if a notificationEvent is present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.topic Optional See Content and PHI .

The client is not expected to take any special action in receipt of a Handshake notification beyond the channel-specific requirement for receiving an event notification.

2.13.8.3 2.13.9.3 Heartbeat Notification

A heartbeat notification is a subscription-notification Bundle of type heartbeat sent without incrementing the subscription event count, though servers MAY include the most recent event in the notification. For servers, heartbeat notifications allow systems to ensure that the connection is still alive and valid. For clients, heartbeat notifications serve as a method to detect errors in communication. Note that a client is not required to take any action in receipt of a heartbeat beyond the channel-specific requirement for receiving an event notification (e.g., accepting the notification bundle with an HTTP 200).

Heartbeat intervals are negotiated while creating a Subscription. If accepted, servers SHOULD send one a heartbeat notification whenever the channel has been inactive for the specified amount of time. For example, if the heartbeat per interval on is 60 seconds, the accepted subscription. expectation is that there is never a period of 60 seconds that passes without sending at least one notification (either event-notification or heartbeat ). Note that this is a minimum requirement - servers have discretion on how to implement testing: for example by resetting a timer when sending any notification, always sending a heartbeat on a fixed timer, etc.. Clients SHALL be able to handle receiving heartbeat notifications more often than required, and SHOULD account for miniscule differences timing (e.g., clock drift).

Element Optionality Notes
SubscriptionStatus.status Recommended Current status of the relevant subscription (e.g., active ).
SubscriptionStatus.type Required SHALL be heartbeat
SubscriptionStatus.eventsSinceSubscriptionStart Recommended The presence of this value allows clients to detect missing notifications. Recommended for subscriptions with best-effort delivery, optional for subscriptions with guaranteed delivery.
Note: this value SHALL NOT be incremented by sending a heartbeat notification.
SubscriptionStatus.notificationEvent Special A server MAY include historical events for a client with a heartbeat , if any exist. For example, a server MAY opt to include the most recent event since the last successful transmission to the client. Details about specific elements within this structure are included in this table.
SubscriptionStatus.notificationEvent.eventNumber Special If a server is including any prior events, this element is required for subscriptions with best-effort delivery and optional for subscriptions with guaranteed delivery. See Event Numbering for details.
SubscriptionStatus.notificationEvent.timestamp Special If a server is including any prior events, timestamp is recommended, so that clients can process historical events with proper context.
SubscriptionStatus.notificationEvent.focus Special Links contained in the focus element contain resource IDs, so will or will not be present based on the payload level relevant to the notification:
  • empty : SHALL NOT be present
  • id-only : SHALL be present if a notificationEvent is included
  • full-resource : SHALL be present if a notificationEvent is present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.notificationEvent.additionalContext Special Links contained in the additionalContext element contain resource IDs and MAY or MAY not NOT exist. Presence is determined based on the payload level relevant to the notification, if they are available:
  • empty : SHALL NOT be present
  • id-only : SHOULD be present if a notificationEvent is present
  • full-resource : SHOULD be present if a notificationEvent is present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.topic Optional See Content and PHI .

2.13.8.4 2.13.9.4 Query Status

Clients can ask a server at any time for the current status of a Subscription, for example via the $status operation .

Since the $status operation is part of the FHIR REST API, the guidance below assumes that a user has been authenticated and is allowed access to all relevant resources.

Element Optionality Notes
SubscriptionStatus.status Required Current status of the relevant subscription (e.g., active ).
SubscriptionStatus.type Required SHALL be query-status
SubscriptionStatus.eventsSinceSubscriptionStart Special Required for subscriptions with best-effort delivery, optional for subscriptions with guaranteed delivery. See Event Numbering for details.
Note: this value SHALL NOT be incremented by sending a query-status notification.
SubscriptionStatus.notificationEvent Special A query-status notification MAY contain recent notifications.
SubscriptionStatus.topic Recommended See Content and PHI , but note that guidance will vary since there is an active user session.

2.13.8.5 2.13.9.5 Query Event

Some servers may allow clients to ask for events which have already occurred, for example via the $events operation .

Since the $events operation is part of the FHIR REST API, the guidance below assumes that a user has been authenticated and the server has filtered any results according to what the user is allowed access.

Element Optionality Notes
SubscriptionStatus.status Recommended Current status of the relevant subscription (e.g., active ).
SubscriptionStatus.type Required SHALL be query-event .
SubscriptionStatus.eventsSinceSubscriptionStart Recommended This value is allows clients to know if they are missing notifications. Recommended for subscriptions with best-effort delivery and optional for subscriptions with guaranteed delivery.
Note: this value SHALL NOT be incremented by sending a query-event bundle.
See Event Numbering for more information.
SubscriptionStatus.notificationEvent Required For notifications that include events, this element SHALL be present. Details about specific elements within this structure are included in this table.
SubscriptionStatus.notificationEvent.eventNumber Special Required for subscriptions with best-effort delivery, optional for subscriptions with guaranteed delivery. See Event Numbering for details.
SubscriptionStatus.notificationEvent.timestamp Recommended So that clients can discover when an event actually occurred, timestamp is recommended.
SubscriptionStatus.notificationEvent.focus Special Links contained in the focus element contain resource IDs, so will or will not be present based on the payload level relevant to the notification:
  • empty : SHALL NOT be present
  • id-only : SHALL be present
  • full-resource : SHALL be present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.notificationEvent.additionalContext Special Links contained in the additionalContext element contain resource IDs and MAY or MAY not NOT exist. Presence is determined based on the payload level relevant to the notification, if they are available:
  • empty : SHALL NOT be present
  • id-only : SHOULD be present
  • full-resource : SHOULD be present
Note that servers SHOULD include the Reference.type element if if the type is not specified in Reference.reference
SubscriptionStatus.topic Recommended See Content and PHI , but note that guidance will vary since there is an active user session.

2.13.9 2.13.10 Notifications and Errors

The SubscriptionStatus resource is key in detecting various errors in communication and processing. For more information, see Managing Subscriptions and Errors in the Subscriptions Framework page.

2.13.10 2.13.11 Search Parameters

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

(No search parameters for this resource)