The Referral Scheduling module adds a full solution for walking a patient through scheduling an appointment with an appropriate provider for the medical service they were referred to.

Dependencies

The Referral Scheduling module is dependent on the following modules:

• Project Context

• Utilities

• Settings

• Error Handling

• Flow Manager

• Chatbot

• Provider Service

• Location Service

• Patient Service

• Order Service

Configuration

The Referral Scheduling module will read and respect the values shown below. To add or edit configuration values follow this path: Experience Manager > Create tab > Content component > Settings item > referralScheduling section.

• chatbotSettingsKey (string): The key of the chatbot settings to use when the Referral Scheduling page is rendered (see Endpoints).

• disableKeyboard (boolean): Whether or not keyboard input should be disabled

• verification (object): Container for verification settings

  • dob (boolean): Whether or not to verify the patient’s date of birth

• maximumResults (number): The maximum number of results to display. If not specified there will be no limit on the number of results returned.

• appointmentTypes (array): An array of appointment type options each with the following properties:

  • label (string): The display label for the appointment type, used in content and on the selection button

  • description (string, optional): A description of the appointment type

  • schedulingId (string): The id for this appointment type in whatever system has been integrated with for scheduling

  • virtualVisit (boolean, optional, default = false): Whether or not this is a virtual visit type.

• sort (array): An array of sort properties for any provider searches, where each entry is an object with a single property, where the key is the sort property name, and the value is a sort direction of either “asc” or “desc”.

• ageFilter (boolean): Whether or not to automatically filter by patient age (if available)

• distance (string): The distance to search within. Should be in the format “XXmi”. If not specified (or invalid), a default of “50mi” will be used.

