Subscriptions R5 Backport
1.2.0-ballot - ballot

Subscriptions R5 Backport, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 1.2.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-subscription-backport-ig/ and changes regularly. See the Directory of published versions

## Workflow

Page standards status: Informative

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:

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

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

Sequence diagram of creating a FHIR Subscription in FHIR R4

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.