Ontario eReferral HL7® FHIR® Implementation Guide

Technical Specifications > Direct Messaging

Specification - Direct Messaging

This section of the implementation guide defines specific requirements for systems wishing to conform to the Direct Messaging requirements in this implementation guide (IG). The focus is on the expected use of FHIR messaging to support the event based information exchange between software applications used by Practioners and/or Service Providers who request or provide services on behalf of a patient.

The requirements and expectations described here are not intended to be exhaustive. This IG establishes a baseline of expected behavior that communication partners can rely on and then build upon without standardizing referral pathways or defining what clinical data must be exchanged when referring patients. Therefore, implementers SHALL anticipate the need to discuss and mutually agree on the approach that will be used to support the different referral pathways, forms used, required supporting information (etc.) that will be enabled through the implementation of Direct Messaging.

Future iterations of this IG are expected to build upon this baseline.

Context

Prerequisites

Before reading this formal specification, implementers are encouraged to first familiarize themselves with other key portions of this IG, specifically:

The Business Context for information about what this IG aims to accomplish including an overview of the business solution and process flow this specification will enable.
The Technical Background page for information about the underlying specifications this IG builds upon including references to sections that implementers should read to establish a necessary foundation to understand the constraints and usage guidance described here.

Conventions

This implementation guide uses specific terminology to flag statements that have relevance when evaluating a solution's conformance with the guide:

SHALL indicates requirements that must be met to be conformant with the specification.
SHOULD indicates behaviors that are strongly recommended (and which could result in interoperability issues or sub-optimal behavior if not adhered to), but which do not, for this version of the specification, affect the determination of specification conformance.
MAY describes optional behaviors that implementers are free to consider but where there is no recommendation for or against adoption.

Participating Systems

Direct messaging occurs between two systems with users performing different roles in the referral process, where:

An RMS Sourceis used by a healthcare service provider to initiate, monitor and/or communicate about a request. An RMS Source will typically enable providers to:
- search for available services or service providers (potentially through integration with a Healthcare Service Directory (HSD));
- access and complete electronic forms required by the service provider;
- attach supporting information (typically through integration with POS);
- submit a request;
- monitor status;
- receive information about appointments and tasks planned and performed in response to the request;
- communicate with other service providers using messaging.
An RMS Target is used by a healthcare service provider to receive, respond to, manage and/or communicate about a request. RMS Target functionality will vary between systems used by service providers to respond to different request types but may include some or all the following:
- receive, review, acknowledge, accept and reject requests with supporting information;
- communicate with the requester using messaging;
- plan tasks to be performed in response to the request;
- appointment scheduling, and
- monitoring the status of planned tasks.

Note:

A single system MAY act as the RMS Source and the RMS Target for a request or one or the other depending on the capabilities of the system, the role of the user for a specific request and the RMS systems used by requester and performer.
In practice, either or both of the systems exchanging referral information may be a specialized Referral Management Systems (RMS), a message broker, or any of a range of systems used at the Point of Service (POS) by people who request, triage, plan or perform services as part of an electronic referral or consultation process. The requirement is only that conformant systems SHALL provide the Capabilities expected of the role they declare.
Definition of the capabilities of a Healthcare Service Directory (HSD), including related FHIR resource, is beyond the scope of this IG

FHIR Artifacts

This specification makes significant use of FHIR Artifacts to describe the structure and content of the messages to be exchanged as well as the behaviour of the participating systems.

Artifact Type	Use
CapabilityStatements	Specify the minimum conformance requirements (i.e. Message Definitions and Operations) for the RMSSource and the RMSTarget participating in a Direct Messaging integration.
MessageDefinitions	Specify the message payloads (i.e. the appropriate FHIR Resources) to use to transmit information for a given Event as well as the expected responses.
StructureDefinitions (Profiles and Extensions)	Specify use case specific constraints and extensions on the FHIR Resources used within messages.
ValueSets	Specify the appropriate values to use within a given coded element within a FHIR Resource (Profile or Extension).

Direct Messaging

