0.1.0 - ci-build

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

Use Cases Appointments

Appointments

Overview

This use case describes how a patient-facing application confirms the outcome of an appointment booking attempt after handing off the user to a provider booking portal (e.g., via SMART Scheduling Links deep links). The goal is to ensure the client application can reliably determine whether an appointment was successfully booked (or not) and, when booked, maintain a local Appointment representation that can trigger downstream coordination such as transportation and task assignment.

This use case focuses on booking confirmation and client-side appointment reconciliation, not on participant acceptance workflows (iCalendar-style responses) or EHR-specific scheduling operations.

Problem statement

In a deep-link scheduling workflow, the patient or caregiver leaves the client application to complete booking in a provider booking portal. The provider portal is the system that determines whether booking succeeds, fails, or is cancelled. However, deep-link discovery standards do not universally define how the booking portal communicates completion back to the client application.

Without a confirmation mechanism, the client application cannot reliably:

  • determine whether booking succeeded,
  • transition the booking attempt out of a pending state,
  • create/activate downstream logistics (e.g., transportation),
  • or present a trustworthy confirmation experience to the user.

Actors and systems

Primary actors

  • Patient
  • Caregiver

Supporting systems

  • Patient-facing scheduling application (“client application”)
  • Provider booking portal (“portal”)
  • Provider scheduling system / EHR

Preconditions

  • The client application has discovered availability and the user has selected a slot/time and destination location.
  • A deep link into the provider booking portal is available.
  • The user initiates booking by following the deep link.

Conceptual lifecycle

From the client application perspective, booking has three phases:

  1. Booking intent (pre-handoff)
    • The user selects a slot and initiates booking.
    • The client creates a local booking attempt record.
  2. Portal booking (handoff)
    • The user completes booking within the provider portal.
    • The portal determines the booking outcome.
  3. Confirmation and follow-through
    • The portal returns the user to the client application with the booking outcome.
    • The client updates local state and triggers downstream workflows as appropriate.

Booking attempt (client-managed)

The client application SHOULD maintain a local record representing an in-flight booking attempt. This record is used to:

  • track the selected slot and intended appointment details,
  • support user experience (pending state, retry),
  • and correlate a portal return response to the correct attempt.

The booking attempt is internal to the client application. It is not required to be represented as a FHIR resource.

Booking confirmation return handshake (baseline pattern)

The recommended baseline pattern is a return handshake from the provider portal back to the client application after booking completion. This pattern is designed to be:

  • minimal and easy for portals to implement,
  • safe by default (avoids PHI in URLs),
  • and sufficient to enable downstream workflows without requiring immediate provider FHIR API access.

Conceptual flow

  1. The client application generates a state value (opaque correlation handle) and associates it with a local booking attempt.
  2. The client launches the provider portal via deep link and includes:
    • the state value
    • a returnUrl for post-booking navigation
  3. The user completes booking in the portal.
  4. The portal redirects the user back to the returnUrl, including a minimal booking outcome payload.
  5. The client application uses state to locate the booking attempt and applies the outcome to finalize client-side state.

Booking outcome payload (minimal required parameters)

To minimize implementation burden, the booking outcome payload SHOULD be kept small and focused.

Required parameters

The portal SHALL return the following parameters:

  • state (correlation token)
    An opaque value generated by the client application and echoed back by the portal to correlate the booking outcome with the original booking attempt.

  • outcome (booking result)
    A constrained code indicating the outcome of the booking attempt.

Allowed outcome codes

The portal SHALL return one of the following values for outcome:

outcome Meaning Client behavior Mapping to Appointment.status
booked Booking completed successfully Confirm/create local Appointment and trigger downstream workflows booked
cancelled Booking flow was cancelled Do not trigger downstream workflows; retain attempt history as cancelled cancelled (if Appointment exists locally)
entered-in-error Booking was created but later invalidated by the system Do not trigger downstream workflows; record as error entered-in-error
failed Booking did not complete and no Appointment was created Do not trigger downstream workflows; present retry guidance No Appointment exists

failed is intentionally included to represent cases where booking does not complete before an Appointment is created (e.g., slot no longer available, portal error, validation failure).

Optional parameters (progressive enhancement)

To support richer user experience and stronger reconciliation, the portal MAY return additional parameters. These should be treated as optional enhancements and not required for baseline adoption.

Recommended optional parameters include:

  • reason (code)
    High-level, non-identifying reason when outcome != booked (e.g., slot-unavailable, system-error, auth-required, validation).

  • bookingRef
    Provider booking confirmation number or portal reference identifier.

  • appointmentRef
    Identifier or reference to a FHIR Appointment in the provider system, when available.

  • resultToken
    A short-lived, one-time token that could enable authenticated backchannel retrieval of appointment details in the future.

State parameter requirements

Although the client application uses state to locate the associated booking attempt (and therefore the patient within the client system), the state value itself MUST be opaque.

The state parameter:

  • MUST NOT encode patient identity, appointment time, location, or other PHI
  • SHOULD be short-lived (expires after a limited duration)
  • SHOULD be single-use to reduce replay risk

Appointment representation in the client application

When outcome=booked, the client application SHOULD create or update a local Appointment representation to reflect the confirmed booking. The Appointment is the canonical client-side record used for:

  • future coordination (transportation, tasks),
  • reminders and notifications,
  • user-facing appointment history.

The client-side Appointment MAY be:

  • a locally constructed Appointment derived from the slot selection and booking confirmation, or
  • a reference to an Appointment created in the provider system (if available).

When outcome=failed, the client application SHOULD NOT create a confirmed Appointment record (since one may not exist) but MAY retain the booking attempt for auditing and user experience.

Triggering downstream workflows

A confirmed Appointment enables additional workflows such as:

  • transportation coordination
  • caregiver task assignment
  • pre-visit preparation tasks (forms, insurance, documentation)

Downstream workflows should only be triggered when booking is confirmed (outcome=booked), since the client already possesses enough context (time, destination, patient/pickup preferences) to proceed.

Optional reconciliation via provider FHIR APIs

When the patient has authenticated access to a provider’s FHIR APIs (e.g., SMART on FHIR), the client application MAY reconcile and enrich the local Appointment using provider data.

Examples include:

  • querying for appointments within a time window to confirm details
  • resolving appointmentRef to retrieve canonical appointment details
  • establishing subscriptions for ongoing appointment updates when supported

These patterns provide stronger assurance and ongoing synchronization but are not required for baseline booking confirmation.

Relationship to FHIR AppointmentResponse

FHIR AppointmentResponse is designed for iCalendar-style participant responses to a proposed appointment (accept/decline/tentative). The booking confirmation return handshake in this use case is distinct: it represents completion of a portal-based booking process and is not intended to replace AppointmentResponse workflows.

Privacy and security considerations

  • Booking outcome payloads returned via URL redirects should avoid PHI.
  • Prefer coded, high-level reason values rather than free-text.
  • Use opaque state tokens that are short-lived and single-use.
  • Treat optional tokens or references (resultToken, appointmentRef) as sensitive and protect them appropriately.

Summary

This use case establishes a pragmatic approach to confirming appointment booking completion after deep-link handoff. By requiring only state and outcome and aligning outcome with Appointment status semantics where applicable, the pattern minimizes implementation burden while enabling reliable client-side appointment management and downstream coordination workflows.