Profiles & Operations > Integration Methods
Integration Methods
This specification includes the following related methods to submit an electronic referral:
SMART on FHIR:
SMART on FHIR is an "App Platform for Healthcare", which provides a common architecture for applications to create "apps" the can be easily plugged into Health IT systems, using FHIR, OAuth2, OpenID Connect and a lightweight UI integration inside browser widgets or inline frames using HTML5. RMS Targets can define their own custom business logic and user interface into their SMART on FHIR app, while simultaneously pull key information from referral source systems.
The SMART on FHIR approach has the additional benefit of making this referral specification applicable to any SMART on FHIR enabled system, which is being increasingly adopted by major EMR vendors, health systems, and even Apple's personal health record feature.
This specification does not describe the detail of how to build a SMART on FHIR app and its workflows; it is assumed that the reader has a basic understanding of SMART on FHIR. To learn more about launching or building a SMART on FHIR app, visit the SMART on FHIR documentation page.
Direct API submission:
In the Direct API submission method, the RMS Source submits the referral payload directly to the RMS target via backend API mechanisms. The payload being sent matches that being sent in the SMART on FHIR method, except that it uses a different message event value.
Unlike the SMART on FHIR submission methods, the RMS Target does not present any UI to the user. It is up to the RMS source to generate all of the UI components.
eReferral Message Events
This specification is built primarily around a messaging paradigm. In the messaging paradigm, all payloads are sent as a "MessageHeader" bundle. All messages are POST operations, and go to the same endpoint no matter the event:
POST [base]/$process-message
Each message includes an event ("MessageHeader.eventCoding") indicating the purpose of the message. Message events in this specification are split into groups as per the step in the workflow that they related to.
The following interactions are included in this eReferral specification:
Submit Referral
"Submit Referral" messages are messages that relate to the process of sending a referral. As discussed in the Workflow Overview Section, there are 2 methods of submitting a referral:
- Submit Referral Method 1: SMART on FHIR
- Submit Referral Method 2: Direct API submission
The following message events is used in the workflow Submit Referral Method 1 - SMART on FHIR:
- acknowledge-add-service-request – to inform the RMS Source of a successfully delivered service request
Alternatively, a referral can be submitted with Submit Referral Method 2: Direct API Submission:
- add-service-request – submit a referral directly from an RMS Source to an RMS Target.
Once submitted, progress updates to the eReferral (e.g., status changes, appointments, etc.) are made at the RMS Target, and are communicated back to the RMS Source with the same set of messages no matter the submit method used.
Scope
A MessageHeader bundle with the relevant eventCoding is sent between the two of the actors, depending on the event:
| Event | Submission Method | Requester | Endpoint | Response |
|---|---|---|---|---|
| notify-add-service-request | SMART on FHIR | RMS Target | RMS Source | Operation Outcome |
| add-service-request | Direct API | RMS Source | RMS Target | ServiceRequest bundle |
The actors and roles differ depending on if the submit referral process is being used:
Submit Referral Method 1: SMART on FHIR
| Actor |
Role |
|---|---|
| RMS Source | Submits referral data to the SMART on FHIR with FUS Server, then launch the eReferral app at the RMS Target. |
| RMS Target | Provides SMART on FHIR eReferral app where referrals are submitted |
| User | Directs the submission the referral through the UI presented by the referral app at the RMS Target. |
Submit Referral Method 2: Direct API Submission
| Actor |
Role |
|---|---|
| RMS Source | Submits referrals to the RMS Target. |
| RMS Target | Receives and processes submitted referrals from the RMS Source. |
| User | Directs the submission of the referral through the UI presented by the RMS Source. |
Expected Behavior
The RMS Source SHALL send a message which contains all eReferral information from the RMS Source. The RMS Target MUST respond with a Bundle containing a LaunchString element (or an OperationOutcome resource if an error occurs), used to open the eReferral SMART on FHIR application in a browser. The SMART on FHIR application SHALL be used to submit a new referral. The SMART on FHIR app and RMS Source MUST be able to handle abandonment of the referral in the app before submission.
From the perspective of the RMS source application, the workflow is as follows:
| Step | Behaviour Description |
|---|---|
| 1. Select the target SMART on FHIR app: |
1a. Select the target HealthcareService: Different SMART on FHIR apps can be used to refer to different services. The selection of the SMART on FHIR app for referring is the responsibility of the RMS source and is out of scope for this specification. Note that the target HealthcareService does not need to be a physical service; it can be a decision support tool of any type to help the patient journey. For example, it can be a search page to find community based organizations in a specific region, which then leads to the appropriate referral page. 1b. In order to route the referral to the appropriate SMART on FHIR app, the RMS Source system should follow the SMART on FHIR Specification. |
| 2. Open the LaunchString | The RMS Source opens the LaunchString in one of the following common modes: 1) a modal widget/window (iFrame) 2) inline (iFrame) 3) link to a new page 4) in a new tab |
| 3. User Interacts with SMART on FHIR eReferral App | The user is presented with a UI provided by the RMS Target, which shows the referral business logic for the selected HealthcareService. There are two possible outcomes in the app: 1) Abandon the Referral (it is the responsibility of the RMS Source to manage the undelivered service request) 2) Submit the Referral (RMS Target will notify the RMS Source using the notify-add-service-request event) |
| 6. Close the SMART on FHIR eReferral App | There are 4 ways to close the app: 1) [modal/inline launch] The RMS Source performs a close action (for modal/inline launch) 2) [modal/inline launch] The RMS Target requests that RMS Source performs a close action (RMS Source must include listener code) 3) [link launch] The RMS Target navigates to a redirectURL provided by the RMS Source, after the referral is submitted or cancelled 4) [new tab] User manually closes the browser tab In all methods, after the work of the app is complete, the app should clearly indicate to the user that it can be closed. |
Specifying the Requester
The RMS Source MUST provide a requester for each ServiceRequest. This can be either via the ServiceRequest.requester element, or it could be extracted from a user based authentication mechanism between the RMS Source and RMS Target (which is not covered in this document). See consumer responsibility section for more details.
Message Responses
A synchronous response is expected (in case of Direct API Integration), where the response to the initial message is provided on the same channel shortly after submitting the initial message. The response will echo back the submitted message with the following changes:
- as a bundle instead of a message
- the Task resource will be added
- any changes the RMS target makes to the data (such as stripping out data elements that the RMS target cannot process)
An asynchronous response is expected if SMART on FHIR is used.
Update Referral (Notifications)
"Update Referral" messages are sent from RMS Target to the RMS Source (+3rd party servers) to notify them of the creation or changes to service requests. The following events are available:
- notify-update-service-requests: When the core service request information has changed
- notify-add-appointment: When a new appointment has been added to a service request
- notify-update-appointment: When an existing appointment has been changed
- notify-update-status: When the status of the service request has changed
This has application in a number of scenarios:
- Updating the RMS source of the changing state of a referral
- Passing on information to a 3rd party system such as a provider EMR/EHR or case management system
- Registering information in a repository
Scope
A MessageHeader bundle with eventCoding element set as the relevant "Update Referral" event is POSTed by the RMS Target to the RMS Source or 3rd Party FHIR server's registered endpoints, which will result in a simple acknowledgment of receipt. Various systems will treat and respond to these messages different depending on the use case (i.e., the message may be treated as a simple notification or more akin to a data synchronization command).
To receive an "Update Referral" message, the RMS Source or 3rd party server must have registered its endpoint with the RMS Target server.
The RMS Target is responsible for the post-submission state, business process handling, and status of the eReferral. Thus, only the RMS Target can issue Update Referral (notification) messages of a submitted referral.
| Actor | Role |
|---|---|
| RMS Source | Receives Update Referral messages from the RMS source |
| RMS Target | Sends Update Referral messages to the RMS source and 3rd party systems |
| 3rd Party System | Receives Update Referral messages from the RMS source |
Revoke Referral
The RMS Sources submits a message to the RMS target commanding it to revoke the referral, which should remove all recorded PHI for the referral in the referral target system
If the patient requests to revoke consent to a previously submitted referral, the RMS Source may ask the RMS Target to revoke the referral via the API. The RMS Target must comply with this request, and clear its record of personal health information related to the referral.
There is only one message event for the revoke workflow:
- revoke-service-request
Communication about Referral (future phase)
Communication messages are issues by any actor, to add ad-hoc communications and documents to the referral, after the initial referral has been submitted.
- send-communication-from-requester – Send a communication from the RMS Source to the RMS Target
- send-communication-from-provider – Send a communication from the RMS Target to the RMS Source
Further communication about a referral AFTER it has been submitted, between the RMS Source and RMS Target, may be required for the referral process.
The following diagram illustrates the messaging data flows:
The resource cannot be rendered.
Interaction Diagrams
The following diagram illustrates the interaction between a FHIR submitting system and receiving system:
The resource cannot be rendered.
Select Target HealthcareService
The method of selecting the target HealthcareService is handled by the RMS Source and is outside of the scope of this implementation guide.Launch/Submit Referral Method 1. SMART on FHIR (RED)
The SMART app launches as per standard SMART on FHIR EHR Launch model, using the eReferral data from the RMS Source's SMART on FHIR server.
The user is presented with the SMART on FHIR referral app UI in a browser or inline widget to guide them through the referral process, including a submission step. Some or all data may be pre-filled with integration data.
If a referral request was not delivered to the RMS Target, it is the responsibility of RMS Source to manage the undelivered service request. . If the referral was delivered, then a message using notify-add-service-request event will be sent to the RMS Source.
Submit Referral Method 3: Direct API Submission
For an integration via a direct API instead of SMART on FHIR, data is submitted from RMS source to RMS target directly, and notifications are sent out to the RMS Source and relevant 3rd parties. No UI from the RMS target is presented to the user.Update Referral at RMS Target
Once submitted, the RMS Target is responsible for progressing the state of referral (e.g., adding appointments, updating status, etc…). Each type of update has a message that is sent by the RMS Target to the RMS Source and any relevant 3rd parties.Communicate About Referral [FUTURE PHASE]
Once submitted (or with the submission), RMS Source and RMS Targets can send bidirectional communication to each other, including commentary and attachments.Revoke Referral (Future Phase)
If the patient revokes consent from the referral, the RMS source can command the RMS target to clear the PHI from its records. A notification of the revoke is then sent by the RMS Target to the RMS source and any relevant 3rd parties.