SMART on FHIR Implementation Guidance

Helpful Information About Implementing SMART With Ocean

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.