Tips and Tricks

Relationship between Referral Form and QuestionnaireResponse Resource

The Ocean eReferral forms (eForms) are used to collect and transmit Patient’s health information to the appropriate recipient. They can be assigned to a directory listing to be used to collect information that a referral receiver might need, and once these form answers are collected in Ocean, they are sent to the receiving EMR system via the FHIR APIs in the payloads. The section of the payload which typically contains the collected form data is the QuestionnaireResponse resource. Every question-and-answer present in the eForm is found in this section, regardless of if it was answered or not. Each form item ID is presented as the linkID element which is related to the itemreference value assigned to the eForm question/section during the form building process. More information on building out eForms can be found in this article. The text of the question is presented as a text element, and the response to the question is presented as an answer.valueString element in the payload. Questions that have not been answered will be typically missing an answer element id, and questions which are hidden are presented with an extension which is explained in the next section.

Therefore, with this structure, it is possible to map the eForm itemreferences (linkIDs) as discrete data elements to sections in your EMRs to better populate the answers provided by the sending physician in your EMR and reduce the manual entry time and errors.

Hidden Fields

As previously stated, during the referral sending process, listings typically have forms that they require the referral sender to complete before sending the referral to the destination listing. These forms questions and answers are presented in the QuestionnaireResponse resource in the payload, with each form item ID presented as the linkID element, the text of the question presented as a text element, and the response to the question presented as an answer.valueString element.

In some cases, there are collapsible form sections which are hidden but then unhidden by the answering of another form question; and senders might have initially responded to a hidden form item and subsequently retracted this answer by hiding the section again without clearing out their answers. In such cases, Ocean will not with-hold the initial answer from the QuestionnaireResponse resource. However, we will present an extension in the QuestionnaireResponse element that will indicate each form item response that has been hidden, including the retracted responses. The valueString property will always be set to '"hidden" for this extension, and the extension.url will be https://ocean.cognisantmd.com/svc/v1/Structure-Definition/ext-ocean-eform-item-visibility

Response Handling

When Ocean sends payload messages to an endpoint, Ocean is expecting to receive a 20X-class (i.e. 200, 201) status response code for that message that was sent. It’s important to note that Ocean is “chatty”, therefore, Ocean will send messages for every action that is taken on a referral. Additionally, even when the receiving system sends updates to Ocean on a referral, Ocean will also send a message (notify-update-service-request) to that receiving system’s endpoint informing them of the change that was just made to the referral. Therefore, while most of these messages can be ignored, Ocean still expected a 20X-class message response for each message event sent. Any other message response sent will trigger a “failed message delivery” in Ocean which will start the retry framework process.

Retry Framework

When the API messages fail to send from Ocean to the integrated endpoint, Ocean embarks on a process to retry the messages for a period of time which is referred to as the Retry Framework. The retry framework consists of Ocean attempting to retry the message sent once per hour for up to 96hours. Additionally, during this time, Ocean will send daily emails to the Site’s Clinical Administrator/Ocean Support Contact informing them of this message failure. More information can be found in this article.

External Service ID

When vendors are using a single endpoint to route referrals for multiple sites/listings (multi-tenant approach), the External Service ID can be utilized to differentiate and identify which listing the payloads are being sent to, regardless of endpoints. This will be identified as the following extension in the payload: https://test.cognisantmd.com/svc/fhir/v1/NamingSystem/id-referral-target-external-service and present in the receiving PractitionerRole.identifier.value and MessageHeader.destination.receiver.value. Here is an example:

Bulk/Individual Referral Retry Action

The bulk retry action allows users the ability to resend referrals to their endpoint either as a new referral (add-service-request) or as an updated referral (notify-update-service-request). This feature is especially useful in the case where a directory listing was already accepting eReferrals prior to an integration being added to that listing. In this scenario, the previously sent eReferrals can be sent to the newly integrated listing’s endpoint and subsequently the EMR by using this bulk retry action. Additionally, this feature can also be used in cases where an EMR integration is down for more than 4 days – surpassing the retry framework period. In this case, once the integration gets back up and running, the eReferrals which have completed their retry period can still be resent to the endpoint, preserving the eReferral information and preventing the data from being lost. Here’s some additional information on this feature:

  • It can be found in the Admin > Integration > On the integration endpoint (Bulk Actions)
  • To use this feature, a csv file containing a list of all the affected eReferrals’ referral reference ID needs to be uploaded.
    • This list can be obtained from the referral analytics report
  • There is currently a limit of 1000 referralRefs per csv file (per one time).
  • The referrals are sent sequentially to the endpoint and spread out by 15s.
  • The add-service-request ServiceRequest will contain the original date that the referral was received so that the chronological order is maintained.
  • Any information sent on the referral prior to the message being sent via the integration will be included in the add-service-request and notify-update-service-request messages.
  • A report is generated at the end of the upload, indicating which referrals were successfully processed.

The Event Log

The event log for each referral is an important tool that enables users confirm and understand if and when the referral was updated. This can be accessed by opening the referral record and selecting 'View Event Log' from the top right 'Action' menu.