HL7 FHIR eReferral Integration Setup Guide

  

Getting Started With the Integration

Service providers can manage Ocean eReferrals within their patient electronic medical record (EMR) or client management system (CMS) through integration with Ocean.  The integration enables:
  • eReferrals to appear within the EMR/CMS without requiring initial activity within the Ocean portal;
  • Status updates to the eReferral (e.g. accepted, booked, cancelled) to be sent to Ocean (which will result in a notification to the provider and patient);
  • Updates to the patient's core demographics to be sent to Ocean;
  • Referral-related communication to be added to the referral (e.g. patient or provider instructions, attachments.)

 

Receiving Referrals from Ocean

The following setup guide is intended to provide software developers with the preliminary steps required to prepare an Ocean site for integration with an EMR/CMS.  Additional detail for each step is provided in the linked support articles. Completion of these steps will enable the testing of non-authenticated connectivity and receipt of the Ocean HL7 FHIR eReferral resource bundle.   

  1. Email Ocean Support with the email domain that you will be using during technical development and testing (e.g. to register new users, receive referral notifications, etc.).  Please identify the name of your company and integration project sponsor (e.g. a clinical or jurisdictional organization).
  2. Create an Ocean user account and site in test.cognisantmd.com
  3. Generate the site's Shared Encryption Key (SEK).
  4. Enable Cloud Connect within the Ocean Portal - see the "Enable Ocean Cloud Connect" section.
  5. Access Cloud Connect and store the SEK  - see Steps 1 and 2.
  6. Configure the API endpoint for your EMR/CMS - HL7 FHIR eReferral tab > Step 1
  7. Set up the service directory listing for your site - complete the basic details for the listing and under "eReferral Policy", enable 'Accept eReferrals'. 
  8. Establish a linkage between the service directory listing and the API endpoint - HL7 FHIR eReferral tab > Step 2.

  9. Sign into your Ocean account,  search for your directory listing in the Ocean Healthmap and submit an eReferral.

 

Sending Referral Updates to Ocean

In order for the EMR/CMS to send updates to Ocean, the following additional setup steps are necessary. The HL7 FHIR APIs that support the eReferral messaging lifecycle are described in a separate API documentation.

  1. Set up the site-specific OAuth2 credentials to communicate with Ocean - HL7 FHIR eReferral tab > Step 3.

 

 


Custom Ocean Integrations

The sections below describe steps necessary to enable different types of integrations between Ocean and your other business information systems in order to automate and streamline information flows:

  • HL7 FHIR eReferral APIs to receive referrals and send updates to Ocean using the HL7 FHIR R4 format
  • Ocean's Open eReferral APIs to receive referral notifications, retrieve referrals and send updates to Ocean
  • Ocean's Open Patient Engagement APIs to create patient-specific Ocean eForms and retrieve them once they are completed.
  • A Referral System Launch to redirect to an external website to complete a referral that has been initiated in Ocean.
HL7 FHIR eReferral Open API eReferral Open API eForms

Step 1: Setting up a Webhook Endpoint

  • Click the Admin View > Integrations> "Register an Integration."
  • Click on the eReferrals option for the integration type.
  • For the Payload Type , select the FHIR option.
  • Name the integration and paste into the Request URL field the URL that Ocean will send the FHIR payloads to.
  • Select the authentication scheme that Ocean will use to authenticate with your system's endpoint and enter the relevant parameters.
  • Select the events that Ocean should notify your system about.
 

Step 2: Linking the Service Directory Listing With an Integration

  • Click the Admin View > Directory Listings> tab and open the Advanced section at the bottom of the page.
  • The integrations specified for the Ocean site will be listed in the Integration field. Select the one that should be linked to this directory listing. Enter the same value into the External Service ID field.
  

Your Ocean site is now ready to send eReferrals to your point-of-service system using the HL7 FHIR eReferral APIs.

 

Step 3: Generating Ocean OAuth Credentials

