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 |
| 11a. | Requester requests clarification from the Performer | send-communication-from-sender | Communication | RMS Source | RMS Target |
| 11b. | Performer responds with an update(s) to the Task and/or its Status as work is performed | notify-update-process-request 4 | Task (process-request) | RMSTarget | RMSSource |
| 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.
^*^Task.code of the StructureDefinition: Task Profile can be used to differentiate between primary task associated with tracking the status of eReferral vs eConsult.
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.
4 The notify-update-process-request in step 11b corresponds to the notification about any update(s) made for the consultation request.
Contributions to Repositories for Analytics and Performance Monitoring
An RMS (typically an RMS Source system) 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. This system will perform the role of "Referral Event Contributor"
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.
Refer to the eReferral Analytics Repository section for the detailled use case and repository events.
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 anentryfor 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
eventCodingidentifying the trigger event and other message related metadata including anid,source.endpoint,destination.endpointis used to convey the purpose of the message and to support message routing.The Focus of the Message:
MessageHeader.focusSHALL 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.entryelement SHALL have a uniquefullUrlandresourceso 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 requestedServiceRequest.performerwhere, each SHALL reference an Organization, Location and/or Practitioner - references to other
ServiceRequest.supportingInfowhere needed (see below)
Illustration: ServiceRequest Message Bundle
Specifications:
Message Bundles corresponding to different Focus resource are specified on the following pages:
- Message Bundle: ServiceRequest
- Message Bundle: Task
- Message Bundle: Appointment
- Message Bundle: Communication
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.focuswill 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. |
| Communication related to the ServiceRequest sent by RMS Target | send-communication-from-provider | N/A | The RMS Target can send a question, request information, or general communication related to a ServiceRequest. |
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.status 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 |
| The requester needs some additional information and sends it using 'send-communication-from-requester' regarding the ServiceRequest | send-communication-from-requester | Information Requested Request Updated Requested Information Updated |
RMS Source MAY send a question, request clarification, or for general communication related to a ServiceRequest |
| ServiceRequest needs a correction | notify-data-correction | Request Updated Requested Information Updated |
RMS Target MAY notify systems that it has corrected information in a ServiceRequest or related resource |
| RMS Target to notify systems that an appointment has been created in response to a ServiceRequest | notify-add-appointment | Request Updated Requested Information Updated |
RMS Target MAY notify systems that an appointment has been created in response to a ServiceRequest |
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. Note: The below workflow event is only an example workflow step to demonstrate the relationship between various statuses.
| 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.textelement;Using one of several different FHIR resources that can be referenced in
ServiceRequest.supportingInfoand then included in the message payload as aBundle.entry:- QuestionnaireResponse to provide structured form data as a list of questions and responses. QuestionnaireResponse.text narrative field should be used to provide unstructured data such a copy-paste or summary of the Questionnaire response
- 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
attachmentthat's available to retrieve from a server using aurl(recommended) or as base64 encodeddataincluded 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).
Irrespective of the performer or requester a referral or consult request is completed when BOTH the sender and receiver mark it as completed.
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.eventSHALL be "notify-update-process-request" - the
MessageHeader.focusSHALL be a reference to Task resources, where:Task.codeis "process-request"Task.statusis "completed"
Task.outputMAY reference one or more resources createdbasedOnthe current ServiceRequest (e.g.: a Communication containing a plan of care)
Request completed by Requester
In some cases, the requester of a referral or consult may be required to confirm that the request has been completed.
Note: The task.code is used to differentiate between the the eReferral vs eConsult request. For eConsult, task.code is 'process-request-consult' and for eReferral the task.code is 'process-request'
In case of an eConsult the workflow will 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) Communication.payload.contentString contains the specialist's consult response .extension:PatientNeedsToBeSeen - PatientNeedsToBeSeen is set to true |
Branching and/or Chaining Requests
In cases where a completion of a 'parent' ServiceRequest results in the creation of other 'children' ServiceRequests, multiple ServiceRequests 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 'parent' 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 'parent' 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:
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
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.)