Helpful Information About Implementing SMART With Ocean
This video provides an overview of how HL7 SMART on FHIR can be used to launch into Ocean, as well as tips for getting started on a SMART server implementation. This article will further accelerate your implementation activities by sharing guidance and considerations collected from other implementers. It is divided into the following sections:
- Setup Considerations - Important items to address to prepare for the system-system 'handshake'.
- Deeper Dive into the Sequence Flow - Additional details on the data being passed between systems and how it is being used.
- Receiving a Copy of the Referral Automatically - Using APIs and Ocean configurations to automatically receive a copy of the referral that has just been sent from the SMART launch.
This will be a 'living' support article as additional guidance is collected. It is suggested that you ‘follow’ it in order to receive a notification when it is updated.
Definitions Used In This Article
Requestor - the individual (provider or patient) that is submitting a referral request.
Service Provider - the clinical or community-based service/organization/provider that is receiving a referral request to deliver a service to the patient.
Point-of-Service (POS) - the patient record management system used by the requestor (e.g. EMR, HIS, case management system, CRM).
SMART Server - the software component utilized by the POS to enable the contextual launch into Ocean.
Single-Sign-On (SSO) - the ability to access one's Ocean user account without having to manually enter one's username and password.
Contextual Launch - the ability to access Ocean using SSO, as well as having the patient that is 'in context' in the POS be brought 'into context' within Ocean without the providing have to manually search for that patient and/or enter that patient's data.
Client ID - an identifier issued by the SMART Server to Ocean to recognize it as a SMART App.
SiteID - Ocean’s identifier for the site set up by the service provider within Ocean to send and/or receive (and manage) eReferrals
Set-up Checklist
- Provide the Ocean team with the SMART server's endpoints so that they can be added to the Ocean allowlist (see the Allowlisting section here).
- The Client ID (used in Steps 3, 4, 11) is supplied by the SMART server to Ocean during integration set-up. Ocean stores it and sends it back when its launched.
- Ocean only needs one Client ID per SMART server URL. The same Client ID can be used for multiple organizations with Ocean sites, as long as they are hosted in the same environment. (e.g. a SaaS POS system)
- Ensure that the development framework allows customization of the access token and ID tokens. Some frameworks, such as Javaspring and .NET, allow for control to the flows, but others are less customizable.
Deeper Dive Into the Sequence Flow
- The Patient ID (Steps 8, 9, 15, 16) is the identifier used to uniquely identify the patient within the POS. It does not need to follow a prescribed identifier format (e.g. the GUID in step 16 is an example).
- Ocean only uses the Patient ID as a key at the FHIR Patient.read endpoint to retrieve the Patient resource.
- The POS/SMART server's Patient.read resource will ideally provide all of the data required to pre-populate the Ocean eReferral patient information section (see image). However, Ocean will not reject a sparsely populated Patient resource; it will leverage the data available (and the referral requestor will have to manually populate the missing fields).
- Conversely, Ocean will ignore any additional demographics received in the Patient resource that are not required to complete the eReferral patient information section.
- The sub field in the JWT id_token payload (Step 9) contains the POS/SMART server's unique identifier for the user. Ocean will perform a search based on the demographic fields in the id_token to identify a matching Ocean user and then store a linkage in the user's Ocean account to the POS userID to enable single-sign-on.
- The POS/SMART server UserID-Ocean UserID linkage is not affected if the user changes their POS password or any other demographic data besides for the UserID itself.
- Ocean can only be launched via SMART as a new browser tab; it will not launch in an iFrame.
- Ocean virus-scans all attachments it receives via the $everything endpoint.
Receiving a Copy of the Referral Automatically
The requestor will likely want to have a copy of the referral in the patient's record within the POS. While this can be performed manually by copying and pasting from Ocean, it can also be automated if the POS/SMART server system has implemented either Ocean's eReferral FHIR API for receiving new eReferrals or Ocean's Open eReferral API to retrieve eReferrals. Ocean will send webhook notification to the specified endpoint (with a FHIR message event of notify-add-service-request and for the Open API notify-upstream-service-request).
This service can be enabled within the Admin > Integrations > Register a Referral Integration dialogue by selecting 'Allow a copy of the referral to be sent to this endpoint when a new referral is sent from this site'.
Sharing the POS Referral ID With Ocean
It is possible to send Ocean the POS/FHIR server's internal referral ID so that it can be included in the FHIR eReferral payload that Ocean sends back. This is useful for POS systems that create an internal referral ahead of launching into Ocean and they want to merge the payload back into that internal referral.
The internal referral ID can be sent in the fhirContext parameter in the access token to pass the SMART launcher's stub referral ref e.g. [{reference: “ServiceRequest/123”}]. Ocean will use the initial Server iss URL parameter that is provided by the EMR at launch and combine it with the fhirContext.
By concatenating the two values above, it will produce a globally unique uri for ServiceRequest.identifier.value = https://chr.telus.com/fhir/ServiceRequest/123
Along with Ocean's referral identifier, this POS referral identifier will appear in the ServiceRequest identifier property with the value ServiceRequest.identifier.system = urn:ietf:rfc:3986.
SMART Launch 'action' Parameters
The table below outlines the list of all 'action' parameters for SMART launching into Ocean.
action Parameter |
resource Parameter (if used) |
Description |
---|---|---|
viewMap |
N/A | Launches the user into the Ocean Healthmap |
viewHealthServices |
The relevant Health Service Category (e.g., CARDIOLOGY_SERVICES) | Launches the user into the Ocean Healthmap filtered for a specific Health Service |
searchHealthMap |
A simple search keyword or phrase (e.g., "blood pressue"). Non-alphanumeric characters must be URL-encoded (e.g. with a "%20" instead of a space). | Launches the user into the Ocean Healthmap and searches for the relevant keyword |
referDirect |
The Directory Listing reference value | Launches the user into the Ocean Healthmap directly to the Directory Listing reference value specified as the 'resource' |
portal |
N/A | Launches the user into the Ocean Portal |
sendMessage |
Optional - The message template identifier | Initiates a new message to the patient with the specified message template or the default one if none is specified |
addForm |
N/A | Allow the user to search for and queue any Ocean eForms for the patient to complete |
viewServiceRequest |
The reference value for the relevant eRequest (eReferral/eConsult/eOrder) | Launch the user directly into a specific eRequest. |
viewReferralFavourite |
The identifier of the favourite item. | Launches the user directly into a referral for the the Directory Listing Offering in the list of favourites specified as the 'resource' |
debug |
N/A | Stays on the launch page for troubleshooting purposes. Can also be of form debug:[action] (like debug:addForm ) for more specific information. |
[blank] | N/A |
When the Action parameter is left blank or omitted, the user is launched into the Patient Summary View for the current EMR patient by default. If no patient is provided in the launch context, the user is simply redirected to the Ocean Portal. |