Systems must send Ocean a site-specific Client ID and secret in order to receive an OAuth token(s) that can be used to submit referral updates for that Ocean site. To generate the Client ID and secret:

  • Click the Admin View > Manage Credentials > Manage OAuth Credentials button.
  • Add a meaningful name and click the "Add New Credential button."
  

Your Ocean site is now ready to receive eReferrals from your point-of-service system using the HL7 FHIR eReferral APIs.

 
 

Referral System Launch

    • Click the check-box "Activate a Referral System Launch when Sending a Referral" to set up the user display messaging and redirect that will occur.

The following fields can be set as part of 'header' and 'footer' that will automatically appear at the top and bottom of the referral form.

  • Company Name - of the system that will be launched
  • Base launch URL - the URL that the redirect will be sent to
  • Application Name
  • Catogory Field

You can optionally set additional advanced settings:

 

  • Referral Form For Associated Listings - Attach a specific referral form that is associated with the listing
  • Confirmation Message (Override) - Customize the confirmation message for accepted referrals.
  • Logo - Personalize referrals by including a logo
  • Use Embedded <iframe> - Enabling this setting will launch the redirect URL in an iframe.

HL7 FHIR eReferral API Implementation Guidance

  

We're Looking Forward to Connecting With You!

The purpose of this article is to accelerate your HL7 FHIR eReferral implementation activities by sharing guidance and considerations collected from other Ocean HL7 FHIR eReferral implementations.  It is divided into the following sections:  
    • Authentication Documentation - related to Ocean’s OAuth2 implementation
    • API Documentation - related to Ocean’s implementation of the Ontario HL7 FHIR eReferral implementation guide
    • Data Mapping - guidance on the intent and usage of various FHIR resource fields in the context of the Ocean implementation
    • Technical Considerations - things to consider when developing your APIs
    • ***Implementation and Testing - tips for assessing the integration behaviour within 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.   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

RMS Target - the system(s) downstream from Ocean that is receiving and acting upon an eReferral.

Service Request ID - this corresponds in the FHIR messages to Ocean’s referral identifier

SiteID - Ocean’s identifier for the site set up by the service provider within Ocean to send and/or receive (and manage) eReferrals

 

Authentication Documentation

  • In order to set the OAuth2 Credentials in the Ocean Portal, you must have the site’s Shared Encryption Key (SEK) (see Step 2 here).  If you do not already have it, the Ocean site administrator can provide this you or it can be retrieved from Cloud Connect.   See here for other options
  • Ocean returns the standard 401/403 response error codes for authorization-related errors around accessing our secured endpoints through OAuth2.
  • If you become locked out of the OAuth2 token exchange, this can be reset by the site administrator.  They can access the Site Admin > Site Credentials > OAuth credentials page and click on the padlock icon.

 

