User Facing Notifications

Purpose and Scope

User-facing notifications allow an authorized FHIR client to send a message to one or more users of a Point of Care (PoC) system through its FHIR API. Within HALO, this guidance focuses on SMART Applications and Backend Services as the participating FHIR clients. The message can inform a user about a clinically or operationally relevant event, such as an available electronic referral system response, new information requiring review, or a change in the state of a referral.

This page describes a common HALO workflow in which the sender creates a FHIR Communication resource and the PoC system makes the accepted message available through its native notification or messaging experience. The guidance is intended to help participating systems establish a consistent approach while allowing implementations to apply local capabilities, policies, and user-interface conventions.

This release does not define a HALO profile for user-facing notifications. The base Communication resource can represent many kinds of communication, not all of which are intended for presentation as notifications. Implementers should therefore agree that a submitted Communication is being used for this workflow. A future release of HALO, or a related pan-Canadian specification, may introduce a formal profile to distinguish user-facing notifications and define additional constraints or terminology.

Participating Systems

The workflow involves the following systems:

System	Role
Point of Care system	Hosts or controls access to the receiving FHIR API, validates the submitted Communication, resolves its context and recipients, persists accepted content, and makes the message available through a local notification or messaging capability.
SMART Application	Acts as a user-authorized sender. It creates a notification using the access and clinical context granted through a SMART launch and authorization flow.
Backend Service	Acts as a system-level sender without a user participating in the runtime authorization flow. It creates a notification under its own pre-authorized access and granted system/ scopes.

SMART Applications and Backend Services are alternative senders. A workflow does not need both, and a Backend Service does not inherit the user identity, context, access token, or scopes of a SMART Application. For additional information about their respective authorization models, see App Launch and Backend Services.

Notification Representation

The base FHIR Communication resource provides the main information needed to represent a user-facing notification. Because HALO does not profile the resource in this release, the following table is guidance rather than a formal statement of cardinality, terminology binding, or fixed values.

Element	Suggested use in this workflow
Communication.subject	Identify the patient when the notification is patient-specific. Omit it for a notification that is not associated with a patient.
Communication.sender	Identify the person, role, organization, device, service, or other supported entity responsible for sending the message.
Communication.recipient	Identify one or more intended users, roles, teams, organizations, or other destinations that the PoC system can resolve and route.
Communication.payload	Carry the human-readable notification message.
Communication.topic	Provide a concise topic that the PoC system can use as a notification title.
Communication.category	Classify the message as a notification and, where locally agreed, provide a more specific category for filtering or grouping.
Communication.priority	Convey the sender's requested relative urgency. Priority does not override local safety, routing, or presentation policies.
Communication.sent	Record when the message was sent. Supplying this timestamp supports chronology and auditability.
Communication.basedOn	Associate the notification with a request or workflow artifact, such as a referral or order, when that relationship is relevant.
Communication.inResponseTo	Associate the message with an earlier Communication when it is a response.
Communication.encounter	Associate the message with an encounter when encounter context is relevant.

Sender Representation and Attribution

The sender should be represented in a way that is meaningful to both the receiving system and its users. Where possible, Communication.sender should reference an existing resource known to the PoC system, such as a PractitionerRole, Practitioner, Organization, HealthcareService, or Device, as permitted by the base resource. The appropriate reference depends on who or what is responsible for the message:

• A person sending the message directly can be identified by a reference to that person or their role.
• A SMART Application sending on behalf of the current user can identify the represented user, while the PoC's authorization and audit records separately identify the client application.
• A Backend Service can be identified by a reference to the service, its responsible organization, or another agreed system identity.

If a persistent resource reference is unavailable, a contained resource may provide human-readable sender details where the receiving PoC supports that pattern.

Recipients should likewise be represented using references that the receiving PoC can resolve to supported destinations. An individual recipient might be represented by a Practitioner or PractitionerRole; a shared destination might use an agreed CareTeam, Group, Organization, role, service, or another supported resource type. The sender and PoC should agree on the resource types and identifier or reference forms available for routing. A raw logical ID should not be displayed to a user when a meaningful name is available.

Patient and Workflow Context

When the notification is patient-specific, the sender should populate Communication.subject and ensure that the referenced patient is known to the receiving PoC. Relevant encounter, basedOn, inResponseTo, or other supported relationships can preserve the context needed to understand the message. For example, a notification from an electronic referral system can reference the related ServiceRequest so that the PoC can associate the message with the originating referral.

References should normally resolve at the receiving FHIR endpoint. If an implementation supports identifier-based resolution, contained resources, or references to another server, the sender and PoC should agree on that behaviour in advance. A sender should not assume that an external or unresolved reference can be followed safely or displayed meaningfully.

Capability Discovery, Authorization, and Prerequisites

Before this workflow is used, the sender and PoC should establish that:

• the PoC FHIR endpoint supports the type-level create interaction for Communication;
• the application or service is registered and approved for the intended workflow;
• the sender can request and be granted an appropriate SMART scope that includes Communication create access;
• the PoC can resolve the intended recipients and relevant patient or workflow context; and
• the PoC has a local capability for incorporating an accepted message into its user-facing notification or messaging experience.

FHIR interaction support can be advertised in the PoC FHIR server's CapabilityStatement.

An application or service can declare its anticipated access in its App Catalog metadata using the scopes element described in App Catalog. Under the SMART scopes syntax, the c interaction suffix represents FHIR create access. Depending on the sender and authorization context, examples include:

• patient/Communication.c for a SMART Application creating patient-compartment communications for the in-context patient;
• user/Communication.c for a SMART Application creating communications within the current user's authorized access; and
• system/Communication.c for a Backend Service operating under pre-authorized system access.

