This page offers a high-level, SoFA-developer-focused overview of the HALO specification. It is not a substitute for the detailed implementation pages, but rather a directional guide to help orient you within the specification, highlight the most relevant sections, and clarify how SoFA fits into the broader HALO ecosystem.
Why HALO Matters to SoFA Developers
By implementing a HALO-conformant SMART on FHIR Accelerator (SoFA) you provide:
Nation-wide enablement – Empower PoC systems that lack public FHIR servers or IdPs to participate in SMART launches and interoperate with any HALO-listed SMART Apps.
Jurisdictional leverage – Centralize security, context management, and data storage once, rather than duplicating complex functionality across every PoC vendor.
Standards alignment – Alignment with well-established specifications including FHIR R4, SMART App Launch v2.1, Subscriptions R5 Backport, and the Pan-Canadian CA Core+ implementation guide to deliver a future-proof and standardized ecosystem.
Event-driven workflows – Push updates to PoCs in real time through topic-based Subscriptions instead of polling or file drops.
Data-governance control – Enforce consistent privacy, consent, and retention policies for all participating applications, including any jurisdiction-specific requirements.
Integration Patterns at a Glance: PoC vs. SoFA
Component
Base SMART on FHIR (SoF)
SMART on FHIR Accelerator (SoFA)
FHIR Server
Local to PoC
Jurisdictional, operated by SoFA
IdP / Auth Server
Local or delegated
Jurisdictional, integrated with SoFA
Context Management
Internally managed by the PoC
Uploaded via $set-context and bound to a unique identifier (launchID)
Data Write-back
Direct to PoC FHIR server
Written to the SoFA and propagated back to the PoC via FHIR Subscriptions
Cleanup
Local policies
Triggered via $clear-context, and/or automated based on internal policies
Key HALO Sections for SoFA Developers
Business Requirements – Understand the overarching requirements for SoFA systems from a business lens.
User Stories / Use Cases – Understand how SoFA supports clinical workflows by enabling launch context, mediating authorization, and facilitating data exchange between PoC systems and SMART Apps in standardized ways.
Overall Architecture – Understand how your system fits into the broader HALO ecosystem and which systems you should expect to interact with.
App Launch – See the complete end-to-end flow your SoFA must support, from launch URL to token exchange, and where your FHIR & IdP endpoints are referenced.
Operation: $set-context – Learn the exact parameters you must accept, how to store resources atomically, create launchID, and validate PoC Subscriptions.
Operation: $clear-context – Know how and when to purge context resources and how to return a compliant OperationOutcome on success or failure.
Subscriptions – Implement the sofa-content-update topic, lifecycle (create → handshake → heartbeat → $events → $status), and notification format.
Profile: SetContextTransactionBundle – Understand how PoC systems will structure the resource Bundle used to populate the SoFA within the $set-context operation.
Profile: SetContextInputParameters – Understand how PoC systems will structure the overarching Parameters resource sent in the $set-context operation.
Profile: SetContextOutputParameters – Understand how to structure overarching Parameters resource returned in the response for $set-context.
Privacy and Security Guidance – Review jurisdictional and national privacy and security guidelines, best practices, and legislative considerations to ensure your SoFA implementation meets applicable requirements for safeguarding patient data and supporting secure interoperability.
Testing & Conformance Expectations
HALO conformance is comprised of several technical actors and transactions across several HALO Profiles. These responsibilities are grouped and tested leveraging four core business use cases.
From a SoFA perspective, the following use cases apply:
UC-02: Care Provider Accesses Additional Patient Data via SMART App
UC-03: Care Provider Shares Patient Data with a SMART App
UC-04: Care Provider Receives External Information via SMART App
Within these use cases SoFA systems are responsible for fulfilling roles such as Resource Server, Context Manager, Subscription Manager, and Notification Producer.
In addition to the HALO-specific testing, SoFA implementers should ensure compliance with the following external specifications:
FHIR Profiling: All resources – inbound or outbound – must be constructed using FHIR R4 (v.4.0.1) and, where profiled, be profiled according to CA Core+.
SMART Launch: Handling of launches must be done in accordance with the EHR Launch flow defined within the SMART App Launch v2.1.0 specification.
Publish a complete CapabilityStatement with HALO-specific capabilities (e.g., CA Core+, HALO profiles, backport-SubscriptionTopic, $set-context, $clear-context, $events, $status`).
Host a .well-known/smart-configuration endpoint with valid authorize, token, and jwks_uri values.
Enforce JSON and XML support; reject resources not conforming to CA Core+.
Use the FHIR Async pattern if asynchronous notification delivery (e.g., via message queue) is supported.
$set-context
Validate FHIR resources sent in the request (the wrapping Parameters resource, the contained Bundle resource, and there resources inside of the Bundle).
Process resource creations transactionally and roll back on failure.
Link created resources to an opaque launch ID representing the current context.
Return the launch ID back to the PoC in the response so that it can be leveraged in the subsequent SMART launch.
Return the resource IDs back to the PoC in the response so that they can be mapped to their original local resource IDs
Reject requests from PoC systems without an active Subscription to the SoFA Content Update topic.
Restrict access to App launch sessions and their associated data to the user who owns the launch context.
Ensure that context provided by the PoC is communicated to the SMART App during launch.
$clear-context
Delete context resources associated with the launch ID.
Return informative OperationOutcome resources.
Identity & Authorization
Ensure that the Authorization Server supports the SMART on FHIR additions to the token response such as launch context parameters and claims within the ID token.
Support SMART-style scopes
Implement full support for both the client credentials and authorization code flows, as defined in the HALO, SMART App Launch, and OAuth 2.0 specifications.
Inform PoC vendors of additional security requirements (e.g., mTLS)
Subscriptions & Notifications
Support subscriptions to the SoFA Content Update topic
Support both rest-hook & websocket Subscription channels
Implement and support the handshake and heartbeat mechanisms
Increment eventNumber with each new event issued for a given Subscription and expose missed events via the $events operation.
Ensure notifications are delivered to the PoC before
Committing any resource changes within the SoFA; otherwise roll back.
Informing the SMART App that the interaction was successful; otherwise return an error.
Ensure that the notifications sent to the PoC include any headers provided within their initial Subscription (e.g,. the Authorization header)
