1. OceanMD
  2. Integrations
  3. API Integrations

API Integrations

Print Guide
Follow

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)

Ocean will be supporting two versions of the FHIR eReferral API: v0.10.0 and v0.11.1. New integrators are strongly encouraged to use the v0.11.1. Existing integrators that are expanding to new sites may continue to use v0.10.0.

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. From the Menu, select Admin and then select Site Features.   Activate the "Enable Ocean Cloud Connect" option.   This will trigger a dialog instructing you to set up Cloud Connect. Select the "Go to Cloud Connect" button.
  5. In Cloud Connect, select "Store my encryption key".  (Do not access the "Integrate with my EMR" option.)  Enter the site's SEK and select 'Save'
  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. Add the Ocean test.cognisantmd.com IP addresses to your allow-list.
  10. If you would like Ocean to send you email notifications when it receives an error response from your endpoint, from the Menu, select Admin and then select Site Account. In the "Clinical Administrator / Ocean Support Contact" field, enter the email address(es) of the error notification recipient(s).
  11. Create a second site (by accessing My Account (top right menu) and clicking on 'Create New Site'.  (This is so that you can mimic the actual referral workflow of a referral being sent to and from one Ocean site to the 'service provider' site that is supported by your integration.  You only need to complete).
  12. In the second ('sender') site, search for the 'service provider' directory listing (of the first site) in the Ocean Healthmap and submit an eReferral.
  13. Follow these instructions to subscribe to the Ocean API Integration Update section to receive critical notifications specific to integration incidents.

You are now ready to receive eReferrals! 

 

Processing HL7 FHIR eReferral Message Bundles

  1. To learn about the use cases, integration flow, methods and profiling of the FHIR resources, please see the Ontario eReferral HL7 FHIR eReferral Implementation Guide v0.10.0, for the v0.10.0. To learn about the v0.11.1 beta, please see Ontario eReferral - eConsult HL7 FHIR Implementation Guide - Draft v0.11.1 
  2. To see how these are implemented by Ocean, please see our HL7 FHIR API documentation.
  3. An important companion to this documentation is our HL7 FHIR eReferral API Implementation Guidance article, which describes key concepts and considerations you should be aware of as you develop your integration.

 

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.

 

 

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 this guide in order to receive a notification when it is updated (see: ‘Keeping Up-to-Date with Ocean Feature Updates’ ).

Ocean will be supporting two versions of the FHIR eReferral API: v0.10.0 and v0.11.1. New integrators are strongly encouraged to use the v0.11.1. Existing integrators that are expanding to new sites may continue to use v0.10.0.

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 in the following article: HL7 FHIR eReferral Integration Setup Guide).  If you do not already have it, the Ocean site administrator can provide this for you or it can be retrieved from Cloud Connect.   View the following guide for additional information Recovering a Lost / Forgotten Shared Encryption Key
  • The URL for the OAuth2 bearer token request within Ocean's test environment is 
    https://test.cognisantmd.com/svc/oauth2/token
    (the OAuth 2.0 Authorization Server documentation refers to the production environment).
  • 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

Ontario eReferral Implementation Guide:

  • Ocean's eReferral FHIR APIs comply with v0.10.0 of the Ontario eReferral Implementation Guide.
  • There is a more recent version (v0.10.1) that introduces 'breaking changes' (i.e., not backwards compatible) in the MessageEventCode value set, which are not supported by Ocean at this time.

Profiles and Operations Section:

  • 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 profile lists for each field whether it is required, the required cardinality, accepted enum values if applicable, specific invariants, and any other relevant information associated with it.
    • Example: The telecom field on the Patient Resource is required, and the system, value, and use sub-fields are required, but not the rank or period sub-fields.

Ocean's FHIR Extension

  • Ocean's implementation utilizes three FHIR extensions.
    1. "http://ehealthontario.ca/fhir/StructureDefinition/ext-id-message-header" in the MessageHeader resource
    2. "http://ehealthontario.ca/fhir/StructureDefinition/ext-id-health-card-version-code" in the Patient resource
      • The first two are specified in the v0.10.0 resource profiling.
    3. "https://ocean.cognisantmd.com/svc/fhir/v1/CodeSystem/ontario-clinical-wait-time-codes" in the Appointment resource of the notify-add-appointment and notify-update-appointment messages. 
      • The third one (for wait times) has been added to meet the needs of the Ontario eServices Program.

