Release 5 Preview #3

2.48 Resource SubscriptionStatus - Content

FHIR Infrastructure Work GroupMaturity Level: 0 Trial UseSecurity Category: Business Compartments: Not linked to any defined compartments

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

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.

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.

No resources refer to this resource directly.

This resource does not implement any patterns.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SubscriptionStatus TUDomainResourceStatus information about a Subscription provided during event notification
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... status Σ0..1coderequested | active | error | off | entered-in-error
Subscription State (Required)
... type ?!Σ1..1codehandshake | heartbeat | event-notification | query-status
SubscriptionNotificationType (Required)
... eventsSinceSubscriptionStart Σ0..1integer64Events since the Subscription was created
... subscription Σ1..1Reference(Subscription)Reference to the Subscription responsible for this notification
... topic Σ1..1canonical(SubscriptionTopic)Reference to the SubscriptionTopic this notification relates to
... error Σ0..*CodeableConceptList of errors on the subscription
Subscription Error Codes (Example)

doco Documentation for this format

UML Diagram (Legend)

SubscriptionStatus (DomainResource)The status of the subscription, which marks the server state for managing the subscriptionstatus : code [0..1] « The status of a subscription at the time this notification was generated. (Strength=Required)SubscriptionState! »The type of event being conveyed with this notificaiton (this element modifies the meaning of other elements)type : code [1..1] « The type of notification represented by the status message. (Strength=Required)SubscriptionNotificationType! »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 notificationseventsSinceSubscriptionStart : integer64 [0..1]The total number of actual events represented within this notification. For handshake and heartbeat notifications, this will be zero or not present. For event-notifications, this number may be one or more, depending on server batchingeventsInNotification : integer [0..1]The reference to the Subscription which generated this notificationsubscription : Reference [1..1] « Subscription »The reference to the SubscriptionTopic for the Subscription which generated this notificationtopic : canonical [1..1] « SubscriptionTopic »A record of errors that occurred when the server processed a notificationerror : CodeableConcept [0..*] « Codes to represent subscription error details. (Strength=Example)SubscriptionErrorCodes?? »

Turtle Template

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


[ a fhir:SubscriptionStatus;
  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:SubscriptionStatus.status [ code ]; # 0..1 requested | active | error | off | entered-in-error
  fhir:SubscriptionStatus.type [ code ]; # 1..1 handshake | heartbeat | event-notification | query-status
  fhir:SubscriptionStatus.eventsSinceSubscriptionStart [ integer64 ]; # 0..1 Events since the Subscription was created
  fhir:SubscriptionStatus.eventsInNotification [ integer ]; # 0..1 The number of actual notifications represented by this bundle
  fhir:SubscriptionStatus.subscription [ Reference(Subscription) ]; # 1..1 Reference to the Subscription responsible for this notification
  fhir:SubscriptionStatus.topic [ canonical(SubscriptionTopic) ]; # 1..1 Reference to the SubscriptionTopic this notification relates to
  fhir:SubscriptionStatus.error [ CodeableConcept ], ... ; # 0..* List of errors on the subscription
]

Changes since R3

This resource did not exist in Release 2

This analysis is available as XML or JSON.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SubscriptionStatus TUDomainResourceStatus information about a Subscription provided during event notification
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... status Σ0..1coderequested | active | error | off | entered-in-error
Subscription State (Required)
... type ?!Σ1..1codehandshake | heartbeat | event-notification | query-status
SubscriptionNotificationType (Required)
... eventsSinceSubscriptionStart Σ0..1integer64Events since the Subscription was created
... subscription Σ1..1Reference(Subscription)Reference to the Subscription responsible for this notification
... topic Σ1..1canonical(SubscriptionTopic)Reference to the SubscriptionTopic this notification relates to
... error Σ0..*CodeableConceptList of errors on the subscription
Subscription Error Codes (Example)

doco Documentation for this format

UML Diagram (Legend)

