App Catalog

Introduction

The HALO App Catalog serves as a centralized repository for healthcare applications that extend the capabilities of clinical systems such as Electronic Medical Records (EMRs). A primary goal of the App Catalog is to provide healthcare providers across Canada with access to jurisdictionally approved third-party applications, streamlining the discovery, configuration, and deployment of applications to improve patient care and clinical workflows.

The pan-Canadian framework of HALO ensures that jurisdictions can adapt the App Catalog, while remaining aligned with broader national standards for interoperability and connectivity. Jurisdictions may tailor the App Catalog to meet local regulatory requirements and healthcare needs.

From the perspective of Point of Care (PoC) systems, the App Catalog provides a standardized method to retrieve and display applications, enabling integration into clinical workflows. The specification defines how PoC systems can interpret the detailed metadata for each application (e.g., name, description, developer information, etc.), to facilitate the HALO App Launch flow.

The app lifecycle (i.e., how an app is registered, updated, and removed from the catalog) is beyond the scope of this specification.

Rationale for a Custom Structure

Currently FHIR® does not provide suitable resources to represent the App Catalog without significant profiling of several resources. FHIR® resources are mainly designed to handle clinical and administrative data related to patients, healthcare providers, and medical treatments, whereas the focus of the data expressed by the App Catalog relates to metadata & application management.

The App Catalog includes information about each application's capabilities, including supported interactions. Although FHIR® provides the CapabilityStatement resource, it is intended to document a set of capabilities (behaviours) of a FHIR® Server or Client for a particular version of FHIR® that may be used as a statement of actual server functionality or a statement of required or desired server implementation, not for managing applications or providing metadata about their use within a broader technical infrastructure.

Endpoint

An implementing system SHALL provide access to the HALO App Catalog through the following API endpoint:

GET [base]

This endpoint allows a consuming system to retrieve a list of available applications from the catalog.

Note: This endpoint will be refined in a future release of this specification. For now, it remains generic to allow flexibility in accommodating upcoming design decisions.

Structure

This section describes the JSON structure of the App Catalog including datatypes, constraints, element descriptions, and examples.

Data Types

The datatypes used in the App Catalog are listed below.

Applications

Each application within the catalog provides key metadata, including a unique identifier (UUID), a descriptive name, and detailed information such as the app’s functionality, privacy policies, and terms of service. This element also includes technical capabilities, such as supported FHIR interactions and launch URLs for integration into clinical workflows. The metadata ensures that healthcare providers can easily discover, assess, and integrate applications that meet their specific needs.

Note that versioning of applications in the App Catalog is managed through separate deployments of each app. When a new version of an application is introduced, it is treated as a distinct deployment in the catalog. This ensures that the metadata for each version remains independent, allowing healthcare providers to maintain or adopt specific versions according to their needs.

The contacts element

The contacts element provides details on how users can reach the publisher or support team for inquiries, troubleshooting, or assistance related to the application. Each contact entry may include an email address, phone number, or URL, offering multiple communication channels.

Each application SHALL include at least one contact entry with an email address and at least one contact entry with a URL. This MAY be accomplished using a single contact entry that includes both the email and the URL, or with multiple contact entries.

The publisher element

The publisher element provides information about the organization or entity responsible for the application. This includes the publisher's unique identifier, human-readable name, and optionally, a URL directing users to the publisher's website.

The scopes element

The scopes element provides a mechanism for the publishers of SMART Apps within the App Catalog to communicate which SMART on FHIR scopes their applications will require. This list SHALL only contain scopes that follow the rules defined within the Scopes and Launch Context of the SMART App Launch 2.1 specification.

While these scopes will ultimately need to be registered with the authorization server ahead of time, these are also intended to be leveraged by the Point of Care application during the SMART on FHIR Accelerator (SoFA) Launch process as a mechanism for determining which resources it needs to prepopulate within the SoFA FHIR server. For more detailed guidance on how Point of Care solutions should implement this decision logic, please see the Operation: $set-context page.

When parsing the list of scopes from the catalog entry for a given application, vendors SHOULD use this information to assess the application's compatibility with their current implementation. For instance, the application might request resources that the PoC system is unable to map to FHIR at this time.

FHIR Resource Scopes

Scopes in this format are comprised of 3 segments. The interaction level prefix, the resource type, and the REST API Interaction suffix.

For example:

• patient/Observation.crus: Permission to create, read, update, and search Observations belonging to the current patient in context.
• user/Patient.rs: Permission to read and search all Patients that the current user has access to.
• system/Practitioner.rs: Permission to read and search all Practitioners in the system.

Note: SMART on FHIR provides guidelines for specifying the exact subset of resources to which an app requires access. This is achieved through finer-grained resource constraints, which leverage FHIR search parameters to preemptively filter the requested resource types. However, due to the complexity of these search parameters, vendors are not currently expected to process them and MAY instead implement mechanisms to ignore them when present. Future releases of HALO may include additional guidance for PoC vendors on how to handle these scopes as a mechanism for limiting the amount of data that is prepopulated within the SoFA FHIR server.

For more information, see Scopes for requesting FHIR Resources within the SMART App Launch specification.

Context Scopes

Context scopes are scopes that allow the SMART on FHIR app to request that the authorization server provide it with various aspects of the current clinical context within the PoC. These scopes follow a simpler syntax of a fixed "launch" prefix followed by an optional resource type.

