HL7 FHIR eReferral API Implementation Guidance

 

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

• 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 that are not supported by Ocean at this time.  
• 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 implementation utilizes three FHIR extensions.  The first two are specified in the v0.10.0 resource profiling, but the third one (for wait times) has been added to meet the needs of the Ontario eServices Program:
  • "http://ehealthontario.ca/fhir/StructureDefinition/ext-id-message-header" in the MessageHeader resource
  • "http://ehealthontario.ca/fhir/StructureDefinition/ext-id-health-card-version-code" in the Patient resource
  • 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. 
• Ocean calculates wait times for each referral directory listing and displays these in the Ocean Healthmap.  The FHIR extension for wait times must be sent in the Appointment resource in order for Ocean to update the wait time accordingly.   For instance:
  • 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" the appointment is the initial screening assessment rather than the actual consultation.
• 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.

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

• Even if Ocean has the patient's email address in the initial referral, Ocean will only send a patient email notification (i.e. with the appointment date) if it receives an email address in the Patient resource of the inbound notify-add-appointment message sent to Ocean.
• There are two methods for retrieving the referral summary and original attachments from Ocean:
  1. The referral summary can be retrieved the endpoint described below: https://ocean.cognisantmd.com/public/fhirApiDocs.html#operation/referralReferenceLetter_1 and individual attachments can be retrieved from the endpoint described below: https://ocean.cognisantmd.com/public/fhirApiDocs.html#operation/documentReferenceBinary_1
  2.  A consolidated PDF with the referral summary and all attachments can be retrieved by appending  "?attachments=true" to the referral summary endpoint  https://ocean.cognisantmd.com/public/fhirApiDocs.html#operation/referralReferenceLetter_1
• 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).   
• 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

• Ocean sends the following core patient and 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, and at least one telephone-based contact field (mobile, fax, or business).  All other fields are optional.
• Ocean does not send a 'null value' when field has not been populated.
• Ocean is only capable of sending [Male, Female, Unknown] 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 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).
• 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 . 

• 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 support article describing Email Notification Rules lists when status changes Ocean will send an email (if received in the Patient resource).  
• 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.  It is strongly recommended that only these values be used when creating and updating an appointment using the API messages. 

• The referral is updated to a "Booked" status in Ocean (which corresponds to the 'Booking Unconfirmed' folder in the Ocean portal) once it receives appointment data from the Third-Party System 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.  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.
• Instructions can be included in the patient appointment email notification (e.g. preparation instructions, early arrival required) by including them in the 'notify-add-appointment' message event Appointment.patientInstruction field.
• 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)
• In all cases, use "http://terminology.hl7.org/CodeSystem/v3-ActCode" for the actor coding system. The code should be either "LOC" or "VR" or "HH". Ensure that any referenced Location objects are in the Bundle and referenced with a unique identifier within the Bundle.  
  • Examples for each of these are provided in the zip file at bottom of this article.

• 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 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. 
• Once a referral is in the "Completed" or "Canceled" referral status, it cannot revert to another referral status via the API.
• The "External Service ID" in the directory listing is used as the unique identifier for the Ocean service. 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.
• ***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

 

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