API Documentation

  • The Ontario eReferral Implementation guide has a Profiles and Operations section that includes links to specific profiling documentation for each FHIR resource used in the specification. Each of these profiles lists for each field whether that field is required (the big red S), the required cardinality of the field, the accepted enum values if that field is an enum, any specific invariants that the field is associated with, and any other relevant information associated with it.  For example, the telecom field on the Patient Resource  has been profiled such that it is required, and the system, value and use sub-fields are required but not the rank or period sub-fields.
  • Ocean’s response/error handling follows the guidance included in the Ontario eReferral HL7 FHIR Implementation Guide and the general FHIR messaging documentation:
  • Successful messages will return a 200 response code.  The body is immaterial, as a 200 code means Ocean successfully received and processed the referral.
  • Messages that Ocean cannot process for any reason (bad data, missing data, unparseable JSON, etc) will return a 40X/50X response code with a FHIR OperationOutcome Resource as the body that will have a description of the error.  It includes an ‘issues' section where the server will present some human-readable debugging information to assist in determining the reason the error was issued. That information can be anything from JSON parse errors, specification validation errors (missing required fields or using the wrong datatypes), business logic errors (e.g. trying to update a referral that doesn’t exist) and internal processing exceptions on our end (usually bugs). With this information and the error response, there’s usually enough to go on to try and find the underlying issue efficiently. 
  • Ocean does not send a Task resource in any of its messages.   The Task resource is only sent by the RMS Target system to indicate how the original ServiceRequest has been acted upon by RMS Target.  The API documentation includes examples of the Task resource in the inbound message events sent to Ocean by the RMS Target.
  • Ocean will ignore any empty demographic fields sent in the Update-Service-Request message from the RMS Target (rather than overwriting/deleting the existing value).
  • The OAuth2 token sent by the RMS Target provides Ocean with the information that is necessary to derive which site the message belongs to (since every token pattern is site-specific).    This is why the Ocean site ID does not need to be conveyed in the payload.
  • The RefID is used by Ocean to determine which specific eReferral the payload refers to within the Ocean site. 
  • If the RMS Target sends Ocean two FHIR Patient addresses, Ocean will store both but will only display the first one in the payload.   If more than two addresses are sent, Ocean will ignore all but the first two in the structure. 
  • *** The bundle will contain two PractitionerRole resources.  One is the describing the requestor and the other is describing the service provider.  There are links in the ServiceRequest/MessageHeader that establish which resource is connected to each practitioner.
  • *** The referrer ID is not guaranteed to be unique.  This is because the referrer may have created the referral without signing into an Ocean user account (e.g. directly from the Ocean Healthmap), so Ocean may not be able to assign a unique ID.
  • *** Every ServiceRequest bundle will include a DocumentReference to retrieve a PDF copy of the Ocean eReferral.   If the requestor includes attachments in the eReferral, these will be added to the bundle as distinct DocumentReference resources.   In this case, the PDF eReferral copy will always be the first DocumentResource resource included in the bundle.

 

Data Mapping

  • Ocean sends the following core patient and provider demographics for every eReferral:

provider_ereferral_info.PNG

 

patient_ereferral_info.PNG

  • Ocean is only capable of sending(Male, Female, Other) for the gender field and does not support gender identity or sex as a core demographic field.  Service providers may include these in the body of the eReferral form. 
  • ***Ocean checks if the HN-province field is populated with a standard two-letter provincial alpha code (e.g ON, PE).  If it is, the JHN identifier will have a Naming System like https://fhir.infoway-inforoute.ca/NamingSystem/ca-XX-patient-hcn where XX is the two-letter alpha code and the usage field on the identifier will be set to OFFICIAL.   
  • ***Users are instructed to enter the name of the identifier system into the province field when they are submitting an identifying number other than a provincial health insurance number.  For instance, they will enter "Military ID" into the HN-province field and the ID number into the health number field.  Ocean will provide the value entered in the HN-province field as a secondary health identifier and will set the JHN identifier usage field with SECONDARY.
  • ***Ocean does not validate that the submitted identifying number belongs to the identifying system (e.g. it does not perform a checksum on provincial health insurance numbers).
  • The body of the referral form (e.g. Allergies, Medical History, and any questions that the clinical service provider adds to their Ocean referral form) will be sent in the QuestionnaireResponse resource as a key name-value pair.  Ocean does not control or constrain the key names created by the service provider.  Therefore, if you intend to map the responses of specific referral form fields into RMS Target fields, you will need to coordinate with the service provider on the key names.   (This is set in the question’s Caption field, which is described in the General tab of this article.) 
  • The table below illustrates the eReferral lifecycle states that can be communicated by the RMS Target to Ocean and the corresponding Ocean internal eReferral state.  The status is communicated by Ocean in the ServiceRequest resource Status field and is updated by the RMS Target in the Task resource’s Status field . 

eReferral_status.PNG


 