Wait Time Calculation:

  • Ocean calculates wait times for each referral Directory Listing and displays them in the Ocean Healthmap.
  • The FHIR extension for wait times must be sent in the Appointment resource for Ocean to update the wait time accordingly.
    • Example: When an appointment date is submitted with the extension set to "wait-1", Ocean will use that date as the date of the first consultation with the health service provider in the wait time calculations.
      • The extension should be set to "wait-1a" if the appointment is the initial screening assessment rather than the actual consultation.

Response/Error Handling

  • Successful messages will return a 200 response code, indicating that 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.

Task Resource:

  • 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.

Demographic Fields:

  • 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).

Patient Addresses:

  • 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.

OAuth2 Token:

  • 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.

RefID:

  • The RefID is used by Ocean to determine which specific eReferral the payload refers to within the Ocean site.

PractionerRole Resources:

  • The bundle will contain two PractitionerRole resources, one describing the requestor and the other describing the service provider.
  • Links in the ServiceRequest/MessageHeader establish which resource is connected to each practitioner.
  • Billing number identifiers based on our Clinician data model has been integrated into our FHIR Practitioner resources within the Outbound APIs. To ensure a comprehensive solution, this update has now been extended to inbound API processing. As a result, setting billing numbers on clinician objects during the arrival of FHIR practitioners is now seamlessly supported.
  • Some Ocean referrals and consults involve another actor (e.g. medical secretary, resident) that submits the request on behalf of the clinician. In this case, there is a request authorizer and a request submitter. the FHIR payload will include a third Practitioner and PractitionerRole resource into the bundle for the submitter, (along with the authorizer and the receiver). Below are examples of how the submitter and authorizer information will be populated in the payload:
     

    MessageHeader.sender

    ServiceRequest.requester

    MessageHeader.author
    Physician Assistant PA sending referral under physician Dr. D PA Dr. D Dr. D
    Resident R sending referral under physician Dr. D R Dr. D Dr. D
    Nurse Practitioner NP sending referral (ordering an MRI) under authorizing physician Dr. Digley NP Dr. D Dr. D
    Medical Secretary MOA sending referral as a delegate under Dr. D MOA Dr. D Dr. D

Referrer ID:

  • 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.

DocumentReference:

  • 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.

Attachment Content Type:

  • According to the HL7 FHIR eReferral specification, it is not mandatory to specify the content/MIME type of an attachment to the eReferral.

  • Ocean will provide if it’s known, but receiving systems should not assume it will always be available or that it will be a specific content type (e.g. PDF), since requestors may include other attachments (e.g. images).

Retrieving Referral Summary and Attachments:

Attachment Size Limits:

  • Ocean's APIs accept attachment/file sizes of up to 10 MB per file and up to a maximum of 50 MB of attachments to a referral.
  • Ocean will send back an error response to the sending endpoint if the attachments exceed these limits.
  • Integrating systems are responsible for notifying their users if an error occurs (e.g. display a warning to the user that the attachments have exceeded acceptable limits).

Test Mode:

  • Ocean referral targets have the option of setting their directory listing (under the listing's Advanced section) to 'eReferral Test Mode'.  This signifies that all referrals set to this listing will be treated as fictitious patients.
  • To indicate that a FHIR payload corresponds to a test referral, Ocean will add the property  meta.security = HTEST to each resource in the bundle.
Data Mapping

Mandatory Demographics for eReferrals in Ocean:

      • Ocean sends the following core provider demographics for every eReferral:
  • The following demographics are mandatory in order to submit an eReferral in Ocean and shall be present in the Patient resource:
    • First Name
    • Last Name (Surname)
    • Date of Birth (DOB)
    • Address (street field)
    • City
    • One telephone-based contact field (mobile, fax, or business).

Handling Null Values:

  • Ocean does not send a 'null value' when the field has not been populated.

Gender Field:

  • The FHIR R4 standard Patient object supports the following four AdministrativeGender values for its "gender" value: "male", "female", "other", and "unknown". Consequently, Ocean uses "unknown" when the value provided in the "Sex" section is left blank, "male" and "female" when these choices are selected, and "other" when any other value is provided. Service providers may include more flexible or specific values as clinically required using the body of the service request form.

HN-Province Field and HN Identifier:

  • 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.

Entering Identifier Systems:

  • 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).