Direct Messaging integrations use FHIR messaging to exchange of information about a referral request (and actions performed in response to a request) between the healthcare practioner or service provider who requests a service and the individual(s) who perform tasks in response to the request.

Flow of information

Information is exchanged in response to business events that "trigger" messages that exchange information between two systems. The sequence diagram below illustrates the business events in scope for this IG as well as information exchanged between the RMS Source and RMS Target in response to each trigger.

DirectMessageFlow-Bus

Use of FHIR Messaging

FHIR messaging defines a standard way to associate a MessageEventCode corresponding to a business event with a "message payload" that is used to exchange information between two systems. The following table illustrates the relationships between the business events in the sequence diagram above and the event codes defined in this IG. Each message has focus FHIR Resource corresponding to the business event that determines the structure of the payload.

#	Trigger Event	Event Code (link to Payload)	Focus (link FHIR Profile)	Source	Destination
1a.	Requester creates and sends a ServiceRequest	add-servicerequest	ServiceRequest	RMSSource	RMSTarget
1b.	Performer responds with a Task (process-request) to track Status	notify-add-process-request	Task (process-request)¹	RMSTarget	RMSSource
2.	Performer sends update(s) to the Task and/or its Status as work is performed	notify-update-process-request ²	Task (process-request)¹ (and potentially others)	RMSTarget	RMSSource
3.	Requester sends an update to the ServiceRequest or the ServiceRequest's Status if information is changed or added	notify-update-servicerequest	ServiceRequest	RMSSource	RMSTarget
4.	Performer notifies the requester that information has been corrected on Target	notify-data-correction³	ServiceRequest (and potentially others)	RMSTarget	RMSSource
5.	Performer notifies the requester of an Appointment created in response to the ServiceRequest	notify-add-appointment	Appointment	RMSTarget	RMSSource
6.	Performer sends an update to an Appointment if information or status changes	notify-update-process-request	Task (process-request) and Appointment	RMSTarget	RMSSource
7.	Requester sends an ad-hoc Communication	add-communication^4,5	Communication	RMS Source	RMS Target
8.	Performer sends an ad-hoc Communication	add-communication^4,5	Communication	RMS Target	RMS source
9a.	Performer requests additional information needed to perform the request (rfi)	add-rfi⁵	Task (rfi) ¹	RMS Target	RMS Source
9b.	(Option 1) Requester responds with a Communication including the requested information	add-communication	Communication and Task (rfi)⁶	RMS Source	RMS Target
9b.	(Option 2) Requester responds with an update to the ServiceRequest	notify-update-servicerequest	ServiceRequest and Task (rfi)⁶	RMSSource	RMSTarget
10.	Performer completes a ServiceRequest	notify-update-process-request ²	Task (process-request)	RMSTarget	RMSSource
11.	Requester terminates a ServiceRequest	terminate-servicerequest	ServiceRequest	RMSSource	RMSTarget
12.	Performer terminates a ServiceRequest	notify-update-process-request ²	Task (process-request)	RMSTarget	RMSSource

¹ Two primary Task 'types' with specific meanings are defined in this IG to support different referral workflows and others may be added by implementers. The Task type is differentiated by Task.code which SHALL therefore always be populated with a TaskCode.

² Where discreet events are not defined in this IG, implementers MAY use the notify-update-process-request event to share information about actions the Performer has planned or taken in response to the ServiceRequest. In these cases, a message MAY have more than one MessageHeader.focus to convey information about both the 'process-request' Task's status and any new resource(s) created. When sending the notify-update-process-request event, all resources in MessageHeader.focus SHALL have the .basedOn element populated with a reference to the original ServiceRequest.

³ The notify-data-correction event MAY be implemented by the Target notify the requester of information the performer corrected in a ServiceRequest, Patient record or other resource (e.g. a correction to health card number or version code). When doing so, the resource being corrected SHALL be referenced in MessageHeader.focus with the ServiceRequest.