Technical Considerations

  • Ocean supports both IPv4 and IPv6
  • Ocean will send the entire ServiceRequest bundle/resources each time there is an update to any of the referral fields.  The change list is provided in the MessageHeader.reason which can serve as ‘hints’ for the RMS Target to assess what has changed.   It is up to the RMS Target to decide which updates require an internal update and/or notification to the service provider.
  • There does not need to be a synchronous response to the transmission for the inbound ServiceRequest message other than a 200 HTTP response to indicate the message was successfully received. The next asynchronous status update change sent to Ocean can provide a more specific status for the referral when it is acted upon by the RMS Target. 
  • If you will be using a single endpoint to receive ServiceRequest bundles for multiple Ocean sites, you can identify who the intended recipient is by examining the ServiceRequest / Performer / PractitionerRole / Identifier, which will contain the Site ID.  
  • The ServiceRequest ID must be populated in the meta->profile section of the MessageHeader.  This is required so that Ocean can identify the incoming messages as conforming to the Ontario HL7 FHIR eReferral Specification v0.10.0 so that they can be processed accordingly. 

identifier_alternative.PNG

  • Because the APIs are RESTful, Ocean does not have the ability to replay a sent message in the event that it is not received (e.g. RMS Target is ‘down’).  It is recommended that RMS Targets have in place a strategy for mitigating API endpoint downtime.  
  • Similarly, when the RMS Target goes ‘live’ with the integration, any pre-existing eReferrals that exist within the Ocean site will not be sent to the RMS Target until they are updated (which will trigger Ocean to send a webhook notification). 
  • Ocean does maintain a log of all message sends which can be used to determine which messages have been missed.   They can be manually ‘forced’ to be resent to the RMS Target by making an update to the referral within the Ocean portal.

***Implementation & Testing

  • ***As a referral is updated in Ocean, it will move between various 'folders' in the eReferral dashboard.  This is one way to see that the status update sent to Ocean has been processed. 
  • ***The event log for each referral can be accessed by opening the referral record and selecting 'View Event Log' from the top right 'Action' menu.  This can assist in determining if the referral is being updated as intended.
  • ***When the Ocean APIs detect a call error rate of more than 5% in the first 20 attempts, it will automatically disable the API.  It can be re-enabled by going back into Admin > Integrations, opening the relevant integration setup and then saving it. 

Open eReferral API Implementation Guidance

Ocean's Open APIs enable third-party systems to integrate with Ocean so that providers can process referrals within their preferred system or app.  In addition to the Open API documentation, we have assembled the following implementation guidance to accelerate your integration implementation.

 

eReferral Integration Sequence

The sequence diagram below illustrates the interaction sequence between Ocean and a third-party system after a referral has been created in Ocean.   

 

Ocean_eForm_Completion_API_sequence-eReferral__1_.png

 

Webhook Validation

  • The webhook requires the URL to respond to a challenge in order for it to work properly.   Testing with a webhook that is not ready to provide the challenge token in the response will fail validation.  This is indicated by a yellow exclamation mark symbol beside the URL. 

mceclip1.png

  • The validation check does not require the ocean specific headers (sitenum, sitekey) in the response, although they will not cause any errors if they are included.  For additional information, please see our API Docs

 

Payload Encryption

  • The encryption code in the Ocean API documentation is an example that illustrates the correct encryption flow and highlights the encryption library (CryptoJS) we use and recommend when working in Javascript.  But the encryption scheme is just standard AES encryption so you will absolutely be able to encrypt/decrypt this data in other languages. For instance, For Ruby, you can use the OpenSSL module in the standard library to run the AES ciphers to encrypt and decrypt the data.  There are also likely other external AES/cryptography gems you can use if you have a preference.

 

Data Mapping

  • The file at the bottom of this article lists the data elements that are available within the Open API payloads.   
  • if the site allows multiple appointment dates for a single referral, the referral listing should have multiple labels configured. By default, Ocean only enables a single label for each listing named “Appointment”.  Each referral listing (Site Admin > Directory Listing > Service Details section) can be configured by the Site Admin to accept add additional labels from the following values: appointment 1 - 5, consultation date, follow-up date, initial visit date, procedure date, surgery date.  

