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