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.
- Guidance for the $everything Operation - Detailing the advantages of the new /Patient/[id]/$everything operation and providing guidance for SMART launch integration configurations.
- FHIR Context - Additional information on the FHIR context with the SMART Launch.
- 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.
- Sharing the POS Referral ID With Ocean - Details regarding the POS/FHIR server’s internal referral ID and how Ocean can send this back to the POS system.
- SMART Launch 'action' Parameters - A list of all the 'action' parameters for SMART launching into Ocean.
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 having the provider 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 it's 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 of 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. 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.
Guidance for the $everything Operation
- Ocean virus-scans all attachments it receives via the $everything endpoint.
- The /Patient/[id]/$everything operation is a new alternative to the Patient.read endpoint. It provides Ocean with additional important information for the contextual launch.
- Implementors may configure in their SMART launch integration whether Ocean should use Patient.read or the more comprehensive $everything operation during the contextual launch.
- In particular, the $everything operation allows Ocean to read the following patient information for the sake of pre-populating Ocean forms:
- Medications
- Allergies
- Problem list
- Past Medical History
- Family History
- Chart Attachments (pre-selected)
- Observations/Vitals/Lab Values
- Immunizations
- Ocean will process the following FHIR resources when they are included in the $everything bundle:
- MedicationStatement
- AllergyIntolerance
- Conditions (for vitals and lab values)
- Appointment
- Observation
- DocumentReference (for pre-selected chart attachments)
- Immunization
- Please refer to this guide for additional information.
Specifying the MRN and Health Insurance values to be populated
- In a scenario where the Patient resource has multiple identifier properties corresponding to different medical record numbers (MRN), Ocean has introduced a SMART launch query parameter to instruct Ocean which MRN value to populate:
-
mrnText
matches against theIdentifier.type.text
that Ocean will look for to grab the corresponding MRN value.
-
- Similarly, SMART servers use different systems for specifying the identifier corresponding to the health card / insurance number (HCN). In order to instruct Ocean which identifier to use to populate the Ocean HCN field:
-
jhnSystem
equals the system value of the identifier property that Ocean will look for to grab the corresponding HCN value. For instance, Epic sites would add the following to their launch string: &jhnSystem=https%3A%2F%2Fopen%2Eepic%2Ecom%2FFHIR%2FStructureDefinition%2FPayerMemberId
-
- Ocean will perform an exact match (excluding “quotation marks”) and will revert to the default value if a match is not found. Special characters can be encoded.
FHIR Context
- When initiating a SMART launch for a service request (e.g., eReferral, eOrder, or eConsult), Implementors can include the ID of their launching system's preliminary service request record in the SMART fhirContext.
- If provided, Ocean stores this ID with the service request and includes it in the identifier list for subsequent FHIR messages related to the service request.
- This feature facilitates the linkage between the preliminary service request record in the EHR (commonly termed a "pending referral or consult") and the backend FHIR messaging of the service request.
- The fhirContext is included in the response token, alongside the access_token.
- It must be part of the token JSON, formatted as an array, like this: [{"reference": "ServiceRequest/{serviceRequestId}"}].
- For more information on the FHIR context, refer to the official article on SMART scopes and launch context.
-
Example of a Launch Context Token
{ "access_token": "{access_token to use for subsequent FHIR API calls}", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "{refresh_token; ignored by Ocean}", "scope": "{granted scopes; should generally match the requested ", "patient": "{patientId, or omitted if no patient in context}", "encounter": "{encounterId, ignored by Ocean}" "id_token": { %% valid signed JWT with OIDC-compatible encoded values "sub": "{user uuid}", "iss": "{token issuer URL}", "aud": "{client_id}", "exp": {expiry date/time e.g., 1679028255}, "iat": {issued date/time e.g., 1679024655}, "nonce": "{nonce GUID; optional; must match Ocean's if provided}" }, "intent": "action={oceanAction}&resource={oceanResource}", %% optional "tenant": "opaque organization UUID; ignored by Ocean", %% optional "fhirContext": "[{"reference": "ServiceRequest/{serviceRequestId}"}]" }
The sequence diagram below illustrates the backend interactions between systems that occur to enable the Ocean SMART single-sign-on and contextual launch. (a PDF file is available at the bottom of this article).
Receiving a Copy of the Referral Automatically
- The requestor may want a copy of the referral in the patient's record within the POS. This copying process can be done manually by copying and pasting from Ocean.
- Alternatively, automation is possible if the POS/SMART server system implements either Ocean's eReferral FHIR APIfor receiving new eReferrals or Ocean's Open eReferral API to retrieve eReferrals. In this case, Ocean will send a webhook notification to the specified endpoint, with a FHIR message event of notify-add-service-request (for the eReferral FHIR API) or notify-upstream-service-request (for the Open API).
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 / FHIR Intent
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. |