These values declare requested access; they do not guarantee that the scope will be granted or that every notification will be accepted. The PoC should apply least privilege, the user's underlying permissions where applicable, the client's approved purpose, and local access-control, privacy, and consent policies. A patient-specific notification should be authorized for the identified patient and context. A non-patient-specific notification still requires authorization appropriate to its recipients, content, and organizational purpose.

FHIR Interactions

Create

The sender submits a notification using the standard FHIR type-level create interaction:

POST [base]/Communication

The request includes the Communication resource and an access token whose granted scope covers the interaction. The PoC evaluates authorization, validates the resource, resolves recipients and context, and either accepts or rejects the request using standard FHIR HTTP response behaviour.

A successful create response normally indicates that the server created and persisted a FHIR resource and assigned it a logical ID. It does not indicate that notification presentation has occurred or that a recipient has read or acted on the message.

Read and Search

Where supported and authorized, FHIR read can allow a sender or another authorized client to retrieve the stored Communication. FHIR search can allow discovery of communications using search parameters supported by the server. These interactions can support reconciliation, audit, or clinical record access, but they do not define a notification inbox protocol and do not expose the PoC's internal read, unread, dismissed, or actioned state.

The ability to create a notification does not imply permission to read or search communications. Clients requiring those interactions should declare and request the corresponding r or s scope permissions, and PoC systems should apply access controls appropriate to the sensitivity and recipients of the content.

Notification Lifecycle

This guidance assumes a simple fire-and-forget lifecycle:

1. The sender issues a FHIR create request for a Communication resource containing the message.
2. The PoC either accepts the resource or returns a standard FHIR error response.
3. After acceptance, the PoC makes the message available according to its local notification or messaging workflow.

While not explicitly in scope for this guidance, more complex workflows may support correction, withdrawal, replacement, escalation, guaranteed delivery, acknowledgement, or other forms of notification lifecycle management. Implementers requiring these behaviours should define them through additional agreements or specifications rather than assuming they are provided by this workflow.

Distinction from Work Assignment

This workflow conveys information to one or more recipients; it does not assign work or establish responsibility for completing an activity. In particular, a Communication.recipient identifies an intended destination for the message and should not be interpreted as the owner of a work item. The notification flow does not define acceptance, reassignment, progress, completion, or other work-management states.

Workflows that assign an activity to an owner or track it through a managed lifecycle are separate from the notification flow described here. For example, such a workflow might use the FHIR Task resource. Defining work-assignment workflows is outside the scope of this page.

Workflow Sequence

Authorization is shown at a high level because the detailed flow differs between a user-facing SMART Application and a Backend Service.

Note: The sequence does not require the PoC to use a separate internal notification service. The FHIR API and notification capability may be components of the same product. Presentation can also occur asynchronously after the create response, according to local processing and routing behaviour.

Interface and Implementation Guidance

Presentation and Context

PoC systems should present accepted notifications through an experience familiar to their users, such as an inbox, notification centre, chart message feed, or another locally supported mechanism. Presentation should use meaningful sender and recipient names, topic, payload, category, priority, and sent time where these values are available. Codes and technical identifiers should be translated into human-readable displays rather than shown directly.

For patient-specific messages, preserving the relationship to the patient can help users evaluate the message in the correct chart. Preserving encounter and related-artifact references can similarly support navigation to a consult, referral, order, or other relevant context. Where reasonable, a PoC can make the same message discoverable from both its general notification experience and the related patient or artifact view.

Persistence, Errors, and Auditability

The PoC should persist an accepted Communication according to applicable clinical record and retention policies. If the PoC cannot safely accept or route a message—for example because authorization is insufficient, required content is invalid, a recipient cannot be resolved, or referenced context is inaccessible—it should reject the create interaction using a standard FHIR error response, preferably with an OperationOutcome that helps the sender understand the issue.

The sender should treat a failed create interaction as a failed submission and should not assume that a recipient was notified. A successful response should be retained with the created resource identity where the sender needs operational reconciliation, while still recognizing that it is not proof of presentation or user action.

Audit records should make it possible to determine which authenticated application or service submitted the message, any represented user, the sender and recipients expressed in the resource, relevant patient and workflow context, and when the interaction occurred. This information can support investigation and accountability without exposing internal notification state through the FHIR resource.

Privacy and Security

Notifications may contain personal health information and may appear in user-facing areas where previews are visible. Implementers should:

• request and grant only the access needed for the workflow;
• validate authorization for the patient, recipients, and clinical or operational purpose;
• avoid unnecessary sensitive information in topics, preview text, or payloads;
• preserve reliable attribution to the originating application, service, and represented user where applicable;
• protect notification content in transit and at rest; and
• apply applicable consent, disclosure, retention, and audit requirements.

For broader guidance, see Privacy and Security Guidance and Design Considerations.

Example Application

An electronic referral system needs to inform a referring provider that a specialist response is available. Acting either as an authorized SMART Application or as a separately authorized Backend Service, it creates a Communication containing:

• status set to completed;
• the patient in subject;
• the referring provider or their role in recipient;
• the responsible person, service, or organization in sender;
• a concise title in topic;
• a message such as "A specialist response is available for review" in payload;
• the referral ServiceRequest in basedOn; and
• the sending time in sent.

The PoC validates and persists the resource, then makes the message available to the referring provider through its standard notification experience. It can also make the same message accessible from the patient chart or related referral view. The create response confirms acceptance of the resource but does not indicate that the provider viewed or acted on the response.