Subscriptions R5 Backport
1.1.0 - Standard for Trial Use International flag

This page is part of the Subscriptions R5 Backport (v1.1.0: STU 1.1) based on FHIR v4.3.0. This is the current published version in its permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions

Workflow

This section gives an overview of the workflow for both Servers and Clients to work with Subscriptions. Each channel MAY vary slightly from this general overview - specifically around interactions involving the Endpoint (e.g., when using a rest-hook the client must pre-configure an HTTP endpoint which the server validates, but when using websockets the client simply connects to the server).

Overview

The workflow for topic-based subscriptions can be broken down into three matched process steps for each a server or client:

Implement TopicsSubscription NegotiationSend NotificationsTopic DiscoveryRequest a SubscriptionReceive NotificationsServerClient
High-level workflow overview
# Server Client
1. Implement Topic-Based Subscriptions Topic Discovery
2. Subscription Negotiation Request a Subscription
3. Send Notifications Receive Notifications

Workflow: FHIR R4B

FHIR R4B ServerFHIR R4B ServerClientClientEndpointServer Implementation1Implement core Subscription functionality2Implement topics and advertise viaSubscriptionTopicresourcesClient Implementation[Client Topic Discovery]3Search for a supportedSubscriptionTopic, e.g.:GET .../SubscriptionTopic?[params]4Bundlewith matchingSubscriptionTopicresources[Client Subscription Request]5Create, configure, or initializethe necessary EndpointEndpoint6Create a Subscription, e.g.:POST .../SubscriptionServer Accepting or Rejecting a Subscription[Valid Subscription, without Handshake]7Success: status =activeSend notifications...[Valid Subscription, with Handshake Success]8Success: status =requested9Handshake10Success, e.g.:200: OKUpdate Subscription:Subscription.status: activeSend notifications...[Valid Subscription, with Handshake Failure]11Success: status =requested12Handshake13Failure, e.g.:404: Not FoundUpdate Subscription:Subscription.status: error[Invalid Subscription]14Failure, e.g.:400: Bad RequestNo subscription was created
Sequence diagram of creating a FHIR Subscription in FHIR R4B
  1. Server implements the core functionality required for subscriptions (see Conformance).
  2. Server implements one or more SubscriptionTopic resources. Implementation is specific to each topic, and will vary between servers.
  3. Client asks the server for the list of supported SubscriptionTopic resources, via querying the resource.
  4. Server responds with a searchset Bundle.
  5. Client ensures that the endpoint is prepared (if applicable - see Channels).
  6. Client requests a Subscription (e.g., via POST, PUT, etc.).
  7. Server MAY accept the Subscription request and mark it active (e.g., supported channel and payload, no handshake required).
  8. Server MAY accept the Subscription request and mark it requested (e.g., supported channel and payload, handshake required).
  9. Server sends a handshake bundle to the endpoint.
  10. If the Endpoint responds appropriately, per the channel requirements (e.g., in REST an HTTP Success code such as 200), the Server updates the subscription to active.
  11. Server MAY accept the Subscription request and mark it requested (e.g., supported channel and payload, handshake required).
  12. Server sends a handshake bundle to the endpoint.
  13. If the handshake fails (e.g., connection failure, bad response, etc.), the Server updates the subscription to error.
  14. Server MAY reject the Subscription request (e.g., unsupported channel type).

Once the subscription is active, notifications will be sent according to the Channel. Note that error states may occur, see Handling Errors for more information.

Workflow: FHIR R4

FHIR R4 ServerFHIR R4 ServerClientClientEndpointServer Implementation1Implement core Subscription functionality2Implement topics and optionally advertiseClient Topic Discovery[CapabilityStatement with Extension Discovery]3Search for a supportedSubscriptionTopiccanonical URL in aCapabilityStatement, e.g.:GET .../CapabilityStatement4CapabilityStatementwith topic canonical URLsinrest.resource[subscription].extension[.../capabilitystatement-subscriptiontopic-canonical][CapabilityStatement with Instantiates Discovery]5Search for a known IGCapabilityStatementinstantiated in a serverCapabilityStatement6CapabilityStatementwith IG capability canonical URLsin theinstantiateselement[CapabilityStatement with Implementation Guide Discovery]7Search for a known IG canonicallisted in a serverCapabilityStatement8CapabilityStatementwith IG canonical URLsin theimplementationGuideelementClient Topic Discovery[Client Subscription Request]9Create, configure, or initializethe necessary EndpointEndpoint10Create a Subscription, e.g.:POST .../SubscriptionServer Accepting or Rejecting a Subscription[Valid Subscription, without Handshake]11Success: status =activeSend notifications...[Valid Subscription, with Handshake Success]12Success: status =requested13Handshake14Success, e.g.:200: OKUpdate Subscription:Subscription.status: activeSend notifications...[Valid Subscription, with Handshake Failure]15Success: status =requested16Handshake17Failure, e.g.:404: Not FoundUpdate Subscription:Subscription.status: error[Invalid Subscription]18Failure, e.g.:400: Bad RequestNo subscription was created
Sequence diagram of creating a FHIR Subscription in FHIR R4B
  1. Server implements the core functionality required for subscriptions (see Conformance).
  2. Server implements one or more subscription topics. Implementation is specific to each topic, and will vary between servers.
  3. Optional Client attempts topic discovery via the CapabilityStatement SubscriptionTopic Canonical extension.
  4. Server responds with its CapabilityStatement.
  5. Optional Client attempts topic discovery via the CapabilityStatement.instantiates element.
  6. Server responds with its CapabilityStatement.
  7. Optional Client attempts topic discovery via the CapabilityStatement.implementationGuide element.
  8. Server responds with its CapabilityStatement.
  9. Client ensures that the endpoint is prepared (if applicable - see Channels).
  10. Client requests a Subscription (e.g., via POST, PUT, etc.).
  11. Server MAY accept the Subscription request and mark it active (e.g., supported channel and payload, no handshake required).
  12. Server MAY accept the Subscription request and mark it requested (e.g., supported channel and payload, handshake required).
  13. Server sends a handshake bundle to the endpoint.
  14. If the Endpoint responds appropriately, per the channel requirements (e.g., in REST an HTTP Success code such as 200), the Server updates the subscription to active.
  15. Server MAY accept the Subscription request and mark it requested (e.g., supported channel and payload, handshake required).
  16. Server sends a handshake bundle to the endpoint.
  17. If the handshake fails (e.g., connection failure, bad response, etc.), the Server updates the subscription to error.
  18. Server MAY reject the Subscription request (e.g., unsupported channel type).

Once the subscription is active, notifications will be sent according to the Channel. Note that error states may occur, see Handling Errors for more information.