Health Service Categories:

  • The Health Service Categories that are used to identify which services are offered for each directory listing are mapped to SNOMED CT and LOINC.
  • A master list of categories and mappings is available at the bottom of this article (both PDF and .xlsx provided).

Referral Form Data:

  • 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 the following article: Guide to the eForm Editor - Add Item.) 

eReferral Lifecycle Status:

  • 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 .

Patient Resource:

  • A Patient resource that includes the patient email address must be sent within event inbound message event to Ocean in order to trigger email notifications to the patient. 
  • The Patient tab of the following support guide: Where do eConsult and/or eReferral notification emails get sent to? lists when status changes in Ocean will send an email (if received in the Patient resource).

Multiple Appointment Dates:

  • 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 add additional labels from the following values: appointment 1 - 5, consultation date, follow-up date, initial visit date, procedure date, surgery date.
  • It is strongly recommended that only these values be used in the Appointment.appointmentType.text field when creating and updating an appointment using the API messages.
  • Also, for semantic reasons, the only Ocean labels that may be used to store wait 2 are Procedure Date and Surgery Date.

Booking Status in Ocean:

  • The referral is updated to a "Booked" status in Ocean (which corresponds to the 'Booked Unconfirmed' folder in the Ocean portal) once it receives appointment data from the RMS in the 'add-notify-appointment' message event.
  • The referral can be moved directly into the 'Confirmed' status in Ocean (which corresponds to the 'Booking Confirmed' folder in the Ocean portal) if a Patient resource is referenced in the Appointment.participant.actor field and the appointment.participant.status is set to accepted . 
    • Note: If a referral moves directly from either the New or Accepted status into Booking Confirmed status, Ocean will not send an email to the patient asking them to confirm their appointment.

Patient Appointment Email Instructions:

  • Instructions for the patient appointment email notification (e.g., preparation instructions) can be included in the 'notify-add-appointment' message event Appointment.patientInstruction field.

Appointment Medium Specification:

  • The appointment medium (video, phone) can be specified in the Location.type field that is referenced by the Appointment.participant.actor field:
    • If the medium is unknown/unspecified or known to be in-person:
      Include a participant containing an actor with code "LOC", display "Clinic Location" and a reference to the listing's Location resource.
    • If the appointment is phone-based:
      Include a participant containing an actor with code "LOC", display "Phone Visit" and a reference "Location/X" to a Location with ID X in the Bundle. Set the Location's telecom to match the listing's phone number.
    • If the appointment is a home visit:
      Include a participant containing an actor with code "HH", display "Patient Location" and a reference "Location/X" to a Location with ID X in the Bundle. Set the Location's address to match the patient's address if it is available.
    • If the appointment is at an alternate location:
      Include a participant containing an actor with code "LOC", display "Alternate Clinic Location" and a reference "Location/X" to a Location with ID X in the Bundle.  The Location resource must contain an address and it's  description should match the description of the alternate location (e.g., "Alternate Clinic Visit Location: ___"   (NOTE: the example Location resource provided in the zip file at the bottom of the page will be updated to include the alternate address)

API Call for Appointment Data:

  • 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 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.

Task.status field:

  • The notify-update-status message is used to convey to Ocean the following referral status values in the Task.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. 
  • When sending the Task resource to update the status of the referral, an explanatory reason for the status change (e.g. why the referral was declined) can be added using the Task.businessStatus.text property.

