PoC Developers

This page provides a high-level, PoC-developer-oriented overview of the HALO specification. It is intended as a starting point to help you navigate the most relevant sections, understand how PoC systems interact with SMART Apps in both base SMART on FHIR and SoFA-enabled environments, and quickly identify the requirements, workflows, and conformance expectations for your role. It is not a substitute for the detailed implementation pages in the specification, but rather a directional guide to point you toward them.

Why HALO Matters to App Catalog Developers

By conforming to HALO, PoC systems (typically EMRs or clinical portals) gain:

• App Ecosystem Access – Discover and launch jurisdictionally approved SMART Apps directly from your interface via the HALO App Catalog.
• Interoperable Application Integration – Enable SMART launches using either local infrastructure or jurisdictional services like the SMART on FHIR Accelerator (SoFA).
• Simplified Development – Offload the complexities of SMART context packaging, FHIR server exposure, and token exchange by leveraging shared infrastructure when needed.

Whether your system offers full SMART on FHIR capabilities or requires external support, HALO ensures you're interoperable and future-proof.

Integration Patterns at a Glance: SoF 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)
App Launch	Direct with local iss and launch values	Direct with jurisdictional iss and launch parameters
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 PoC Developers

All PoC Implementations (SoF & SoFA)

• Business Requirements – Understand the overarching requirements for PoC systems from a business lens.
• User Stories / Use Cases – Understand how your system enables care providers to discover, launch, and interact with SMART Apps as part of their clinical workflows, including how patient context and data are shared and received.
• Overall Architecture – Understand how your system fits into the broader HALO ecosystem and which systems you should expect to interact with.
• App Catalog – Understand how to query and discover jurisdictionally approved applications, what metadata is available foreach, and how to leverage this information to drive the launch flow.
• App Launch– Based on your preferred flow (SoF or SoFA), learn how the SMART launch flow takes shape in HALO and what you as the PoC developer are responsible for providing.
• Privacy and Security Guidance – Review jurisdictional and national privacy and security guidelines, best practices, and legislative considerations to ensure your PoC implementation meets applicable requirements for safeguarding patient data and supporting secure interoperability.

PoC Implementations Leveraging a SoFA Integration

• Operation: $set-context – Know how to construct and transmit launch context to SoFA, maintaining logical ID-based mappings between local resources and their corresponding resources created in SoFA.
• Operation: $clear-context – Learn how you can clean up context after an App session completes.
• Subscriptions – Understand how data write back is implemented in the SoFA launch flow and what is expected from a PoC in this configuration.
• Profile: SetContextTransactionBundle – Understand how to structure the resource Bundle used to populate the SoFA within the $set-context operation.
• Profile: SetContextInputParameters – Understand how the Parameters resource sent in the $set-context operation is constructed.
• Profile: SetContextTransactionResponseBundle – Understand the structure of the transaction-response Bundle returned by the SoFA in response to the $set-context operation.
• Profile: SetContextOutputParameters – Understand the structure of the overarching Parameters resource returned in the response for $set-context.

Testing & Conformance Expectations

HALO conformance is comprised of several technical actors and transactions across several HALO Profiles. These responsibilities are grouped and tested leveraging the four core business use cases.

From a PoC perspective, the following use cases apply:

• UC-01: Care Provider views and selects SMART Apps that are of interest
• 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 PoC systems are responsible for fulfilling roles such as App Catalog Consumer, Launch Initiator, Resource Server, Authorization Server, Context Source, Subscription Producer, and Notification Consumer with some variance based on whether they are implementing the base SMART on FHIR (SoF) flow or the SMART on FHIR Accelerator (SoFA) flow.

For more details regarding testing and conformance expectations for PoC systems, see the see the Interoperability Recommendations and Technical Use Case Sequence Diagrams pages.

In addition to the HALO-specific testing, PoC vendors 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 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.
• FHIR Subscriptions: In the SoFA flow, resource writes are handled using notifications following FHIR Subscriptions R5 Backport v1.2.0-ballot.

Responsibilities & Recommendations Checklist

App Catalog Integration

• Query the HALO App Catalog endpoint to retrieve approved SMART Apps.
• Parse and render metadata about the Apps (e.g., name, icon, description) to your users.
• Use the Application.scopes field from the catalog entry to determine required context
• Consider support bilingual metadata publishing (English and French)

App Launch

All Flows (SoF & SoFA):

• Determine whether to use base SMART launch or SoFA launch based on system capabilities.
• Construct SMART launch URLs including iss and launch parameters.
• Implement the launch mechanism (e.g., new tab, embedded window).

Base SMART on FHIR (SoF) Launch Flow:

• Host a conformant .well-known/smart-configuration endpoint.
• Generate and resolve launch codes that represent the launch context of the App for the currently authenticated user.
• Ensure that the Authorization Server understands the launch context and returns the launch context parameters to the SMART App in the token response.
• Support SMART-style scopes.
• Enforce JSON and XML support

SMART on FHIR Accelerator (SoFA) Launch Flow:

• Work with your jurisdiction to implement a pathway where your users can authorize Apps to obtain a jurisdictional access token (auth code flow) that allows execution of the $set-context operation.
• Construct and trigger the $set-context operation.
• Store local PoC-to-SoFA ID mappings using the SoFA resource IDs returned in the $set-context response bundle.

Subscriptions & Notifications (SoFA only)

All Subscription Implementations (REST Hook & WebSocket)

• Work with your jurisdiction to implement a workflow for obtaining a system-level access token (client credential flow) that provides access to Subscription creation workflows.
• Implement either the websocket or rest-hook channels based on your system's needs.
• Implement functionality to create and maintain instance-wide Subscriptions to the SoFA Content Update topic.
• Avoid creating multiple concurrent Subscriptions to the SoFA Content Update topic for the same instance.
• Implement support for the handshake and heartbeat protocols.
• Leverage the heartbeat timeout to detect unexpected error states with your Subscription.
• Handle error states by reactivating your Subscription or creating a new one.
• Be able to receive, acknowledge, and process notifications containing FHIR resources conformant with CA Core+ profiles.
• Track and validate the eventNumber element between notifications to process events in the correct order and detect gaps.
• Use $status and $events operations as needed to detect Subscription error states and recover missed notifications.
• Store resource ID mappings between SoFA and the local PoC systems.
• Coordinate secure notification delivery with jurisdiction (e.g., auth headers, mTLS).
• Be aware that notifications are best-effort—processing reliability is your responsibility.
• Implement proper security and privacy rules with consideration for the fact that notifications will originate from different Apps launched by different users.

WebSocket-based Subscription Implementations

• Implement support for the $get-ws-binding-token operation
• Implement the bind-with-token message

User Experience

• Design the launch flow within your system to leverage to work with embedded UI containers (e.g., iframe, modal, popup) when opening SMART Apps.
• Account for browser restrictions on third-party cookies and cross-origin interactions.