Online Booking

Online Booking (OAB) uses the following FHIR Resources:

  • Slot
  • Appointment
  • Practitioner
  • Schedule
  • Patient
  • DocumentReference
  • ValueSet
  • AppointmentResponse
  • Optional: Observation, QuestionnaireResponse

The following section walks through the various FHIR connections made as part of a standard online booking workflow. These connections can serve as a starting point for your own implementation.

Ensure you have read the Getting Started section prior to implementation. Of particular note: you will not be able to access the Online Booking app in the Ocean portal until you have configured Cloud Connect.

You should also refer to Ocean's Online Booking Setup Guide for important context on how users configure their sites and their EMR/EHR with Ocean to enable online booking.

Sequence of Connections With FHIR Resources

0. Online Booking Configuration Queries

In order for end users to configure their clinic's online booking options, Ocean first needs to read some metadata from the server, to determine which providers, schedules, appointment types, and so on are used by the clinic. These values are read as part of a regular "synchronization", which is done when it is first connected in Cloud Connect and then automatically every half hour. You can also request an immediate synchronization in the Cloud Connect portal.

The following endpoints are called in particular:

Check the Profiles in this implementation guide for more information about each endpoint operation.

After a successful synchronization, you should be able to activate and configure bookable schedules inside Ocean's Online Booking app within the portal. Proceed to set up at least one schedule and one booking link for testing purposes.

1. Patient Check-in via ID

If you have succesfully configured a booking link, open it in an incognito/private browsing window to test it. Enter a test patient's information, particularly the name, birth date, and health number, and click Check-In.

Cloud Connect will proceed to search for a patient using the following Patient endpoint query:

  • GET Patient?identifier={id}
    • The id is the health number entered for the patient, or some other supported patient-unique identifier such as a student number.
    • This call expects to receive a Bundle of matching patients.

If no match is found, the patient or caregiver is presented with an appropriate message. Clinics may configure Ocean's to either block or allow bookings for these patients who have no active record within the integrated system. For example, walk-in clinics may choose to allow the patient to proceed here as a new patient, despite the lack of an existing Patient record. Otherwise, the patient is blocked from proceeding and advised to contact reception.

If multiple matches are found, the patient is also presented with an error. Ocean insists that the identifier match be unique in this case to avoid privacy risk of accessing the wrong chart.

If a single match is found, CC validates that the birth date and surname match as expected.

2. Load and Verify Additional Patient Data to Complete the Check-In

Presuming a match is found for an existing patient record, Ocean proceeds to read relevant information from the integrated system regarding the patient.

Starting with the Patient record, it uses the basic information such as the name and address information. The "generalPractitioner" field is also used in the Patient resource to reference the primary care provider (PCP) for the patient. Many schedules are restricted to allow only patients with a matching PCP, so this field is considered mandatory. Check the Patient profile for details on the data requirements.

If the patient query succeeds, an additional query is performed:

  • GET Patient/{id}/$everything?_type=CareTeam,Appointment

This query fetches the patient's existing appointments and the patient's care team so that optional constraints may be enforced (e.g., only one Physical per year, only patients of Dr. Jones etc.). See the $everything operation definition in this project for details on this call. In this context, Ocean is expecting to receive a Bundle containing a set of CareTeam and Appointment resources.

Appointment Loading and Validation

Ocean requires the patient's set of past and future appointments to enforce its customizable booking rules. For example, clients can configure a rule such as, "No more than 1 Physical per year". To enforce these rules, the relevant Appointments must be returned in the $everything bundle. For performance reasons however, systems may reasonably choose to omit very-old or far-off future appointments, such as appointments more than 2 years old or repeat appointments more than 1 year in the future.

Care Team Loading and Validation

The patient's set of providers (Practitioners) is used to determine which booking schedules should be available to the patient. For example, depending on the configuration, Dr. Jones' patients may not be able to book into Dr. Smith's schedule, and vice-versa.

To determine the patient's providers, first the "generalPractitioner" field in the Patient resource is used reference the primary care provider (PCP) for the patient. Check the Patient resource profile for details on this field.