⁴ The source of a Communication MAY be the requester, the performer or potentially other parties such as a primary care provider or, in the future, the patient or a family member. To enable appropriate rendering of communications on systems, Communication.sender SHALL be populated with an appropriate PractitionerRole.

⁵ Where both the add-communication and add-rfi events are supported in an implementation either can potentially be used by a peformer to request information from a requester that results in an update to a ServiceRequest. Implementers SHOULD use add-rfi where traceability is required as it provides the means for the requester to associate the update to the ServiceRequest with the RFI.

⁶ A response to an add-rfi message SHALL include a reference to the Task (rfi) in MessageHeader.focus for traceability.

Constructing Messages

Transmission of information between two systems using FHIR messaging involves the exchange of a message payload that consists of several parts:

A Message Bundle: A Bundle Resource ("type" : "message") is used to package together a collection of FHIR Resource instances that will be sent from one system to another. The Bundle SHALL have an entry for each of the FHIR Resources required to convey information about the business event, starting with the MessageHeader which SHALL always be first.
A Message Header: A MessageHeader Resource with eventCoding identifying the trigger event and other message related metadata including an id, source.endpoint, destination.endpoint is used to convey the purpose of the message and to support message routing.
The Focus of the Message: MessageHeader.focus SHALL point to the ServiceRequest, Task, Appointment or Communication Resource that is being acted upon.
Other referenced entities and supporting information: The MessageHeader and Focus SHALL reference other resources to convey information about the Patient who is the subject of the referral request (ServiceRequest.subject), the PractitionerRole of the requester (ServiceRequest.requester, MessageHeader.author), supporting information (ServiceRequest.supportingInfo), etc.
Identifiers & Timestamps: Bundles and MessageHeaders SHALL have appropriate Identifiers & Timestamps as defined in the FHIR messaging requirements. Each Bundle.entry element SHALL have a unique fullUrl and resource so systems that receive messages can resolve references within the bundle.

The Event (MessageHeader.event) and Focus of the Message (MessageHeader.focus) determines the content and structure of the Bundle of information (FHIR Resources) exchanged between the RMS Source and the RMS Target.

Example: ServiceRequest Message Bundle

As illustrated below, a message event that focuses on a ServiceRequest will include a Bundle of resoruces that, minimally, SHALL include:

a MessageHeader
the ServiceRequest referenced in MessageHeader.focus
the Patient who is the subject of the ServiceRequest (ServiceRequest.subject)
PractitionerRole(s) referenced in MessageHeader.author, ServiceRequest.requester, the requested ServiceRequest.performer where, each SHALL reference an Organization, Location and/or Practitioner
references to other ServiceRequest.supportingInfo where needed (see below)

Illustration: ServiceRequest Message Bundle

ServiceRequestMessageBundle

Secifications:

Message Bundles corresponding to different Focus resource are specified on the following pages:

Notes:

To enable conformance testing against the requirements of this IG, the requirements summarized above are formally specified as contraints within FHIR Profiles published in this IG. Implementers are strongly encouraged to become familiar with these formal specifications and to rely on them as the source of truth.
Messages with multiple resources in MessageHeader.focus will have additional requirements that are not represented in the requirements above.

State Machines

The information flows defined above are used to transmit information about ServiceRequests, Appointments and related Communications between systems as well as to convey information about the status of a ServiceRequest. Within FHIR Messages, staus is conveyed using a combination of the event code in MessageHeader.event and the .status element(s) of the Task (process-request) or ServiceRequest in MessageHeader.focus.

The person who initiated the Referral request (i.e. the Requester) is owner of the ServiceRequest and the system where a request was created, the RMS Source, SHALL be considered the source of truth for the content of the request.

Once a ServiceRequest has been created and sent to the RMS Target, the RMS Target that receives the request (and its users) SHALL be responsible for processing the request. Therefore, the RMS Target SHALL be considered the source of truth for all information about actions performed in response to the Request and the status of the request. The RMS Target SHOULD use the 'process-request' Task resource (and associated messages) to convey status information back to the RMS Source and Requester.

CombinedStateMachine

Requester State Machine