Appointment_labels.png

  • If an API call is sent with appointment data without a label, then Ocean will assign the first appointment label that has not been used in that referral for that appointment. If a second appointment is sent without a label and there all of the appointment labels have already been assigned for that referral, the API will return an error.   Alternatively, the appointment data can be sent with an appointment label, but it must correspond to one of the labels configured for that site.
  • The POST Update a Referral API accepts the following referral status values in the status field:  Accepted, Declined, Confirmed, Canceled, Completed, Printed, Incomplete, Sent. The field is optional and should only be populated by the Third-Party System when the referral status value is different than the previous update sent to Ocean.  Ocean will return an error of "Referral is already in the requested status” if two updates are sent with the same status value.   As such, if the Third-Party System's internal set of referral statuses are more granular than Ocean's, referral updates should contain the relevant updated information without a status value unless it will change the Ocean referral status
  • The referral is updated to a "Booked" status internally by Ocean once it receives appointment data from the Third-Party System.
  • Once a referral is in the "Completed" or "Canceled" referral status, it cannot revert to another referral status via the API.

Open Patient Engagement API Implementation Guidance

 

Ocean's Open APIs enable third-party systems to integrate with Ocean so that providers can send Ocean eForms to patients and have the completed eForms automatically downloaded into their preferred system or app.  In addition to the Open API documentation, we have assembled the following implementation guidance to accelerate your integration implementation.

 

Patient Engagement eForm Integration Sequence

The sequence diagram below illustrates the interaction sequence between Ocean and a third-party system to generate patient-specific weblinks that can be embedded in the third-party system's secure messaging service.   The patient will access the weblink to complete Ocean eForms, after which Ocean will notify the third-party system to collect the completed forms.

 

Ocean_eForm_Completion_API_sequence.jpg


Ocean SMART App Launch Overview (SMART on FHIR EHR Contextual Launch)

 

Introduction

Ocean uses the SMART App Launch industry standard to support single-sign-on (SSO) and patient-contextual launch from an electronic health record (EHR) or other health system.

Single Sign-On

The SMART launch framework allows an authenticated person using a trusted third-party health system to open a specific application or page within Ocean without having to manually sign in to Ocean. Instead, the user's EHR credentials can be used to securely and automatically sign in as their corresponding Ocean user.

Ocean adheres to the Open ID Connect standard to ensure this single sign-on process is secure.

Patient Contextual Launch

In addition to SSO, the SMART launch can optionally pass information to Ocean that is related to the EHR's currently-selected patient. The patient information includes the EHR's MRN, name, health number, gender, date of birth, contact information and other clinical information when available.

Some use cases for the patient contextual launch include:

  • Opening the patient's "Ocean Patient Dashboard" to view a summary of Ocean information related to this patient, including active eReferrals, eConsults, questionnaire results and so on. The dashboard also serves as a convenient launch point for performing other actions, such as initiating a referral.
  • Viewing the patient in Ocean's Health Map.
  • Creating a new eReferral that is pre-populated with the patient's demographic and clinical information based on the EHR chart.
  • Using Ocean to email a secure message link or questionnaire directly from the EHR chart.

Ocean reads this patient information, with permission from the EHR, by requesting "scopes" to read data from the EHR's FHIR endpoints.