• content (object): Container for content settings

  • schedulingPhoneNumber (string): The scheduling phone number (offered in certain content)

  • healthSystem (string): The health system name (used in certain content)

  • repeatHealthSystem (string, optional): If filled out, will lead to the health system name being repeated in certain contexts, such as before references to the target service.

  • insuranceReminder (boolean): Whether or not to include a reminder to verify that a chosen provider will take the patient’s insurance before scheduling.

  • includeReferringProvider (boolean): Whether or not to include the referring provider’s name in content (if available in the referral data).

  • includeReferringLocation (boolean): Whether or not to include the referring location name in content (if available in the referral data).

  • dobVerificationPhrase (string): A string of content to override the default date of birth verification input phrase.

  • nameVerificationPhrase (string): A string of content to override the default name verification input phrase.

  • zipCodeTerm (string): The term to use in content when referring to a zip code (otherwise the default of “zip code” will be used.

  • providerTerm (string): The term to use in content when referring to a provider (otherwise the default of “provider” will be used. The term should be something that can be pluralized by adding an “s” to the end.

  • onlineManagementReminder (boolean): Whether or not to include a reminder about online appointment management in the sign-off content.

  • patientPortal (object): A container for settings for the patient portal link:

    • text (string): The text for the patient portal link.

    • url (string): The url for the patient portal link.

  • patientPortalServices (array): An array of patient portal services to include in the online management reminder content.

  • overrides (object): A container for content overrides.

    • targetService (object): A container for target service flow content overrides.

      • locationOnly (string): An override for the initial content in the target service flow when only the referring location data is available (and configured to be used).

      • providerOnly (string): An override for the initial content in the target service flow when only the referring provider data is available (and configured to be used).

      • neither (string): An override for the initial content in the target service flow when neither referring provider or location information is available (or neither is configured to be used).

      • both (string): An override for the initial content in the target service flow when both referring provider and location information is available (and both are configured to be used).

The following tokens can be used in content overrides and custom phrases:

• {{patient.firstName}}

• {{patient.lastName}}

• {{contentSettings.healthSystem}}

• {{contentSettings.repeatHealthSystem}}

• {{contentSettings.providerTerm.singular}}

• {{contentSettings.providerTerm.plural}}

• {{contentSettings.providerTerm.capitalized}}

• {{referral.referringProvider.fullName}}

• {{referral.referringLocation.name}}

• {{referral.targetService}}

An example of JSON for the above settings:

Intermediary Models

The following intermediary models are used internally by the solution code, and are exposed under referralScheduling.models in the project context for convenience when writing custom handlers.

Referral

This serves as a simpler form of only referral-specific data from an order. The intermediary referral model is:

• id (string): The Orbita ID of the order record

• referringProviderId (string): originProviderId from the order record

• referringProvider (object): null by default, to be populated by the loadReferralData handler

• referringLocationId (string): originLocationId from the order record

• referringLocation (object): null by default, to be populated by the loadReferralData handler

• targetService (string): referral.targetService from the order record, falling back to referralTargetService from the order record

• targetProviderId (string): referral.targetProviderId from the order record

• targetProvider (object): null by default, to be populated by the loadReferralData handler

• targetProviderName (string): referral.targetProviderName from the order record

• targetProviderPhone (string): referral.targetProviderPhone from the order record

• reasonCode (string): referral.reasonCode from the order record

• customData (object): customData from the order record

Appointment Slot

This serves as a formatted version of appointment slot data that gets submitted when an appointment slot button is clicked in the UI. The intermediary appointment slot model is:

• provider (object): The provider data (determined by the getAppointmentSlots handler).

• location (object): The location data (determined by the getAppointmentSlots handler).

• id (string): The id of the appointment slot (determined by the getAppointmentSlots handler).

• date (string): The date portion of the submitted datetime, formatted as “M/D/YYYY”.

• time (string): The time portion of the submitted datetime, formatted as “h:mm A”

Flow Studio Flows

Verification

This is the initial flow the user is brought into as part of the experience. It verifies that the link is still considered active for the user, performs the necessary and configured identity verification, and redirects the user to either the Target Provider or Target Service flow based on the determined referral type.

Target Provider

This flow is used when the referral is considered a target provider referral, with initial dialogue and referral confirmation specific to that context, and varying depending on the available referral data and content configuration settings. It will then confirm if the user wants assistance scheduling an appointment, allow the option to specify a different zip code from the one in their record, and perform the search for relevant providers, displaying an appropriate message if no results are found, or moving them on to the Schedule Appointment flow otherwise.

Target Service

This flow is used for target service referrals, with initial dialogue and referral confirmation similar in some regards to the Target Provider flow, but without reference to a target provider. It confirms that the user wants assistance scheduling an appointment, offers up the same zip code input option, and performs the search for relevant providers, directing them to the Schedule Appointment flow if results are found or displaying a message if there were no results.

Schedule Appointment

This flow delivers a reminder for the patient to confirm their insurance is accepted (if configured), displays the carousel of results, handles filtering by the user of those results, confirms the appointment that the user selected, returning them to the carousel if they do not confirm or submitting a request to book that appointment when they do confirm. It will end with a sign off message telling the user to look out for further communication about the appointment.

Handlers

isLinkActive

This handler is called to determine if a referral link is still active for a patient.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

Returns: A promise that resolves with a boolean indicating if the link is still active for the particular patient.

The default implementation of this handler always returns true.

loadReferralData

This handler is called to load referral data from a particular order.

Parameters:

• order (object): The order data (see Order intermediary model).

Returns: A promise that resolves with the referral data derived from the order (see Referral intermediary model).

The default implementation of this handler attempts to load the following fields from the referenced ID fields (using the appropriate service) on the assumption that the ID is that of an Orbita record:

• referringProvider: referringProviderId

• referringLocation: referringLocationId

• targetProvider: targetProviderId

dobValidationFailed

This handler is called when a patient fails to verify their date of birth twice.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

Returns: Nothing.

The default implementation of this handler does nothing.

nameValidationFailed

This handler is called when a patient indicates they are not the named patient.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

Returns: Nothing.

The default implementation of this handler does nothing.

getReferralType

This handler is called to determine if the current referral is for a target service, or a target provider.

Parameters:

• referral (object): The referral data (see Referral intermediary model).

Returns: A promise that results with “provider” if the referral is determined to be a target provider referral, “service” otherwise.

The default implementation will return “provider” if referral.targetProviderName or referral.targetProvider is available in the referral data, and “service” otherwise.

selfScheduled

This handler is called when a patient answers the question as to whether or not they have already scheduled an appointment.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• didSelfSchedule (boolean): True if the patient has indicated that they already self scheduled. False otherwise.

Returns: Nothing.

The default implementation of this handler does nothing.

zipCodeValidationFailed

This handler is called if a patient enters an invalid zip code twice.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

Returns: Nothing.

The default implementation of this handler does nothing.

getAppointmentSlots

This handler is called to retrieve available appointment slots for a particular provider, at a particular location, for a certain timeframe.

Parameters:

• projectId (string): The Orbita project ID

• locationName (string): The name of the currently selected location

• providerId (string): The ID of the provider record

• start (string): The start date formatted as “MM-DD-YYYY”

• end (string): The end date formatted as “MM-DD-YYYY”. Only passed for the scope “month”.

• days (number): The number of days to return appointment slots from. Only passed for the scope “next”.

• timezone (string): The relevant timezone.

• scope (string): “next” for next available appointments, “month” for appointments for a month, “day” for appointments for a specific day.

• type (string): The appointment type ID

• patientId (string): The ID of the current patient

Returns: A promise that resolves with available timeslots, formatted in one of the following manners depending on scope:

• next: An array of results in the following format:

  • date (string): Formatted as “MM/DD/YYYY”

  • timeslots (array): An array of timeslot strings in the format "h:mm AM/PM"

  • slotId (string): A stringified JSON object containing the following properties:

    • locationName (string): The name of the currently selected location.

    • providerId (string): The ID of the provider record

  • data (object):

    • _source (object):

      • location (object): Location data to pass when submitting the appointment request

      • provider (object): Provider data to pass when submitting the appointment request

      • idMapping (object): An object mapping with the timeslot (in the format “h:mm AM/PM”) as the key, and the appointment ID as the value.

• month: An object with the following properties:

  • disableDates (array): An array of date strings in the format “MM-DD-YYYY” to disable on the calendar:

  • availableDateDatas (array): An array of available appointment slot data in the following format:

    • date (string): The date, in the format “MM-DD-YYYY”

    • _id (string): A stringified JSON object containing the following properties:

      • locationName (string): The name of the currently selected location.

      • providerId (string): The ID of the provider record

• day: An array of results in the following format:

  • displayName (string): The timeslot in the format "h:mm AM/PM"

  • dateTime (string): The date in the format “MM-DD-YYYY”

  • data (object):

    • location (object): Location data to pass when submitting the appointment request

    • provider (object): Provider data to pass when submitting the appointment request

    • id (string): The ID of the appointment slot

The default implementation of this handler serves up dummy appointment slots (with no IDs) that will submit the provider and location data used to populate the cards for the purposes of populating the UI and allowing testing.

noProvidersFound

This handler is called when no providers are found to present to the patient.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

Returns: Nothing.

The default implementation of this handler does nothing.

submitAppointmentRequest

This handler is called when a patient has selected an appointment slot and confirmed that they would like to request it.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• appointmentSlot (object): The appointment slot data (see Appointment Slot intermediary model).

• appointmentTypeId (string): The appointment type ID, if available.

• isVirtualVisit (boolean): Whether or not the appointment is a virtual visit.

Returns: A promise that resolves with an object with the following properties:

• success (boolean): True if the submission of the appointment request was successful, false otherwise

• confirmation (object): Any confirmation data that would be useful for the appointmentSuccess handler

The default implementation of this handler returns true for testing purposes, with no confirmation data.

appointmentSuccess

This handler is called when submitAppointmentRequest returns true.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• appointmentSlot (object): The appointment slot data (see Appointment Slot intermediary model).

• confirmation (object): Any confirmation data passed along by the submitAppointmentRequest handler.

• isVirtualVisit (boolean): Whether or not the appointment is a virtual visit.

Returns: Nothing.

The default implementation of this handler does nothing.

appointmentFailure

This handler is called when submitAppointmentRequest returns false.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• appointmentSlot (object): The appointment slot data (see Appointment Slot intermediary model).

Returns: Nothing.

The default implementation of this handler does nothing.

zipUpdated

This handler is called when the user answers the question as to whether or not they want to specify an alternate zip code to search in.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• updatedZip (string): The alternate zip code the user specified. Null if the user did not want to change the search zip code.

• requestedUpdate (boolean): True if the patient requested to specify a different zip code. False otherwise.

Returns: Nothing.

The default implementation of this handler does nothing.

filtersApplied

This handler is called when the user applies filters to the results in the provider carousel.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• filters (object): The applied filter data.

Returns: Nothing.

The default implementation of this handler does nothing.

selectedAppointmentType

This handler is called when an appointment type has been selected.

Parameters:

• patient (object): The patient data (see Patient intermediary model).

• referral (object): The referral data (see Referral intermediary model).

• appointmentType (object): The appointment type.

Returns: Nothing.

The default implementation of this handler does nothing.

Overriding Handlers

Any of the above handlers can be overridden with a custom version by using the registerHandler method exposed by the Referral Scheduling module. For example:

Your custom handler can accept any of the documented parameters and there is an expectation that it will return an appropriate value for handlers expected to return something.

Endpoints

The Referral Scheduling solution establishes the following endpoints:

[GET] /oeapi/[Hyphenated Project Name]/referral-scheduling/:channel/:token

This endpoint will render a page using the chatbot settings defined in the settings (or a default of the “outreach” chatbot settings included with the Chatbot module) that brings the user directly into the Verification flow.

The channel will be passed along in custom data based on the following mapping:

• e: “email”

• s: “sms”

• [any other values]: null

[GET] /oeapi/[Hyphenated Project Name]/referral-scheduling/:token

This endpoint serves the same purpose as the above endpoint, but covers cases where there is no channel to specify. The channel will come through as null in the custom data.

[GET/POST] /oeapi/[Project ID]/getAppointmentSlots/:scope/:patientId

These endpoints serve requests made by the provider carousel to get available appointments for a particular provider in several different UI contexts.

Allowed scopes are:

• next: Intended for getting the next available appointments for a provider from the next X (default 3) days that they have appointments.

• month: Intended for getting all available appointments for the provider for a particular month.

• day: Intended for getting all available appointments for the provider on a particular day.

Depending on the scope, appropriate parameters will be passed to the getAppointmentSlots handler which is responsible for retrieving slots and formatting them in an appropriate manner based on the scope.

Specifying an unknown scope will result in a 400 error.

[GET/POST] /oeapi/[Project ID]/getAppointmentSlotsByType/:type/:scope/:patientId

These endpoints serve the same purpose as the above endpoints, but with an extra parameter for the appointment type ID that will get passed through to the getAppointmentSlots handler when available.

Context

A context to limit provider results to only a subset of the Blaze data on an environment can be set in session at msg.orbita.session.modules.referralScheduling.context.

It can be either a string or an array of strings. If set, an additional filter will be applied on the backend to all request to limit results to only those provider records with a value set at customData.context that matches the context set in session.