HL7 FHIR eReferral API Implementation Guidance

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

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.

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:

• 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

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.

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 field has not been populated.

Gender Field:

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

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 when creating and updating an appointment using the API messages. 

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. 
• Once a referral is in the "Completed" or "Canceled" referral status, it cannot revert to another referral status via the API.
• 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 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.

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

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