Sequence of Events for Users

  • A user is signed into the EHR system.
  • The user clicks on an "Ocean" launch button in the EHR's UI.
  • The launch button opens Ocean in a new web browser tab or window. The launcher supplies Ocean with a URL containing the basic launch credentials (based on the SMART protocol).
  • Next, in the background:
    • Ocean uses the launch credentials to request authentication information from the EHR using the OAuth 2.0 protocol.
    • In response, the EHR provides Ocean with an access token, which provides Ocean with basic information regarding the current EHR user and the current patient.
    • Ocean checks whether the EHR user has already been linked to an Ocean account.
  • If the user has not yet linked their EHR account to Ocean, a sign-in prompt is shown:mceclip0.png
  • Once the account is linked (and from then on in future launches), the single sign-on is automatic.
  • Next, if a patient was specified, Ocean asks the EHR for information about the current patient (using the EHR's FHIR APIs).
  • Finally, Ocean redirects to the requested page within Ocean. This page can be either a patient-specific destination, such as the Ocean patient dashboard, or a general destination like the Ocean Portal, depending on the "action" requested by the SMART launch button's launch URL.

The sequence diagram below illustrates the backend interactions between systems that occur to enable the Ocean SMART single-sign-on and contextual launch:

 

SMART_on_FHIR_Workflow.png

Requirements

To connect to Ocean, launching systems must:

  • Implement and support the SMART "EHR launch sequence" as the "EHR FHIR Server / EHR Authorization Server" (Ocean is the "App" in this context) 
  • Provide OAuth 2.0 endpoints for the SMART launch.
  • Adhere to the Open ID Connect protocol as the launching system. As part of the protocol:
    • Provide public access to the endpoint: [the-fhir-server]/.well-known/openid-configuration
      • (Ocean accesses this endpoint as part of the Open ID protocol, to ensure it can validate the launcher's JWT signature using the public key that is specified in the configuration's "jwks_uri".)
    • Sign the JWT token with the ES256 or RS256 algorithm.
  • Provide at least one configurable launch URLs for Ocean for the system's users. These launch URLs must permit variable path names depending on the Ocean site, desired Ocean action, and so on.
    • Examples of Ocean SMART launch URLs include:
      • Viewing the patient in Ocean's Health Map - https://ocean.cognisantmd.com/sso/smart/auth?siteNum=1234&action=viewMap
      • Opening the patient's "Ocean Patient Dashboard" - https://ocean.cognisantmd.com/sso/smart/auth?siteNum=2000&action=portal

In addition, to support patient-contextual launch, systems must:

  • Support FHIR R4 for the Patient.read endpoint as part of the SMART App Launch context.
  • Provide a "patient" parameter in the SMART launch access token.
  • Adhere to established FHIR conventions for storage of relevant PHI used by Ocean, such as the use of the "JHN" health number identifier and the version code identifier for Ontario patients.

We also recommend the following:

  • Provide the Base64-encoded value for the Ocean site's shared encryption key as the value for a "oceanSharedEncryptionKey" attribute in the SMART launch access token.
    • This optional parameter will save users from the requirement to manually enter their site's shared encryption key in their web browser.

Allowlisting

For security reasons, all health system servers that would like to use a SMART launch into Ocean must be privately allowlisted by an CognisantMD Ocean administrator.

The allowlisted entry for a launch system must have the following values:

  • The server URL:
    • Provided as the initial "iss" parameter during the SMART launch. This value should also correspond to the FHIR API server.
  • Client ID:
    • The unique unguessable "client_id" for Ocean, as randomly assigned by the launching server. (This is the URL parameter supplied by Ocean during the initial SMART redirect back to the launcher's authorization endpoint.)
  • Authorization endpoint:
    • The OAuth 2.0 "/authorize" endpoint
  • Token endpoint:
    • The OAuth 2.0 "/token" endpoint
  • Token issuer URL:
    • The "iss" value provided within the signed JWT claims set, within the id_token value of the authorization token.

With the exception of the client ID, all of these values should be available in the EHR server's .well-known/openid-configuration endpoint and/or the FHIR metadata endpoint.

For security reasons, Ocean performs strict validation of the JWT token to adhere to the Open ID Connect precautions. (If any aspect of the JWT token does not pass the protocol, Ocean attempts to provide a helpful error message for troubleshooting.)

 

Please contact us if you would like to connect your SMART on FHIR-compliant server with Ocean. Plan to provide us with the values listed above.