Helix AU Core - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Appointments

Appointments

Overview

A booking/scheduled meeting of a healthcare event among patients and practitioners for a specific date/time.

Appointment Writeback

Usage Context

The Appointment resource supports end-to-end scheduling operations including booking, updating, cancelling, and status tracking. Writeback functionality ensures that updates are accurately reflected across systems and notify relevant participants. These operations ensure appointment records remain synchronized across systems such as Helix, SmileCDR, and online booking portals.

Creating a New Appointment

Context:
An appointment needs to be scheduled for a patient, such as for a consultation, procedure, or follow-up.

Expected Outcome:
A patient calls to book a new appointment through a portal with the available slots.

Appointment Example:
A new Appointment resource is created and associated with a valid Slot, Patient, and Practitioner.

• Initial FHIR values:

  Appointment.status = proposed
  Appointment.participant.status = needs-action
  

• Helix Writeback Behavior:
  • If successfully created:

    Appointment.status = pending
    Appointment.participant.status = accepted (for PPRF, LOC)
    Helix database.AppointmentStatus = booked
    

  • If creation fails:

    Appointment.status = cancelled
    Appointment.participant.status = declined (for PPRF, LOC)
    Helix database.AppointmentStatus =deleted
    

• A FHIR Subscription notification will be triggered to inform downstream providers.

Updating an Appointment

Context:
Changes are made to an existing appointment, such as rescheduling or updating the reason for visit.

Example:
A provider is unavailable at the originally scheduled time, and the appointment needs to be moved to new slot.

Expected Outcome:

• Original appointment is cancelled.
• A new appointment is created with the updated details.
• Direct updates to appointment times or slots are not supported. Cancel and rebook with same details instead.

Cancelling an Appointment

Context:
The patient cancels, or the provider becomes unavailable.

Example:
A cancellation request is received, and the appointment needs to be marked as cancelled.

Expected Outcome:
The appointment's status is updated to cancelled, and participant's status is updated to declined any linked systems are notified.

Appointment.status = cancelled
Appointment.participant.status = declined

• Update the associated Slot as available.

Updating Appointment Status

Context:
Appointment status needs to reflect real-world outcomes like check-in or no-show.

Examples:

• Patient checks in: booked → arrived
• Patient doesn’t show up: booked → noshow
• Visit is complete: arrived → fulfilled
• Invalid transitions (e.g., fulfilled → booked) must be rejected.

Expected Outcome:
The updated status reflects the current state of the appointment and may trigger other workflows (e.g., billing or documentation).

Differences to Consider When Writing Back

Slot Validation

• Ensure selected Slot is still available at the time of booking or rescheduling.
• Prevent overlapping bookings.
• $getSlots Operation used to get available slots for a Practitioner.

Status Transitions

• Allowed transitions include:
  • booked → arrived
  • booked → cancelled
  • booked → noshow
  • arrived → fulfilled
• Invalid transitions (e.g., fulfilled → booked) should be rejected.

Participant Status Management

• Participant entries (e.g., patient, practitioner) must include a valid status such as accepted or declined.

  participant.status = accepted | declined
  

Time Zones and Localization

• Appointment times must consider server and client time zones to avoid discrepancies.

Subscription Interactions

Appointment writeback operations can impact linked systems and should support triggering appropriate notifications or events.

Linked Resources:

• Patient Resource: Changes in patient data (e.g., contact info) may affect appointment reminders or outreach.
• Slot Resource: Booking or cancellation updates slot availability.
• Practitoner: Associated healthcare provider.
• Subscription Resource: Can notify downstream systems about updates to appointments.
• More information can be found in FHIR page: Appointment

Conformance Requirements

Field Validation

• All required fields (e.g., status, participant, slot,practioner) must be present.
• Reject appointments with invalid slot references or participant or practitioner roles.

Access and Permissions

• Ensure only authorized systems/users can create, update, or cancel appointments.
• Enforce rules around past or completed appointment edits.

Status Transition Rules

• Must conform to supported status flow:
  • proposed → booked
  • booked → arrived → fulfilled
  • booked → cancelled or booked → noshow

Testing and Validation

Validation Rules and Expected Behaviors

• When a new appointment is created:
  • The Appointment.status must be set to pending.
  • The participant.status for both the Location and Practitioner should be set to accepted.
• An appointment must not be created if the start time is later than the end time.
  • The system must return a validation error in this scenario.
• An appointment must not be created if the start or end time is missing.
  • Both start and end times must be present and valid.
  • The system should return a clear validation error indicating missing required fields.
• An appointment must not be created if the start and end times are equal.
  • The system must reject the appointment due to zero-length duration.
• Appointment times must follow the correct local timezone rules based on Daylight Saving Time:
  • During DST, the system must store and reflect times in UTC+11.
  • After DST ends, the system must revert to UTC+10.
  • This behavior should occur even if the request explicitly uses UTC+10 or UTC+11.
• If a Practitioner is not associated with the selected HealthCareService:
  • The appointment should be created in Smile.
  • The appointment must not flow into Helix.
  • The appointment will not be saved in database
• For new or existing active appointments:
  • If an invalid Schedule,Patient reference is provided, the appointment must be created in Hub with:
    • Appointment.status set to cancelled
    • participant.status for both Location and Practitioner set to declined