External Service ID:

  • The "External Service ID" in the directory listing is used as the unique "id" for the HealthcareService. The site Admin can set the External Service ID as a unique set of digits that can be used to identify the listing in the integration.
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.
  • Update events are tracked in our audit log and will trigger an 'update' notification.  It is safe to ignore notifications with the MessageHeader.reason  = EVENT_LOGGED.
  • 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.
  • 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 Menu Admin > Integrations, opening the relevant integration setup and then saving it.
  • Ocean referral sites may offer patients a self-referral website form along with the the eReferral listing within the Ocean Healthmap.
  • If this is enabled, these self-referrals will trigger an webhook notification with a ServiceRequest bundle.
  • They can be distinguished from service provider-initiated referrals because ServiceRequest.requester will reference a Patient resource rather than a PractitionerRole resource.
  • Integrators should confirm with the sites's business stakeholders whether they want patient self-referrals to be processed in the same way as service provider-initiated referrals (e.g. can they create a new referral in the RMS Target/POS or should they only once they have been 'accepted' within the Ocean Portal).

Enabling 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 Referral System Launch

Step 1: Setting up a Webhook Endpoint

  • From the Admin Settings page, click 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 and what actions can be performed once the referral has been sent.
 

Step 2: Linking the Service Directory Listing With an Integration

  • From the Admin Settings page, click 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:

  • From the Admin Settings page, click 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.

Configuring Settings and Permissions for API Integrations

Ocean offers extensive flexibility to make updates to the referral and receive notifications throughout the referral lifecycle. These can introduce complexity to an eReferral API integration between Ocean and a downstream system. This article describes these notifications, settings and permissions so that implementers can assess which can be supported by their integration.

  • The notifications, settings and permissions are found on the Admin > Integrations > eReferral page.
  • After selecting "eReferral", the full configuration window will appear.

Integration Name

  • The integration name is used to identify the integration when binding it to a Directory Listing(s).
  • It is also used to identify the integration if the site has multiple integrations set up.

  • Note: The list of integrations also includes integration status icons. A yellow or red hexagon appearing to the right of the integration name indicates that Ocean cannot successfully communicate with the endpoint.

    Hovering over the icon with your cursor provides additional details about the error response code Ocean is receiving.

Webhook Endpoint

  • Used to specify where Ocean will send the eReferral webhook notifications as the referral is updated within the Ocean Portal.
  • If the Payload Type is set to Open API, Ocean will automatically check to see if the URL entered in this field is valid. If it is invalid, a yellow hexagon will appear.

Payload Type

Ocean offers two sets of APIs for eReferral integration - the Open APIs and HL7 FHIR APIs. This setting is used to select which API set Ocean will use in communicating with your system.  

Note: The two sets of APIs are not equivalent in terms of the events they support, the data structures or their security mechanisms. Because the FHIR APIs are standards-based and more widely adopted, implementers are advised to utilize them unless there is a specific reason to use the Open APIs, such as contextual system launch.

Contextual System Launch

  • Some referral targets require that another system be launched during or after a referral has been created.
  • The "Referral System Launch" tab in the "Enabling Ocean Integrations" article describes how to configure a referral system launch.

    Note: This feature is only available for specific workflows. Please submit a support ticket to explore if it applies to your integration.

Email Notifications

  • When eReferral updates are made within the Ocean Portal, Ocean sends email notifications. These are described in the support article "Where do eConsult and/or eReferral notification emails get sent to?".
  • By default, updates made via the APIs will not trigger email notifications to the referral participant(s). If they are enabled, Ocean will send an email notification to the appropriate participant(s).

Submission Settings

  • By default, all referral forms include an "Add Attachment" button to upload files.
  • Enabling the "Prevent referral senders from including attachments" checkbox hides the button on any referrals initiated to listings setup with that integration. It is useful if the downstream system does not want to store or manage attachments.

Permissions

Expand each setting below for additional information regarding the functionality.

Make the following status updates in Ocean: Accept, Split, Complete, Mark Incomplete, Accept Reply, Cancel
  • By default, a site with API integration will have the action buttons related to these status updates hidden within the referral page.
  • These status updates are similar to the ones supported by the APIs, so the site needs to determine whether they want them enabled so that Ocean users can also manage the referral within the Ocean Portal.
Send messages from the eReferral record page
  • Messaging within the eReferral allows the sender and receiver to communicate about the referral. For instance, the receiver may request additional information before accepting the referral or the sender might inquire about the treatment from the receiver.
  • Ocean by default disables the messaging pane for senders and recipients, so they do not have access to type or send messages on referrals sent to a listing setup with an API integration.
  • This permission should be enabled if the integration supports messaging or messaging does not need to stored as part of the referral in the downstream system. Whether or not it is enabled, messages can still be sent via the API integration.