A ServiceRequest will pass through several states over its lifecycle. State changes within an RMS Source MAY be the result of actions taken directly by users of the RMS Source or a response to messages received from an RMS Target.

The following table outlines the expected use of FHIR messaging and message elements to convey state changes within the RMS Source to the RMS Target:

Business Event	Message EventCode	ServiceRequest.status	Expectation of RMS Target
A ServiceRequest is created by the RMS Source and sent to the RMS Target	add-servicerequest	active	The RMS Target SHOULD respond with notify-add-process-request once (a) the message has been accepted and (b) the 'process-request' Task has been created; The RMS Target SHOULD also send nofications to the RMS Source to communicate updates to status as the request is processed.
A ServiceRequest that has been sent to RMS Target is terminated in the RMS Source	terminate-servicerequest	Revoked Entered-in-error	The RMS Target SHALL delete the Task and any associated PHI upon receipt of the message.
A ServiceRequest's status is changed within the RMS Source	notify-update-servicerequest	active on-hold completed Unknown	The RMS Target SHOULD update any stored ServiceRequest information corresponding to the change.

Performer State Machine

The 'process-request' Task is used to track the state of a ServiceRequest on the RMS Target. State changes MAY result from actions taken within the RMS Target or based on messages the system receives from an RMS Source.

The following table illustrates the relationship between changes in the status of the 'process-request' Task and the messages exchanged between the RMS Source and RMS Target. It is expected that systems participating in integrations will have internal states that vary from below, therefor implementers SHALL anticipate the need to discuss workflow and state transitions with integration partners at the time of implementation and to map their internal states to the status codes used to exchange information between the RMS Source and RMS Target.

Business Event	Message EventCode	Task.status	Expectation of RMS Source
A ServiceRequest is received and 'process-request' Task is created on the RMS Target	notify-add-process-request	Requested Received Accepted Ready In-progress	The RMS Source MAY update the status of the ServiceRequest based on the information received
The status of a 'process request' Task is changed	notify-update-process-request	Requested Received Accepted Ready In-progress on-hold completed Rejected cancelled failed	The RMS Source MAY update the status of the ServiceRequest based on the information received

Referral Forms and Supporting Information

This IG defines baseline messaging requirements for eReferral but not the forms or clinical data that must be sent with a ServiceRequest. Therefore, implementers SHALL anticipate the need to discuss and mutually agree on the approach that will be used to support different requests and referral pathways. This includes any forms that may be used to inititate the referral and the format of any required supporting information that must be attached.

This IG and the FHIR profiles within it provide a few different options for attaching supporting information to a ServiceRequest, including:

Converting the information collected within a form into human-readable text and including it in the ServiceRequest.note.text element;
Using one of several different FHIR resources that can be referenced in ServiceRequest.supportingInfo and then included in the message payload as a Bundle.entry:
- Command 'link' could not render: Object reference not set to an instance of an object.
  to provide structured form data as a list of questions and responses,
- Command 'link' could not render: Object reference not set to an instance of an object.
  to provide structured information about a patient's allergies,
- Command 'link' could not render: Object reference not set to an instance of an object.
  to provide structured information about a patient's health condition / diagnosis,
- Consent to provide consent information collected at source, or
- Command 'link' could not render: Object reference not set to an instance of an object.
  to provide a binary attachment that's available to retrieve from a server using a url (recommended) or as base64 encoded data included in the resource.

Where there is a requirement to exchange structured clinical information supported by other FHIR resourcces implementers MAY engage and collaborate with the eReferral WG to profile specific FHIR resources with the expectation of contributing them to a future version of this IG.

Referral Outcome Information

Different referral requests and pathways will have different outcomes. As with other business flows, implementers SHALL anticipate the need to discuss expected outcomes of different ServiceRequests and any information to be shared when a ServiceRequest reaches a terminal state (i.e.: completed, cancelled, failed or rejected).

Below are proposed approaches for trial use.

Completing a Request

