Pan-Canadian HALO Specification
HALO is a standardized “visual interactive framework” that would enable web applications to plug into their existing design.
This profile defines the use of Subscriptions R5 Backport FHIR Implementation Guide within the HALO framework to enable asynchronous, event-driven communication between the SMART on FHIR Accelerator (SoFA) and subscribing Point of Care (PoC) systems. It formalizes the interactions required to create, manage, and consume Subscriptions for the HALO-defined SOFA Content Update topic, which serves as the mechanism for notifying PoC systems when relevant clinical resources are created or modified within the SoFA.
The CA:FSub profile includes both REST-hook and WebSocket delivery channels and specifies a minimal, but sufficient, set of transactions necessary to support reliable and consistent event propagation, recovery, and lifecycle management of FHIR Subscriptions. This ensures that PoC systems remain synchronized with SoFA-hosted patient data introduced or updated by SMART applications launched via the HALO context.
The scope of this profile is limited to conformance requirements needed for participation in the HALO Subscription workflow. Additional capabilities defined in the FHIR Subscriptions R5 Backport specification, such as email or SMS channels, are out of scope for this release.
See the Subscriptions page for more information.
| Actor | Actor Option |
|---|---|
| Subscription Requester | |
| Susbcription Manager | |
| Notification Consumer | REST Hook WebSocket |
| Notification Producer | REST Hook WebSocket |
A system that creates subscription resources, defines the conditions for triggering notifications, and specifies how and where those notifications are delivered to the subscriber.
A system that maintains subscription resources, evaluates triggering criteria based on defined events, manages subscription lifecycle, and coordinates notification delivery.
A system that generates and sends notifications to consumers whenever subscription-defined events or conditions are met.
To be conformant, a system in this role must implement both options:
A system that receives and processes notifications generated by the Notification Producer, acting upon the provided data or alerts as defined by the subscription.
To be conformant, a system in this role must implement at least one of the options:
The following diagram provides an overview of the Actors directly involved in the CA:FSub profile and the relevant Transactions between them.
The tables below lists the transactions for each actor directly participating in the CA:FSub profile. To claim compliance with CA:FSub, an actor shall support all required transactions (labeled “R”).
| Actor | Transaction | Optionality |
|---|---|---|
| Subscription Requester | Create Subscription [CA:FSub-1] Update Subscription [CA:FSub-2] Delete Subscription [CA:FSub-3] Retrieve Subscription Status [CA:FSub-4] Retrieve Past Events [CA:FSub-5] |
R O O R R |
| Subscription Manager | Create Subscription [CA:FSub-1] Update Subscription [CA:FSub-2] Delete Subscription [CA:FSub-3] Retrieve Subscription Status [CA:FSub-4] Retrieve Past Events [CA:FSub-5] |
R R R R R |
The table is applicable for all Actor Options (REST Hook and WebSocket).
| Actor | Transaction | Optionality |
|---|---|---|
| Notification Producer | Send Handshake Notification [CA:FSub-8] Send Heartbeat Notification [CA:FSub-9] Send Event Notification [CA:FSub-10] |
R R R |
| Notification Consumer | Send Handshake Notification [CA:FSub-8] Send Heartbeat Notification [CA:FSub-9] Send Event Notification [CA:FSub-10] |
R R R |
The table below is applicable for WebSocket Actor Option only.
| Actor | Transaction | Optionality |
|---|---|---|
| Notification Producer | Get WS Binding Token [CA:FSub-6] Connect and Bind with Token [CA:FSub-7] |
R R |
| Notification Consumer | Get WS Binding Token [CA:FSub-6] Connect and Bind with Token [CA:FSub-7] |
R R |
The Subscription Requester initiates a new FHIR Subscription by performing a POST operation on the Subscription Manager's /Subscription endpoint. The request includes configuration such as the topic URL (e.g., http://fhir.infoway-inforoute.ca/io/HALO/SubscriptionTopic/sofa-content-update), delivery channel (e.g., rest-hook or websocket), and any heartbeat or timeout extensions. The Subscription Manager validates the configuration and persists the Subscription in a requested state. If valid, the Subscription Manager initiates the handshake workflow.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
The Subscription Requester updates an existing Subscription by performing a PUT request to the /Subscription/[id] endpoint. This is commonly used to change the Subscription status (e.g., from off to requested) or update delivery settings. The Subscription Manager validates the changes and applies them, including re-triggering the handshake if necessary.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
The Subscription Requester removes a Subscription by issuing a DELETE request to the /Subscription/[id] endpoint. Upon receipt, the Subscription Manager deletes (or soft deletes) the resource and halts any further notifications associated with that Subscription.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
The Subscription Requester queries the status of a Subscription by invoking the $status operation with a GET request to /Subscription/[id]/$status. The Subscription Manager responds with a Bundle that contains a profiled Parameters resource representing the SubscriptionStatus in R4 (as defined by the R5 Backport). This Parameters resource conveys the current SubscriptionStatus details, including the status, topic, notification type, and event counts.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
The Subscription Requester retrieves historical notifications by invoking the $events operation on the /Subscription/[id]/$events endpoint. This is a GET request and may include parameters such as eventsSinceNumber and content. The Subscription Manager returns a Parameters resource with a Bundle containing past events and the associated FHIR resources. This is used to recover from missed notifications.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
REST Hook Option
Not Applicable.
WebSocket Option
The Notification Consumer requests a WebSocket binding token by invoking $get-ws-binding-token on a Subscription instance. The Notification Producer validates access and returns the token, its expiry, and the WebSocket endpoint URL.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
REST Hook Option
Not Applicable.
WebSocket Option
The Notification Consumer initiates a WebSocket connection using the URL returned in the $get-ws-binding-token operation, and authenticates by sending the returned token in a bind-with-token message. Upon successful validation, the Notification Producer associates the connection with the Subscription.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
REST Hook Option
When a Subscription with a rest-hook channel is created or updated to requested, the Notification Producer sends a handshake notification Bundle to the endpoint specified in the Subscription. The Notification Consumer must respond with 200 OK. If successful, the Subscription status is updated to active; otherwise, the Subscription remains in an error or requested state.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
WebSocket Option
After successfully binding to the WebSocket, the Notification Producer sends a handshake notification over the socket. This confirms the Subscription is reachable and completes the activation process. No acknowledgment is required from the Notification Consumer. If successful, the Subscription status is updated to active; otherwise, the Subscription remains in an error or requested state.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
REST Hook Option
To verify ongoing connectivity, the Notification Producer periodically sends heartbeat notifications to the Notification Consumer’s endpoint based on the configured heartbeatPeriod. The Notification Consumer is expected to return 200 OK. Heartbeats do not increment the eventNumber.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
WebSocket Option
The Notification Producer sends periodic heartbeat notifications over the established WebSocket connection to indicate that the Subscription is still active. No acknowledgment is required from the Notification Consumer.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
REST Hook Option
When a resource change triggers an event for an active Subscription, the Notification Producer sends a notification Bundle to the Notification Consumer’s endpoint. The Bundle includes metadata such as the SubscriptionStatus and the affected FHIR resource(s). If the resource represents an update, the Notification Consumer uses existing ID mappings established during the $set-context operation (see: Operation: $set-context) to locate and update the corresponding local record. If the resource is newly created, the Notification Consumer creates a corresponding local resource instance and establishes a new mapping to the SoFA logical ID. In all cases, the Notification Consumer records the associated event number and acknowledges receipt by responding with 200 OK.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.
WebSocket Option
When a resource change triggers an event for an active Subscription, the Notification Producer delivers a notification Bundle over the established WebSocket connection to the Notification Consumer. The Bundle includes metadata such as the SubscriptionStatus and the affected FHIR resource(s). If the resource represents an update, the Notification Consumer uses existing ID mappings established during the $set-context operation (see: Operation: $set-context) to locate and update the corresponding local record. If the resource is newly created, the Notification Consumer creates a corresponding local resource instance and establishes a new mapping to the SoFA logical ID. In all cases, the Notification Consumer processes the event and records the associated event number to maintain continuity. Unlike REST-hook delivery, no explicit acknowledgment is required over the WebSocket connection.
See the Subscriptions page and the Subscriptions R5 Backport FHIR Implementation Guide specification for more information.