The CareTeam may be also used to indicate the patient's full set of providers. NOTE: Currently alternate/secondary providers are not supported by Ocean's booking engine, but this functionality may be provided as a future enhancement. With this in mind, we recommend that you provide these providers as a CareTeam resource to ensure the integration supports this enhancement. Once implemented, as long as the CareTeam contains a given provider, and the Ocean online booking schedule's configuration permits patients with this provider to book in the schedule, the patient will be eligible to book within the schedule.

If a patient is found but none of the configured schedules allow this particular patient to book, the check-in will fail with an appropriate error message shown to the patient.

Patient-Specific Online Booking Rules (Optional)

Sometimes clinics want to adjust the booking options for specific patients, or to deny them access entirely. To find these patient-specific configurations, Ocean inspects the Patient resource for the following optional extensions:

See the Patient Profile for more information.

3. Schedule Selection

If the patient is permitted to check in, the available schedules for the patient are shown. Since these schedules were configured in part 0, this step has no dependency on the integrated system.

However, it is worth noting that Cloud Connect automatically performs "partial synchronizations" every half hour (or sooner upon request), essentially repeating the steps in 0, to ensure the schedule metadata is reasonably up-to-date.

4. Booking Form Completion

If the patient is permitted to check in, the booking form is shown. This form may be customized using the Ocean's form library. It does not depend on the integrated system. However, the form content does contribute to the OAB progress note, which is submitted as a DocumentReference later on as part of a successful booking.

5. Slot Selection

Once the booking form is completed, the booking calendar is shown and the available slots are loaded.

The slots are loaded using a combination of FHIR requests:

  • Slot?schedule={scheduleId}&start=ge{startDateTime}&start=lt{endDateTime}&end=lt{endDateTime}
  • Appointment?slot.schedule={scheduleId}&date=ge{startDateTime}&date=lt{endDateTime}

The Slots do not necessarily need to omit time slots that are occupied based on the presence of an overlapping Appointment start/end time. Most EHRs do not perform this sort of online booking logic themselves. Consequently Ocean's OAB has its own logic to filter out the slots that are blocked by these appointments.

The startDateTime and endDateTime are in standard ISO date/time format and often reflect the start and end of the selected month in the online booking view. See the Profiles for details on each Resource and endpoint call.

Slot-Specific Booking Suggestions

The Slot may include an optional "appointmentType" code, which acts as a suggestion for the booking slot. This appointmentType code, when provided, should be included in the set of potential slot suggestions (/ValueSet/schedule-code) fetched in Step 0.

For example, a Slot may return "WBVs" as the schedule code for its appointmentType, indicating that only appointments of type "Well Baby" should be booked within these slots, depending on the site's configuration for their Ocean OAB schedule's appointment type booking restrictions.

A note performance implications for the Slot/Appointment queries:

The time slot and appointment information queried in this step are expected to change frequently during a busy clinic. Ocean keeps its own local cache of this appointment and time slot information to limit the number of requests to the integrated system. However, since there may be manual bookings occurring simultaneously with the automated bookings, to avoid stale data that leads to double-booking, the cache is invalidated up to every 20 minutes when viewing the timeslots on an individual day, and up to every 5 hours when viewing the entire month view and on the first available appointment summary.

Developers may rightly conclude that this Appointment query could incur significant load on the EMR/EHR database, particularly since it is performed quite frequently to ensure the available slots are not out of sync with concurrent manual (telephone-based) bookings in the EHR. Implementors should ensure that their system is prepared to handle this increased load and keep it in mind when troubleshooting system-wide slowdowns. To limit the performance impact, consider optimizing the Appointment query to return only the bare minimum data set for each appointment (start, end, status, patientId, appointment type) using proper indexing, and increase database scaling capacity appropriately for larger clinics.

6. Booking

Once the patient chooses a slot, CC proceeds to call POST Appointment. The Appointment will be populated with relevant information as described in the profile, including the Slot ID if it was supplied. Based on the FHIR create standard, this call expects to receive a status 201 "created" FHIR result, with a response header with key "Location" with value https://yourfhirserverBaseURL/Appointment/[id]/_history/[vid]. Ocean will use this [id] value for subsequent updates to the appointment. The [vid] is the version ID and can simply be returned as a constant "1".

If the patient specified a contact email (or one already exists in the Patient resource), Ocean will send a confirmation email to the patient, along with a link to attempt a cancellation for the appointment.