Add Attachments to messages in the eReferral record page
  • Some sites with an API integration that support messaging do not support storing and managing attachments.
  • By default, the 'Add Attachment' feature is hidden unless this is enabled, which prevents Portal users from adding attachments to a message.
Add Notes on the eReferral record page
  • Ocean users are able to add notes to the referral that assist other users in understanding how the referral is being processed.
  • When an API integration is in place, this feature is disabled by default. The downstream system may support a Notes feature internally or does not wish to receive updates related to the notes.
Update patient demographics in the eReferral record page
  • The patient demographics can be updated within the Ocean Portal after the referral is initially sent. This can add complexity for an integrated downstream system to support in terms of records management (patient merge/unmerge scenarios).
  • By default, the update feature is hidden for referrals associated with a directory listing that has an API integration, which hides the edit button beside the patient demographics for senders and recipients, so they do not have access to editing demographics on referrals sent to a listing setup with that integration.
Cancel the referral
  • Referral senders can cancel the referral within the Ocean Portal (e.g. patient no longer needs the service). This feature is disabled for sites with an API integration because it adds complexity to the referral management in the integrated downstream system.
  • If enabled, Ocean will send an webhook notification when the referral has been cancelled in the Portal.
Forward the referral to another site in the Ocean Portal
  • Referrals can be forwarded from one Ocean site to another. For example, a Central Intake site will forward a referral to a service provider.
  • This feature is disabled by default (the “Forward” option is hidden in the Action Menu for receivers) for sites with an API integration, because it adds complexity to the referral management in the integrated downstream system.
  • When enabled, receivers can manually forward the referral within the Ocean Portal; there is currently no API support for forwarding. (Note: Senders cannot forward referrals.)
Update the referral form summary
  • The referral form summary section contains the contents of the referral form that was submitted by the sender.
  • By default, when an API integration is present, Ocean hides the edit button beside the Referral Form Summary for senders, so they do not have access to editing the form on referrals sent to a listing setup with that integration.
  • When enabled, Ocean will send updates of the referral payload via the API each time the referral form summary has been updated.

API Behaviour

Allow a copy of the referral to be sent to this endpoint when a new referral is sent from this site

When a referral is sent from a site that has an API integration and the "Post a copy of the referral (all integrations) and all subsequent status updates (FHIR v0.11 only) to this endpoint when a new referral is sent from this site" setting is enabled, Ocean will send a copy of the referral to the sender system (This is the FHIR notify-add-service-request message event and the Open API notify-upstream-service-request message event).

This eliminates the need for the sender to manually copy and paste or download a PDF of the referral summary into their system.

Integrations utilizing FHIR v11 will get all subsequent upstream status updates (including appointments, and communications) to this endpoint when a new referral is sent from this site.

Use this integration for API-created directory listings

This option applies the selected integration as the default endpoint for listings that are created using the HealthcareService API. It does not apply to manually created listings.

When API Messages Fail: Ocean’s API Retry Logic and Troubleshooting

What It Is

While there are many advantages to RESTful APIs, one downside is that if a call is unsuccessful, there is by default no memory of the failed attempt. For system-system API integrations, particularly in healthcare, this can be dangerous in that it could lead to information loss and process disruptions between systems.

To address this issue, Ocean has a built-in automated retry capability for all direct Open and FHIR-based Ocean API integrations. This Ocean service will resend any webhook notifications that do not receive a 20X-class (e.g 200, 201) status response code once per hour for up to four days.

How It Works

This service will be operated from the Ocean Cloud Connect module. Cloud Connect manages a queue of all webhook notifications that are funneled through it until they are successful or time-out.

  • Successful calls are removed from the queue.
    • The first unsuccessful API call will trigger an email alert containing the name of integration and error message encountered by Ocean, which will be sent by email to the Ocean Site's 'Clinical Administrator / Ocean Support Contact' email address specified in the Site Account settings.
    • Ocean will retry the call to the endpoint several times in the first hour. If unsuccessful, Ocean will try once an hour.
    • Every 24 hours, Ocean will send an email alert to the 'Clinical Administrator / Ocean Support Contact' to update them that the issues are still not resolved.
    • If the integration subsequently accepts a message from Ocean or if its settings are resaved, it will cease to appear in the daily email alert.
    • After 96 hours, Ocean will abort attempts to reach the endpoint and will send a final email alert stating that the maximum number of retries has been reached.

