Helpful Information About Implementing SMART With Ocean
The purpose of this article is to accelerate your implementation activities using the HL7 SMART on FHIR framework to launch Ocean 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. Updated content since the previous published version will be preceded by ***
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
- 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.
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 'Notify on Sent Referrals from this Site'.