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

Overview

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

Appointment Writeback

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 notifies relevant participants. These operations ensure appointment records remain synchronised across systems such as Helix, Helix Hub, and online booking portals.

You can create, update, and cancel an appointment via Helix FHIR API. A FHIR Subscription notification will be triggered to notify downstream providers, such as a specialist or imaging centre.

Creating a New Appointment

Context:
An appointment needs to be scheduled for a patient, whether it is for a consultation, procedure, or follow-up visit.

Expected Outcome:
An appointment for a patient has been created in the Helix Appointment Book with the chosen timeslot and practitioner.

An appointment example:
A new Appointment resource is created and associated with a valid Slot, Patient, Location, and Practitioner.

• Initial FHIR values:

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

• Helix Writeback Behavior:
  • If successfully created in Helix:

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

  • If unsuccessfully created in Helix:

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

Updating an Appointment

Direct updates to appointment times or slots are not supported. Instead, you need to cancel the existing appointment and rebook it. See Cancelling an Appointment and Creating a New Appointment.

Cancelling an Appointment

Context:
The patient cancels an appointment, or the provider's availability changes.

Expected outcome:
The appointment's status is updated to cancelled, and participant's status is updated to declined. All linked systems are notified and the associated slot becomes available.

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

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

Updating an Appointment Status

Context:
The appointment status should accurately reflect real-world outcomes, such as patient check-in or no-show.

Expected Outcome:
The updated status reflects the current state of the appointment and can trigger downstream workflows such as billing, documentation, or care coordination.

An example:

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

Considerations for Writeback

Slot Validation

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

Status Transitions

The table below lists all statuses that you can send and their corresponding mappings to Helix Hub statuses.

FHIR status	Helix Hub status mapping
Proposed/Pending/Booked	Booked
Arrived	Arrived
Cancelled	Deleted
NoShow	DidNotAttend

The table below lists all Helix Hub statuses and their corresponding mappings to FHIR statuses.

Available Helix Hub status	FHIR status mapping
Booked/DeclinedBySms/Rescheduled	Pending
Deleted/DeclineByReception	Cancelled
DidNotAttend	Arrived
Arrived	Arrived
ConfirmedBySms/ConfirmedByReception	Booked

Participant Status Management

Participant entries for patients or practitioners, must include a valid status such as accepted or declined.

participant.status = accepted | declined

Subscription Interactions

Appointment operations can impact linked systems and will trigger corresponding notifications via subscriptions. This is the preferred method for downstream systems to be notified of changes.

• Note: Polling for changes is not acceptable due to the unnecessary additional load imposed on systems.

Linked Resources:

• Patient resource: Updates to patient data such as contact details, may affect appointment reminders or outreach efforts.
• Slot resource: Booking or cancellation updates slot availability status.
• Practitoner: The healthcare provider associated with the appointment.
• Subscription resource: Enable notifications to downstream systems when appointments are created, updated or cancelled.
• You can find more information at FHIR page: Appointment

Conformance Requirements

Field Validation

• All mandatory fields such as status, participant, slot,practioner, must be filled.
• Decline appointments with invalid slot references, participant or practitioner roles.

Access and Permissions

• Ensure only authorised systems or users can create, update, or cancel appointments.
• Prevent modifications to appointments that have already been completed.