SMART App Developers

This page provides a high-level, SMART App–developer-oriented overview of the HALO specification. It serves as a starting point to help you navigate the most relevant sections, understand how HALO abstracts differences between standard SMART on FHIR and SoFA environments, and quickly identify the requirements, workflows, and conformance expectations that matter most 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 SMART App Developers

By conforming to HALO, you gain:

• Accelerated Adoption – HALO extends SMART on FHIR to give your application jurisdiction-wide reach inside Canadian Point-of-Care (PoC) systems – even those without public FHIR servers – while reducing the need for customizations between deployments to different jurisdictions
• Low-friction on-boarding – Publish once to the Jurisdictional App Catalog and be discoverable by every participating EMR.
• Unified launch flows – a single launch sequence that works in both fully-compliant SMART PoC environments and in SoFA (SMART on FHIR Accelerator) environments.

Integration Patterns at a Glance: SoF vs. SoFA

From a SMART App developer’s perspective, HALO deliberately abstracts the underlying differences between SoF (standard SMART on FHIR) and SoFA (SMART on FHIR Accelerator) workflows. Whether your app is launched from a fully compliant EMR or from a lightweight PoC system leveraging jurisdictional infrastructure, your app should behave identically during and post-launch.

The HALO specification guarantees:

• The same launch parameters (iss, launch) are passed to your app regardless of the source system.
• The FHIR server you interact with (referenced by iss) always supports SMART discovery and token exchange via .well-known/smart-configuration.
• All required context (e.g., patient, encounter, user) is delivered through launch context parameters and token claims within the token response, no matter who manages the Identity Provider or FHIR server.
• Asynchronous and synchronous write handling is transparent and compliant with FHIR Async API patterns when applicable.
• Your implementation doesn't change. The only thing that varies is who’s hosting the infrastructure behind the iss and authorize URLs—a distinction abstracted away from your App by HALO. HALO’s goal is to make your app portable, scalable, and jurisdiction-ready without modification.

If your app works in a standard SMART on FHIR environment, it works in SoFA too.

Key HALO Sections for SMART App Developers

• Business Requirements – Understand the overarching requirements for SMART Apps from a business lens.
• User Stories / Use Cases – Review practical scenarios that illustrate how SMART Apps are expected to be used in clinical workflows, including data access, sharing, and response flows across systems.
• Overall Architecture – Understand how your system fits into the broader HALO ecosystem and which systems you should expect to interact with.
• App Catalog – Understand the metadata you’ll need to provide during on-boarding and registration, and how PoC systems will use this data to discover and launch your app.
• App Launch – Learn how both standard and SoFA launch flows operate, and the rationale behind HALO’s unified launch design.
• Subscriptions – Understand how your app’s resource writes trigger notifications back to PoC systems in the SoFA flow, and what responsibilities this places on you as a SMART App developer.
• Privacy and Security Guidance – Review jurisdictional and national privacy and security guidelines, best practices, and legislative considerations to ensure your SMART App 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 SMART App 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 SMART App systems are responsible for fulfilling roles such as Launch Responder and Authorization Client. These roles and their related transactions should not differ, regardless of whether the app was launched using the base SMART on FHIR or the SMART on FHIR Accelerator launch flow.

For a more detailed summary of the exact testing and conformance expectations for PoC systems, see the Interoperability Recommendations and Technical Use Case Sequence Diagrams pages.

In addition to the HALO-specific testing, SMART App 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.

Responsibilities & Recommendations Checklist

App Catalog

• Publish complete and accurate app metadata (name, description, tags, icons, privacy/terms URLs, etc.).
• Provide a valid and functional SMART launch URL.
• Declare all required SMART scopes (e.g., FHIR resource, context, identity, offline access).
• Include contact information and publisher details in metadata.
• Maintain separate catalog entries for each version of the app.
• Consider support for bilingual metadata publishing (English and French)

App Launch

• Accept the launch and iss parameters from the PoC system.
• Query the .well-known/smart-configuration endpoint to obtain authorization metadata.
• Initiate OAuth 2.0 Authorization Code flow using the discovered metadata.
• Include required scopes (e.g., openid, fhirUser, launch/patient, patient/Observation.rs) in the authorization request.
• Extract the user identity and context resource IDs from the access token response.
• Use the access token to retrieve necessary FHIR resources from the server specified in iss.

Security & Authorization

• Comply with OAuth 2.0 and OpenID Connect specifications.
• Request the offline_access scope if background write operations are required after the user interaction is complete (e.g. user closed the App).
• Ensure capability to support jurisdictional and PoC-based Identity Providers.
• Handle access to ID and refresh tokens securely in compliance with SMART and OAuth 2.0 and OIDC.
• Ensure that all requested scopes are SMART-style scopes.
• Be prepared to support both old and new style scope (e.g. patient/Observation.r, patient/Observation.read)

Context-Aware Operation

• Leverage provided context to personalize app behavior (e.g., displaying a patient demographic detail header).
• Validate that required context is present and resources accessed are in the correct format (e.g., CA Core+).
• Request necessary context-related scopes (e.g., launch/patient).
• Isolate app launch sessions and avoid reusing clinical context (e.g., patient ID, encounter ID, tokens) across launches.

Synchronous & Asynchronous Interactions (FHIR Async)

• Support both synchronous (2XX) and asynchronous (202 Accepted with polling) interactions.
• Dynamically adapt to server response model — do not assume a fixed behavior.
• Optionally use the Prefer header to indicate processing preference (e.g., Prefer: respond-async).

User Experience

• Design UI to work in embedded PoC UI containers (e.g., iframe, modal, popup).
• Account for browser restrictions on third-party cookies and cross-origin interactions.
• Gracefully handle failed launches, missing context, and authorization errors with clear user-facing messages.