What You Need To Do

  • Ensure that the email address(es) of the individual(s) most responsible for the integration is/are included in the Ocean Site's 'Clinical Administrator / Ocean Support Contact' field. This may be the clinic's IT manager and/or vendor's point of contact; They do not have to be a user on the Ocean Site.
    • Multiple email addresses can be specified in the field - simply separate each email address using a comma.
  • When an email alert is received from Ocean, it generally indicates an issue with the receiving system's endpoint, not with Ocean. The first step to take is investigate the health of the receiving system's endpoint prior to reaching out to the OceanMD Support team.
  • Common issues encountered include:
    • Expired certificates.
    • Unplanned system downtime.
    • The receiving system's endpoint is unsure of how to process the message it has received.
  • If assistance is needed or it appears to be an Ocean-related issue, please submit an incident report to the OceanMD Support Team. In your report, be sure to include:
    • Ocean Site Number
    • Ocean Environment (i.e., test.cognisantmd.com, staging.cognisantmd.com, or ocean.cognisantmd.com)
    • A description of the investigation performed to date to assess any issues with the receiving endpoint.
    • A complete screenshot of the Ocean email alert.

FHIR Patient Engagement Integration Setup Guide

Patient engagement tools such as Online Booking, Patient Messaging, Patient Reminders, Website Forms, Kiosk and Tablet use, including form completions can be integrated with your EMR using the FHIR API integration. 

Pre-requirements for Integration

Setting up Patient Engagement Integration with Ocean

These steps include the preliminary steps required to set up your Ocean site for patient engagement integration with an EMR.

  1. Complete the New Integrators registration survey
  2. Email Ocean Support with the email domain that you will be using during technical development and testing (e.g. to register new users, login to the Ocean portal, etc.). 
  3. Once Ocean confirms that Step 2 is complete, create an Ocean user account and site in test.cognisantmd.com
  4. Generate the site's Shared Encryption Key (SEK)
  5. From the Menu, select Admin and then select Site Features. Activate the 'Enable Ocean Cloud Connect' option. This will trigger a dialog instructing you to set up Cloud Connect. Select the 'Go to Cloud Connect' button.
  6. In Cloud Connect, select 'Integrate my EMR'. Enter the site's SEK and select 'Save and Continue'
  7. Select 'FHIR-Based EMR' as the EMR type you are integrating with
  8. Enter your FHIR-Based EMR Credentials - This step has some pre-requirements which are outlined in the High-Level Requirements section 
  9. Once requirements are completed, select 'Connect to FHIR EMR'. If successful, a "You have successfully authenticated with a FHIR EMR!" message will pop up, 'Save and Continue'
  10. Configure your Cloud Connect settings by specifying (1) how many schedule days to sync, (2) which providers to sync for, and (3) any walk in provider configuration (These configurations are explained in this article). Click 'Save'. 
  11. The Cloud Connect configuration is now complete. 
  12. Login to your Ocean Portal using your Ocean user account credentials
  13. Open the 'Menu' in the top left corner and click 'Admin', navigate to 'Site Features' under Additional Functionality
  14. Enable the 'Enable Ocean Cloud Connect' checkbox if not already enabled. 

You have now successfully set up your Ocean Portal for patient engagement integration!

 

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.
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.
  • Be capable of launching a modern web browser (either embedded or via a desktop app linkage).
  • Ensure that the system's users have access to at least one configurable launch URL for Ocean. These URLs should accommodate variable path names based on factors such as the Ocean site, the intended Ocean action, and other relevant parameters.
    • A full list of 'action' parameters for SMART launching into Ocean can be found in the SMART on FHIR Implementation Guidance article.
    • 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=dashboard

