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 or requesting consults from specialists. 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.

Participating Systems

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

  • An RMS Source is 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.
  • An RMS Source and RMS Target MAY support both eReferral and eConsult functionality, or only support one of eReferral and eConsult

Direct Messaging between RMS Systems

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

Information is exchanged in response to business events that "trigger" messages that exchange information between two systems. 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.

As illustrated below, the flow of information and use of messaging may vary according to business requirements.

eReferral and eConsult

Flow of Information

The sequence diagram below illustrates the business events that may be supported in eReferral integrations as well as information exchanged between the RMS Source and RMS Target in response to each trigger.

Use of FHIR Messaging

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-service-request ServiceRequest RMSSource RMSTarget
1b. Performer responds with a Task (process-request) to track Status notify-add-process-request Task (process-request)1 RMSTarget RMSSource
2. Performer sends update(s) to the Task and/or its Status as work is performed notify-update-process-request 1 Task (process-request) RMSTarget RMSSource
3. Requester sends an update to the ServiceRequest or the ServiceRequest's Status if information is changed or added notify-update-service-request ServiceRequest RMSSource RMSTarget
4. Performer notifies the requester that information has been corrected on Target notify-data-correction2 ServiceRequest 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) RMSTarget RMSSource
7. Requester sends an ad-hoc Communication send-communication-from-requester 3 Communication RMS Source RMS Target
8. Performer sends an ad-hoc Communication send-communication-from-provider 3 Communication RMS Target RMS source
9a. Performer requests additional information needed to perform the request send-communication-from-provider 3 Communication RMS Target RMS Source
9b. (Option 1) Requester responds with a Communication including the requested information send-communication-from-requester 3 Communication RMS Source RMS Target
9b. (Option 2) Requester responds with an update to the ServiceRequest notify-update-service-request ServiceRequest RMSSource RMSTarget
10. Performer completes a ServiceRequest notify-update-process-request Task (process-request) RMSTarget RMSSource
11. Requester requests clarification from the Performer send-communication-from-sender Communication RMS Source RMS Target
12. Requester updates the status of a ServiceRequest to complete notify-update-service-request ServiceRequest RMSSource RMSTarget
13. Requester terminates a ServiceRequest revoke-service-request ServiceRequest RMSSource RMSTarget
14. Performer terminates a ServiceRequest notify-update-process-request Task (process-request) RMSTarget RMSSource

1 Where discrete 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 SHALL use MessageHeader.focus to identify the resource created or updated within the event. When sending the notify-update-process-request event, the resource in MessageHeader.focus SHALL always have the .basedOn element populated with a reference to the original ServiceRequest.

2 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.

3 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.

Contributions to Repositories for Analytics and Performance Monitoring

An RMS Source MAY be requested to contribute information about referral requests to another third-party system such as a regional repository/registry, a point of service system or a patient portal.

In these cases, 'notification' type events SHALL be used to transmit information about the event UNLESS the intent is for the system or its users to take action in response to the request:

Message Event Code Trigger Event
notify-add-service-request Requester creates and sends a ServiceRequest
notify-update-service-request Requester sends an update to the ServiceRequest or the ServiceRequest's Status if information is changed or added
Requester updates the status of a ServiceRequest to complete
revoke-service-request Requester terminates a ServiceRequest
notify-add-appointment Performer notifies the requester of an Appointment created in response to the ServiceRequest
notify-update-process-request Performer sends update(s) to the Task and/or its Status as work is performed

In addition to the 'notification' type events, the ContentType extension on the MessageHeader resource is used to distinguish between analytical and clinical message bundles.

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:

Illustration: ServiceRequest Message Bundle

Specifications:

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.

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-service-request 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 revoke-service-request 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-service-request 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, therefore 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

Furthermore to the above, the Task.businessStatus is a reflection of the internal business state of a task within an RMS Target. The Task.businessStatus MAY vary between RMS Target systems depending on internal workflow. An example of the relationship between the Task.businessStatus, Task.status, and ServiceRequest.status is depicted in the eConsult example below.

Workflow Event Business Event Message EventCode Task.business Status Task.Status Expectation of RMS Source
Consult provided by specialist. The status of a 'process request' Task is changed notify-update-process-request Completed1 Completed1 The RMS Source MAY update the status of the ServiceRequest based on the information received

1 The status selected to depict the workflow event are not meant to be prescriptive. The code selection for Task.status and Task.businessStatus are up to the discretion of the participating systems.

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:

    • QuestionnaireResponse to provide structured form data as a list of questions and responses
    • AllergyIntolerance to provide structured information about a patient's allergies,
    • Condition to provide structured information about a patient's health condition / diagnosis,
    • Consent to provide consent information collected at source, or
    • DocumentReference 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 approaches in use:

Request completed by Performer

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"
  • Task.output MAY reference one or more resources createdbasedOn the current ServiceRequest (e.g.: a Communication containing a plan of care)

Request completed by Requester

Some workflows, including the Ontario eConsult workflow, may require the provider who requested a referral to confirm that the request has been completed. In this case the flow will typically be as follows:

Business Event Message EventCode Target System Details
Specialist provides response notify-update-process-request RMS Source Task.code is "process-request-consult"
Task.status is "completed"
Task.output.valueReference() references the service plan or response (Communication) Communication.payload.contentString contains the specialist's consult response
Requester confirms that request has been completed notify-update-servicerequest RMS Target ServiceRequest.status is completed
ServiceRequest.supportingInfo references QuestionnaireResponse
QuestionnaireResponse.questionnaire references Questionnaire
QuestionnaireResponse contains responses from the requester to performance questions related to billing and service utilization
Requester cancels request revoke-service-request RMS Target ServiceRequest.status is revoked
Requester redirects request revoke-service-request followed by add-service-request RMS Target ServiceRequest.status is revoked followed by ServiceRequest.status is active
Performer responds to consult request suggesting eReferral notify-update-process-request RMS Source Task.code is "process-request-consult"
Task.status is "completed"
Task.output.valueReference() references the service plan or response (Communication)
Task.output.code is a code representing eReferral (insert code here
Communication.payload.contentString contains the specialist's consult response
.extension:PatientNeedsToBeSeen is set to true

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-service-request 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-service-request 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-service-request"
                    },
                "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.)