As part of a successul booking, CC will also attempt to upload the following resources to the patient's chart:

  • POST Patient - To create a new patient chart if no existing chart was found during the initial check-in. Currently, the chart is created only after the online booking submission is reviewed and imported in the Ocean Online Booking portal.
  • PUT Patient - Optional. For an existing chart, this call is used to update Patient resource values (often the patient's contact information), if specified on the booking form. The Patient FHIR payload will include only the fields that have been populated on the booking form. Note that if the booking form does not contain any changes relevant to the Patient object (i.e., no fields tagged as demographic or contact information), then Ocean will not issue the PUT call.)
  • POST DocumentReference - To upload a progress note containing the clinical details of the online booking, particularly the note generated by the booking form. This DocumentReference contains a "text/plain" progress note designed to briefly summarize the patient's booking details including the reason for visit and other customizable aspects of the booking form, mainly for a brief review by the clinician immediately prior to the encounter. The administrative team does not need to see this note since the Appointment resource contains the salient information.
  • POST Observation - Optional. To post tagged EMR Field values generated by the booking form, such as a "@CovidScreeningResult".
  • POST QuestionnaireResponse - Optional. To record specific key/value answers from the booking form.

Note: In its current form, Ocean will upload these patient resources at this stage only when the chart is pre-existing. For walk-in clinics, the clinic must first manually review and import the online booking submission in the portal prior to the chart creation, which occurs at a later point in time.

8. Post-Booking Form Note Submission (Optional)

After a successul booking, some clinics present patients with an optional "post booking" form. Usually this form is read-only, but some clinics use the post-booking form as an opportunity for the patient to record additional details about the upcoming appointment, such as a historical account of the presenting illness.

Much like the Booking Note submission, CC will call the same endpoints as needed, such as the DocumentReference and PUT Patient, to record additional notes and Patient field updates supplied on the post booking form.

9. Cancellation

If the patient clicks the cancellation link in the confirmation email, CC will first call:

  • GET Appointment/id to check the appointment status.

  • This cancellation request may be rejected if the appointment is within the minimum-notice window or if its status has fundamentally changed; in this case, the patient will be instructed to contact the clinic directly.

If the cancellation request is granted, CC will call:

  • PUT Appointment: This will submit a base Appointment resource with a matching ID. The appointment's status will be updated to "cancelled" and cancellationReason as code "pat-crs". The participants will also be returned except the Patient participant's status will also be set to "cancelled".
  • POST AppointmentResponse with participation status "declined"; comment "Appointment canceled by the patient via Ocean"; appointment reference "Appointment/"; and single participant with actor reference "Patient/" and a participant type (system "http://hl7.org/fhir/ValueSet/encounter-participant-type"; code "PART"; display "Participation")

10. Reminders

Ocean can send reminders for both OAB-based appointments and manually-scheduled appointments.

Although appointment reminders are offered as a separate independent Ocean product from OAB, they naturally complement OAB workflows. Many OAB "must-have" checklists expect reminder functionality; since there is much overlap with the FHIR calls, integrators should strongly consider supporting both products. See the Reminders section for more information.

11. Online Booking Submission Review and Import

Some clinics elect to configure a manual review process for their bookings within the Ocean portal. This step is necessary currently for walk-in clinics and other systems that create new patient charts based on the online bookings.

Once the MOA imports the submission in the portal, if a new chart must be created, it is submitted as a POST Patient call followed by the other calls outlined in the preceding "Submission of Booking Note and Related Resources" step.

12. Online Booking Submission Rejection

Some clinics elect to configure a manual review process for their bookings within the Ocean portal.

As part of this workflow, when the MOA clicks Decline, it is submitted as a PUT Appointment call with status "declined" and an AppointmentResponse call with the Practitioner AppointmentParticipant status as "declined" as well.

Test Cases

The following test cases highlight typical use cases and may be used by vendors as a form of "smoke testing" for new releases. Keep in mind that there are many different workflows for online booking beyond these simple examples.

A: Schedule configuration queries

  1. Add or change the following in the EMR/EHR: an appointment type; a schedule; a schedule code; and a practitioner/provider.
  2. In Cloud Connect, click the button to Synchronize with the EMR/EHR and wait for it to finish successfully.
  3. View the Appointment Types.
    1. Click to enable the "EMR Appointment Type Mapping" if not already done.
    2. Check the EMR Appointment Type dropdown for one of the Ocean appointment types to confirm that the updated appointment type is listed.
  4. View the Provider Schedules in the Ocean Portal.
    1. Click Add Schedule to confirm that the updated schedule is listed. Click Cancel.
    2. Open an existing schedule (create one if necessary).
    3. Add an Appointment Type (create one if necessary) and click Edit Restrictions on the appointment type.
      1. In the "Only book in time slots with the following" appointment type restriction, confirm that the updated schedule code is listed.
    4. In the Restrictions section, "Who is allowed to book into this schedule?", choose "Patients with Selected Providers".
    5. Click "Add Provider" below the restriction and confirm that that the updated practitioner/provider is listed.

B: Booking and canceling as a registered patient with an assigned primary care provider

  1. Ensure that the EMR/EHR has the following and has already synced with Ocean:
    • A patient P1 with:
      • A designated family doctor F
      • A surname, first name, birth date, and health number
      • A test email that you can access
    • A practitioner/provider for family doctor F
    • A schedule for family doctor F
      • Ensure that the schedule has bookable slots from 9:00 AM to 12:00 PM, Monday to Friday, with 10-minute intervals.
      • Ensure that the schedule has an existing appointment booked on the upcoming Monday from 9:10-9:20.
    • A schedule for "Flu Clinic"
    • An appointment type "Phone"
  2. Ensure that Ocean is configured with:
    • An appointment type "Telephone Visit" of duration 10 minutes, mapped to the EMR type "Phone"
    • A schedule linked to "Flu Clinic"
    • A schedule linked to family doctor F with a time interval matching the EMR/EHR (10 minutes)
      • Ensure that this schedule F has:
        • A restriction, "Who is allowed to book into this schedule?", choose "Patients with Selected Providers" and family doctor F
        • The default Ocean online booking form and post-booking form (check the Edit Advanced Settings if you are unsure)
        • No other restrictions listed that might interfere with the test case
    • A booking link with both schedules
    • The same time zone as the EMR/EHR
  3. Open the booking link in a private browsing ("incognito") window.
  4. Enter P1's information to check in.
  5. Complete the booking form and choose "Telephone Visit"
  6. Confirm that both Flu Clinic and the family doctor schedule F are offered as schedule options.
  7. Select the family doctor schedule to see the available slots.
  8. Confirm that the time slots show the correct availabilities, i.e., M-F 9:00 to 11:50, except on Monday where the available time slots should be 9:00-9:10 and 9:20-11:50.
  9. Select the Monday 9:30-9:40 time slot and book it.
  10. Confirm that the EMR appointment schedule shows the appointment in the 9:30-9:40 slot with the correct appointment type "Phone".
  11. Confirm that P1's medical chart contains a progress note summarizing the online booking form's answers.
  12. Acting as P1 again, in the (customizable) post-booking form's question, "You may include comments here to help your provider prepare for this visit:", answer "testing post-booking form" and submit the form.
  13. Confirm that P1's medical chart contains another progress note stating, "testing post-booking form".
  14. Check for the notification email sent to P1's email address.
  15. Click the Cancel Appointment link in the email and proceed to cancel the appointment.
  16. Confirm that the appointment is removed from the EMR/EHR schedule (or appropriately marked as canceled, depending on the EMR/EHR's convention).

C: Booking as a new patient in a walk-in clinic

  1. Ensure that the EMR/EHR has the following and has already synced with Ocean:
    • A schedule "WIC"
      • Ensure that the schedule has bookable slots from 1:00 PM to 4:00 PM, Saturday and Sunday, with 5-minute intervals.
      • Ensure that the schedule has an existing appointment booked on the upcoming Saturday from 1:05 PM-1:15 PM.
    • An appointment type "Walk-In"
  2. Ensure that the Ocean site is configured with:
    • An appointment type "Walk-In Visit" of duration 10 minutes, mapped to the EMR type "Walk-In"
    • A schedule "Walk-In Clinic" linked to the WIC schedule with a time interval matching the EMR/EHR (5 minutes)
      • Ensure that this schedule has:
        • A restriction, "Who is allowed to book into this schedule?", choose "All Patients"
        • The appointment type "Walk-In Visit"
      • No other restrictions listed that might interfere with the test case
    • A booking link with the WIC schedule
      • Ensure that the booking link has "Limit online booking to patients with a chart in your EMR" unchecked.
    • The same time zone as the EMR/EHR
  3. Open the booking link in a private browsing ("incognito") window.
  4. Enter the patient's information to check in. Ensure that the health number or other identifier does not already exist in a patient's chart in the EMR/EHR.
  5. Complete the booking form and choose "Walk-In Visit"
  6. Confirm that the "Walk-In Clinic" is offered and select it to see the available time slots.
  7. Confirm that the time slots show the correct availabilities, i.e., Saturday and Sundays 1:00 PM to 4:00 PM, except on the upcoming Saturday where the available time slots should be 1:15 PM to 3:50 PM (since the 1:00-1:05 slot is too small to hold the 10-minute appointment).
  8. Select the Saturday 1:15 PM time slot and book it.
  9. Confirm that the EMR appointment schedule shows the appointment in the 1:15-1:25 PM slot with the correct appointment type "WIC" and the patient's name in its usual label. Note that this appointment will not be linked to a patient because the patient does not yet exist in the EMR/EHR.
  10. In the Online Booking Submissions, confirm its presence in the Needs Review section and Accept the appointment. This should trigger the patient chart creation in the EMR/EHR.
  11. Confirm that the medical chart exists in the EMR/EHR now, with the patient's name and other basic information automatically populated along with the online booking form note. Note that the appointment is not automatically linked to this chart (unless it is somehow linked by the POST patient call handler on the EMR/EHR end).

D: Booking as a registered patient into a dedicated slot

  1. Ensure that the EMR/EHR has the following and has already synced with Ocean:
    • A patient P1 with:
      • A designated family doctor F
      • A surname, first name, birth date, and health number
      • A test email that you can access
    • A practitioner/provider for family doctor F
    • A schedule for family doctor F
      • Ensure that the schedule has bookable slots from 9:00 AM to 12:00 PM, Monday to Friday, with 10-minute intervals.
      • Ensure that the schedule has a slot allocated for "PHEs" (periodic health exams) on Wednesdays from 9:30-11:00
      • Ensure that a PHE is booked on the upcoming Wednesday from 9:30 - 10:00
    • An appointment type "PHE"
    • A schedule code "PHEs" (returned via the /ValueSet/schedule-code FHIR query in step 0)
  2. Ensure that Ocean is configured with:
    • An appointment type "Periodic Health Exam" of duration 30 minutes, mapped to the EMR type "PHE"
    • A schedule linked to family doctor F with a time interval matching the EMR/EHR (10 minutes)
      • Ensure that this schedule F has:
        • The appointment type "Periodic Health Exam" with restriction, "Only book in time slots with the following schedule-code applied: [PHEs]"
  3. Open the booking link in a private browsing ("incognito") window.
  4. Enter P1's information to check in.
  5. Complete the booking form and choose "Periodic Health Exam"
  6. Confirm that the schedule is offered as the schedule option and select it to see the available slots.
  7. Confirm that the time slots show the correct availability, i.e. Wednesdays from 9:30-11:00, except on the first Wednesday, where only 10:00-11:00 is available.
  8. Select the Wednesday 10:30-11:00 time slot and book it.
  9. Confirm that the EMR appointment schedule shows the appointment in the same time slot with the correct appointment type "PHE".
  10. Confirm that P1's medical chart contains a progress note summarizing the online booking form's answers.

Additional test cases to consider

  • Attempting and failing to book as a patient with online booking disabled via the extension https://ocean.cognisantmd.com/svc/fhir/v1/StructureDefinition/oab-allowed
  • Booking as a patient tagged as requiring an extended appointment time specified via the extension https://ocean.cognisantmd.com/svc/fhir/v1/StructureDefinition/oab-min-appointment-duration
  • Attempting and failing to book as a patient with an appointment type T that has been booked within the minimum wait defined in the schedule's appointment type restriction, "Prevent patients from booking another [T] within days"
  • Attempting and failing to book as a patient with an appointment type T that has already been booked for another patient on a Monday, due to the schedule's appointment type restriction, "Book a maximum of 1 [T]s per day on [Monday]"
  • Attempting and failing to book as a patient without a primary care provider