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 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 the Identifier.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}"
    },
    "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

The table below outlines the list of all 'action' parameters for SMART launching into Ocean.