In the typical case where a ServiceRequest is accepted by and RMS Target and then completed by its users, an update to the "process-request" Task SHOULD be used to share information with the requester about the ServiceRequest outcome, where:

the MessageHeader.event SHALL be "notify-update-process-request"
the MessageHeader.focus SHALL be a reference to Task resources, where:
- Task.code is "process-request"
- Task.status is "completed"
Experimental: Task.output MAY reference one or more resources createdbasedOn the current ServiceRequest (e.g.: a Communication containing a plan of care)

Branching and/or Chaining Requests

In cases where a completion of a ServiceRequest results in the creation of others, multiple messages MAY be triggered by an RMS that is performing the role of both RMS Source and RMS Target.

Below illustrates how direct messaging may be used when a care coordinator creates a service plan and orders services from another provider when completing a ServiceRequest.

Business Event	Message EventCode	Target System	Details
Coordinator sends request to service provider	add-servicerequest	RMS Target	`ServiceRequest.basedOn` SHALL reference the original ServiceRequest
Coordinator notifies requester of request completion	notify-update-process-request	RMS Source	`Task.code` is "process-request" `Task.status` is "completed" Experimental: - `Task.output(1)` references the service plan (Communication) - `Task.output(2)` references the order (ServiceRequest)
System notifies others of new ServiceRequest	notify-add-servicerequest	optional/multiple	`ServiceRequest.basedOn` SHALL reference the origninal ServiceRequest `ServiceRequest.supportingInfo` references the service plan (Communication)

Note that additional business rules apply to situations where multiple connected ServiceRequests are made simultaneously.

Exchanging Messages

Implementations conformant with this Direct Messaging specification SHALL exchange FHIR Message Bundles as defined in this IG to transfer information between the RMS Source and RMS Target.

It is assumed that most implementers will use HTTP based transfer between to transfer the FHIR Message Bundles between endpoints that support the FHIR $process-message operation (although implementers **MAY mutually agree on other FHIR conformant approaches and remain conformant with this IG). Implementers are encouraged to read the $process-message operation definition prior to implementing the messaging.

Example:

The following provides an example of an information exchange between an RMS Source and RMS Target corresponding to the first Trigger in the sequence diagram on this page. Messages are truncated for readability with links to the full Message Bundle.

RMS Source Sends Request to the RMS Target:

link to message bundle

POST [base]$process-message
[other headers]

{
    "resourceType": "Bundle",
    "id": "E959B538-5281-4E70-A6CC-34337EAAB720",
    ...
    "type": "message",
    "timestamp": "2020-10-09T15:21:51.2112Z",
    "entry": [
        {
            "fullUrl": "urn:uuid:4783C82C-683E-491D-B834-3D1B8931BDD9",
            "resource": {
                "resourceType": "MessageHeader",
                "id": "4783C82C-683E-491D-B834-3D1B8931BDD9",
                ...
                "eventCoding": {
                    "system": "https://ehealthontario.ca/fhir/CodeSystem/message-event-code",
                    "code": "add-servicerequest"
                    },
                "destination": [{

                ...

RMS Target Receives and Accepts the Message

200 OK
[other headers]

RMS Target sends 'process-request' Task

link to message bundle

POST [base]$process-message
[other headers]

{
    "resourceType": "Bundle",
    "id": "0022F68B-F981-4D7F-8446-4BD754B824EA",
    ...
    "type": "message",
    "timestamp": "2020-10-09T15:21:51.2112Z",
    "entry": [
        {
            "fullUrl": "urn:uuid:6CF3735F-C8C5-4C1D-B3A1-01E861611CF8",
            "resource": {
                "resourceType": "MessageHeader",
                "id": "6CF3735F-C8C5-4C1D-B3A1-01E861611CF8",
                ...
                "eventCoding": {
                    "system": "https://ehealthontario.ca/fhir/CodeSystem/message-event-code",
                    "code": "notify-add-process-request"
                    },
                "destination": [{

...

Example instances of the message Bundle corresponding to each of the different event codes above are available from the Behaviour: Message Definition section of the FHIR Artifacts page. (See right column.)