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

2.48 Resource SubscriptionStatus - Content

FHIR Infrastructure Work Group

Maturity Level: 0

Trial Use

Security Category: Business

Compartments: Not linked to any defined compartments

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

2.48.3 References

No resources refer to this resource directly.

This resource does not implement any patterns.

2.48.4 Resource Content

 

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

2.48.4.1 Terminology Bindings

Path	Definition	Type	Reference
SubscriptionStatus.status		Required	SubscriptionState
SubscriptionStatus.type		Required	SubscriptionNotificationType
SubscriptionStatus.error		Example	SubscriptionErrorCodes

2.48.5 Notification Types

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.

2.48.5.1 Event Notification

The primary notification is a notification about an event.

• Example event notification

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

2.48.5.2 Handshake Notification

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.

• Example handshake notification

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

• Example heartbeat notification

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.

2.48.5.4 Query Status

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

• Example query-status notification

2.48.5.5 Subscription Status

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