SubscriptionStatus (DomainResource)The status of the subscription, which marks the server state for managing the subscriptionstatus : code [0..1] « The status of a subscription at the time this notification was generated. (Strength=Required)SubscriptionState! »The type of event being conveyed with this notificaiton (this element modifies the meaning of other elements)type : code [1..1] « The type of notification represented by the status message. (Strength=Required)SubscriptionNotificationType! »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 notificationseventsSinceSubscriptionStart : integer64 [0..1]The total number of actual events represented within this notification. For handshake and heartbeat notifications, this will be zero or not present. For event-notifications, this number may be one or more, depending on server batchingeventsInNotification : integer [0..1]The reference to the Subscription which generated this notificationsubscription : Reference [1..1] « Subscription »The reference to the SubscriptionTopic for the Subscription which generated this notificationtopic : canonical [1..1] « SubscriptionTopic »A record of errors that occurred when the server processed a notificationerror : CodeableConcept [0..*] « Codes to represent subscription error details. (Strength=Example)SubscriptionErrorCodes?? »

Turtle Template

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


[ a fhir:SubscriptionStatus;
  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:SubscriptionStatus.status [ code ]; # 0..1 requested | active | error | off | entered-in-error
  fhir:SubscriptionStatus.type [ code ]; # 1..1 handshake | heartbeat | event-notification | query-status
  fhir:SubscriptionStatus.eventsSinceSubscriptionStart [ integer64 ]; # 0..1 Events since the Subscription was created
  fhir:SubscriptionStatus.eventsInNotification [ integer ]; # 0..1 The number of actual notifications represented by this bundle
  fhir:SubscriptionStatus.subscription [ Reference(Subscription) ]; # 1..1 Reference to the Subscription responsible for this notification
  fhir:SubscriptionStatus.topic [ canonical(SubscriptionTopic) ]; # 1..1 Reference to the SubscriptionTopic this notification relates to
  fhir:SubscriptionStatus.error [ CodeableConcept ], ... ; # 0..* List of errors on the subscription
]

Changes since Release 3

This resource did not exist in Release 2

This analysis is available as XML or JSON.

 

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

PathDefinitionTypeReference
SubscriptionStatus.status The status of a subscription at the time this notification was generated.RequiredSubscriptionState
SubscriptionStatus.type The type of notification represented by the status message.RequiredSubscriptionNotificationType
SubscriptionStatus.error Codes to represent subscription error details.ExampleSubscriptionErrorCodes

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

The primary notification is a notification about an event.

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

When a connection to an Endpoint is established, a server MAY send a Handshake notification to the endpoint. A Handshake notification is a subscription-notification Bundle sent without incrementing the subscription event count.

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.

Servers MAY periodically send notifications across a channel to ensure that the connection is still alive and valid (e.g., in accordance with a client's requested heartbeat interval). The Heartbeat notification is an empty subscription-notification Bundle sent without incrementing the subscription event count.

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

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

  • The SubscriptionStatus.eventsSinceSubscriptionStart element indicates the number of unique events that have triggered notification attempts on this Subscription inclusive of the current notification being sent.

    • In the case of a handshake notification, this count will be zero (0) if present.

    • In the case of a heartbeat or query-status notifications, this count will be the same as the last notification and will not be incremented due to the current notification.

    • In the case of an event notifications, the event count will be incremented by the number of notifications contained within this bundle (often a single notification, though servers may choose to batch notifications within a short time interval).

    • In the case of an event notification that cannot be delivered (e.g., because a client endpoint is offline), the server MAY retry delivery but does not increment the event count for each retry; the count represents unique events, not unique delivery attempts.

  • The SubscriptionStatus.eventsInNotification element represents the number of event notifications conveyed by the Bundle. This helps clients:

    • Determine if a notification requires further processing (e.g., a client might discard handshake and heartbeat notifications)

    • Determine the number of events it should expeect to find in follow-on queries when the in empty payload type is used

    • Handle batched results (e.g., a server sending at max one notification per second)

    For notifications of types other than event, eventsInNotification will be zero (0) if present.

  • The SubscriptionStatus.status element represents the Subscription status values at the time the notification is generated. Note that the status MAY change between the time the notification is sent and the time it is received/processed, and therefore this status recorded in the notification is not guaranteed to represent status at the time of receipt. The field is useful as a hint to inform the client if the server has encountered errors in notifications immediately preceding this notification.

  • The SubscriptionStatus.topic element provides a canonical reference to the SubscriptionTopic resource relevant to this notification. Depending on how the SubscriptionTopic was defined, this MAY point to the the server that generated the notification or to an external canonical URL.

  • The SubscriptionStatus.subscription element references the Subscription resource that triggered this notification, as an absolute URL for the Subscription resource on the server that generated the notification.