Systems should also:

  • Provide the Base64-encoded value for the Ocean site's Shared Encryption Key as the value for an "oceanSharedEncryptionKey" attribute in the SMART launch access token.
    • This parameter eliminates the need for users to manually input their site's Shared Encryption Key in their web browser for each contextual launch. While it can be omitted if a clinic pre-configures user web browsers by storing the Shared Encryption Key in the browser's "localStorage," it is usually mandatory. Hospital-based browsers often do not retain localStorage across user sessions due to privacy considerations.
    • More information on SMART launch providers is provided here
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.
  • Ocean reads this patient information, with permission from the EHR, by requesting "scopes" to read data from the EHR's FHIR endpoints.
  • 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.
Integration Requirements for Patient-Contextual Launch in Ocean Systems

In addition, to support patient-contextual launch, systems must adhere to the following requirements:

  • Support FHIR R4 for Patient.read Endpoint:
    • Integration should include support for the Patient.read endpoint as part of the SMART App Launch context, following FHIR R4 standards.
  • Include "patient" Parameter in SMART Launch Acess Token:
    • Ensure the provision of a "patient" parameter in the SMART launch access token to enable seamless patient-contextual launches.
  • Adherence to FHIR Conventions for PHI Storage:
    • Adhere to established FHIR conventions for the storage of relevant PHI used by Ocean. This includes the use of "JHN" Health Number identifier and Version Code identifier for Ontario patients.
  • Optional: Support FHIR R4 /Patient/[id]/$everything Operation:
    • Optionally support the FHIR R4 /[/Patient/[id]/$everything operation to pre-populate medications, allergies, medical history, and chart attachments.
Sequence of Events for Users
    1. A user is signed into the EHR system.
    2. The user clicks on an "Ocean" launch button in the EHR's UI.
    3. 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).
    4. 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 current patient.
      • Ocean checks whether the EHR user has already been linked to an Ocean account.
    5. If the user has not yet linked their EHR account to Ocean, a sign-in prompt is shown:
    6. Once the account is linked, from that point onwards the single sign-on is automatic.
    7. Next, if a patient was specified, Ocean asks the EHR for information about the current patient (using the EHR's FHIR APIs).
    8. 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 (a PDF file is available at the bottom of this article).

Allowlisting

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

Please send the following values to the Ocean Support email 'support@oceanmd.com' so that we can create the allowlist entry for your launch system:

  1. The Server URL:
    • Provided as the initial "iss" parameter during the SMART launch. This value should also correspond to the FHIR API server.
  2. Client ID:
    • The unique unguessable "client_id" for Ocean, as randonly 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.)
  3. Authorization Endpoint:
    • The OAuth 2.0 "/authorize" endpoint.
  4. Token Endpoint:
    • the OAuth 2.0 "/token" endpoint.
  5. Token Issuer URL:
    • The "iss" value proivided within the signed JWT claims set, within the id_token value of the authorization token.
  6. The URL and the response body for the publicly-accessible ".../.well-known/smart-configuration" (if supported).
  7. The URL and the response body for the publicly-accessible ".../.well-known/openid-configuration".

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.)

SMART on FHIR Implementation Guidance

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

Open eReferral API Implementation Guidance

Ocean eReferral Open API Deprecation

As of November 3rd, 2022 the Ocean eReferral Open API is deprecated. Third-party systems that are developing new integrations with Ocean eRequests (eReferral and eConsults) should use Ocean's FHIR APIs.

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. 

  • 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.
  • ***When retrieving a referral, it is recommended to use the oneTimeKeyEncryptedWithSitePublicKey": field (rather than the oneTimeKeyEncryptedWithTargetPublicKey" field) so that your system can also decrypt referrals that are sent by your clients' Ocean sites (and not just those that are received by it).  See the "API Behaviour" section of this article for more information about receiving a copy of sent referrals. 

 

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.  

blobid0.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.
  • Ocean will flag place a referral into the 'Needs Review' folder when a recipient has a new message sent to them (e.g. referral recipient sends a message within the referral to the sender with patient care instructions).   When a message is sent using the 'Add a Message' endpoint (URL below), the TargetSiteNum must be populated with the site number of the provider that should review the message in order for it to be 'flagged' for inclusion in the Needs Review folder. 

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