By default, in an EHR launch, the launch scope is used when the SMART app receives the ?launch=... parameter in the launch URL. This scope instructs the authorization server to include relevant context in the access token response. Optionally, apps may request specific launch scopes suffixed with a resource type, providing a hint to the server about which specific context to include.

When these more specific scopes are defined for an app in the catalog, PoC vendors initiating a SoFA launch SHALL use these scopes to determine the minimum context that must be set during the $set-context operation (see Operation: $set-context).

If only the launch scope is provided, PoC vendors initiating a SoFA launch SHALL, at a minimum, include the current patient, practitioner, organization, and location in the $set-context operation, provided that they are present within the user's current context.

For example:

• launch: Permission to obtain the launch context from the launching PoC application.
• launch/Patient: The app needs to know the ID of the patient in context at launch time.
• launch/Encounter: The app needs to know the ID of the encounter in context at launch time.
• launch/Organization: The app needs to know the ID of the organization the user is acting within at launch time

Note: The process by which apps request information about the current user is outlined in the Identity Scopes section below.

For more information, see Scopes for requesting context data within the SMART App Launch specification.

Identity Scopes

In SMART on FHIR, SMART apps can request information about the user currently launching the application by including a combination of the openid and fhirUser scopes. In traditional OAuth 2.0 and OpenID Connect (OIDC), the openid scope signals to the authorization server that the client expects an ID Token to be included in the access token response. In the SMART on FHIR context, adding the fhirUser scope indicates that the app is requesting the server to include a fhirUser claim in the ID Token. This claim contains a reference to the FHIR resource representing the current user.

For more information, see Scopes for requesting identity data within the SMART App Launch specification.

The Offline Access Scope

The offline_access scope in SMART on FHIR is used by client applications to request a long-lived refresh_token. When included in the authorization request and subsequently granted by the authorization server, this scope enables the application to obtain new access tokens even after the user has logged out or their session has expired. Essentially, this means the application is permitted to maintain continuous interaction with the FHIR server without requiring repeated explicit user re-authorization.

See the Scopes for requesting a refresh token and Refresh access token sections of the SMART App Launch specification for more details on the offline_access scope.

Within the HALO framework, which supports both standard SMART on FHIR and the SoFA (SMART on FHIR Accelerator) flow, handling of the offline_access scope depends on the chosen integration pathway:

• Standard SMART on FHIR Flow: The Point of Care (PoC) system's Identity Provider (IdP) is responsible for managing refresh tokens and handling long-term access to resources on behalf of the application.

• SoFA Flow: Jurisdictional-level infrastructure handles the issuance and management of refresh tokens. Specifically, the inclusion of the offline_access scope indicates that the SMART application may continue to write data back to the jurisdictionally hosted SoFA FHIR server even after the user has closed the app or logged out of the PoC. Consequently, the PoC system has an ongoing responsibility to maintain the mappings originally established through the $set-context operation (See the Operation: $set-context page). These persistent mappings ensure that data written back to the SoFA can be accurately reconciled and associated with the correct clinical context in the PoC, facilitating seamless updates or notifications related to patient data and clinical workflows.

Complete App Catalog JSON Example

Below is an example response from the app catalog endpoint. For simplicity, only a single result is shown here. In practice, this response will contain a list of available apps within the jurisdiction and is likely to include multiple results.

[
    {
        "id": "fcf9956c-f952-40e0-8e24-a65d56118db2",
        "name": "Heart Health Monitor",
        "description": "A comprehensive application for monitoring and managing heart health.",
        "descriptionShort": "Monitor heart health",
        "tags": [
            "cardiology",
            "monitoring",
            "health"
        ],
        "helpUrl": "https://heart.example.com/help-manual",
        "iconUrl": "https://heart.example.com/icons/heart-health.png",
        "screenshots": [
            "https://heart.example.com/screen1.png",
            "https://heart.example.com/screen2.png",
            "https://heart.example.com/screen3.png"
        ],
        "privacyPolicyUrl": "https://heart.example.com/privacy/heart-health",
        "termsOfServiceUrl": "https://heart.example.com/terms/heart-health",
        "launchUrl": "https://heart.example.com/launch/heart-health",
        "eligibilityCriteria": "The audience for this app is General Practitioners and Nurses.",
        "contacts": [
            {
                "email": "support@example.com",
                "title": "Customer Support"
            },
            {
                "url": "https://heart.example.com",
                "title": "Online Chat"
            },
            {
                "phone": "+01 111 222 3333",
                "title": "24 Hour Emergency Line"
            }
        ],
        "publisher": {
            "id": "6b4929be-a7c0-4a38-4a8e-53338dbcb7f5",
            "name": "Example Company Inc.",
            "url": "https://heart.example.com"
        },
        "isEnrolling": true,
        "scopes": [
            "openid",
            "fhirUser",
            "launch",
            "launch/Patient",
            "launch/Organization",
            "launch/Location",
            "user/Practitioner.r",
            "user/Organization.r",
            "user/Location.r",
            "patient/Patient.r",
            "patient/Observation.rs",
            "patient/Condition.rs",
            "offline_access"
        ]
    }
]

Usage note: every effort has been made to ensure that the examples are correct and useful, but they are not a normative part of the specification.