0.2.0 - Informative
TCFHIRAGSchedulingR5 - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
This implementation guide supports the following interactions for a scheduling process.
A Scheduling Client can create a Patient on a Scheduling Server. This is a prerequisite for booking an Appointment in which this Patient participates. The HL7® AT Core Patient Profile SHALL be used by both the Scheduling Client for the request as well as the Scheduling Server in the response.
A Scheduling Client can fetch bookable HealthcareServices from a Scheduling Server. Search parameters of the HL7® AT Scheduling HealthcareService Profile can be used to filter the results. If no search filter for the active
attribute is provided, the Scheduling Server SHALL respond with resources where the value of the active
attribute is true
or not present.
Depending on the scheduling scenario that is implementented ("peer-to-peer" appointment booking, availability of a central platform for scheduling, …), it might be necessary not only to find healthcare services that are offerd but also to find out which medical institution is offering them. Additionally, finding healthcare service providers that offer a service close to a location or within a certain zip-code area might be useful as well.
For such a purpose, this IG provides a new operation called $findHSP (find Healthcare Service Provider).
This operation uses either a full HealthCareService resource as input parameter or dedicated codes for it like HealthcareService.category
, HealthcareService.type
or HealthcareService.specialty
.
In addition to that a Scheduling Client can provide further filter criteria in its search like:
The response will be a Bundle consisting of the HealthcareService resource and a list of healthcare service providers (Organization, Practitioner, PractitionerRole) that offer the requested service.
After (optional) selection of a HealthcareSerice a Schedulung Client can fetch available Schedules. The schedule resource provides a container for (time)-slots that can be booked using an appointment. One schedule applies to one service or resource that can be booked and contains multiple slots indicating the availability of this service/resource. A real-world analogue of a schedule is a calendar column (for a single resource or service). For a more detailed description, refer to Schedule. Search parameters of the HL7® AT Scheduling Schedule Profile can be used to filter the results. If no search filter for the active
attribute is provided, the Scheduling Server SHALL respond with resources where the value of the active
attribute is true
or not present.
After selecting one or more Schedules, available Slots for this/those Schedules can be fetched. The slot is one unit of time on a schedule and represents the smallest unit of time that the service or resource can be booked for. A real-world analogue of a slot would be the rows in a calendar column. For a more detailed description, refer to Slot. Search parameters of the HL7® AT Scheduling Slot Profile can be used to filter the results.
In this optional step, a Slot can be requested to be put on hold (i.e. reserved) by a Scheduling Client until the Appointment is booked. $hold is the corresponding operation definition. The Slot is identified either by a Reference or one or more Identifiers, which have to identify a single slot instance. For creating a hold on an Appointment, the parameter slot-status
SHALL have value busy-tentative
. For releasing the hold on a previously reserved Slot, slot-status
SHALL have value free
. The response contains the Slot resource and an OperationOutcome. In case of successfull creation of the hold, the status
of the Slot is set to "busy-tentative" and the response SHALL contain a parameter held-until
with type dateTime, signaling, when the hold expires automatically. The Scheduling Server decides how long a Slot is held. If the Slot was successfully released, the status
is set to free
. If the hold operation is rejected, due to another Scheduling Client consuming the Slot by booking an Appointment or creating a hold on the Slot, the status
of the Slot is set to "busy-unavailable".
The scheduling client books an appointment by sending an HL7® AT Scheduling Appointment Profile resource with status
proposed
to the Scheduling Server. The Scheduling Server returns a Parameters response containing the requested Appointment and an OperationOutcome. The Appointment resource will have an updated status
of booked
if the request is approved, pending
if it needs to be manually confirmed or cancelled
if it is rejected. The corresponding operation definition is the $book operation.
To cancel an Appointment, the Scheduling Client sends an HL7® AT Scheduling Appointment Profile with its status
set to cancelled
or entered-in-error
. The Scheduling Server responds with the Appointment resource or an OperationOutcome in case of error.
When an Appointment is cancelled on the Scheduling Server it's status is set to cancelled
. The Scheduling Server is responsible for notifying participants of the Appointment (e.g. via email, text message or push notification) about the cancellation. Scheduling Clients then can fetch the updated Appointment (see Find existing Appointments).
To postpone an Appointment, the Scheduling Client sends an HL7® AT Scheduling Appointment with updated values for start
, end
and optionally minutesDuration
. The Scheduling Server then returns the updated Appointment or an OperationOutcome in case of error. The Scheduling Server responds with the Appointment resource or an OperationOutcome in case of error.
When an Appointment is postponed on the Scheduling Server, the values for start
, end
and optionally minutesDuration
are updated. The Scheduling Server is responsible for notifying participants of the Appointment (e.g. via email, text message or push notification) about the postponement. Scheduling Clients then can fetch the updated Appointment (see Find existing Appointments).
ToDo: Define restrictions on which fields can be updated.
To update an Appointment, a Scheduling Client sends a HL7® AT Scheduling Appointment Profile resource with updated attributes. The Scheduling Client SHALL NOT change the participant Patient of the Appointment. The Scheduling Server then returns the updated Appointment or an OperationOutcome in case of error. The Scheduling Server responds with the Appointment resource or an OperationOutcome in case of error.
When an Appointment's information is updated on the Scheduling Server, the values ToDo list allowed attributes are updated. The Scheduling Server is responsible for notifying participants of the Appointment (e.g. via email, text message or push notification) about the update, if the changed information requires informing them. Scheduling Clients then can fetch the updated Appointment (see Find existing Appointments).
Scheduling Clients can fetch existing Appointments from Scheduling Servers. Search parameters of the HL7® AT Scheduling Appointment Profile can be used to filter the results.
ToDo: Example Search URL
Due to the potentially large amount of data, paging SHALL be used for all interactions with HTTP method GET
. For the correct usage of paging see official documentation.
In typical appointment booking systems appointment-related messages are sent via various channels (e.g. email, text message). Because this implementation guide allows chaining multiple Scheduling Servers cascadingly, the necessity arises to coordinate which Scheduling Server is resoponsible for sending those messages. By default the Scheduling Server, that also persists Appointments, SHOULD be the one that also sends the Appointment-related messages. However service providers of Scheduling Servers MAY also have different bilateral arrangements, which are managed outside of the scope of this implementation guide.
Scheduling Clients SHALL use the following HTTP return preference for requests of standard POST
and PUT
interactions:
Prefer: return=representation
Scheduling Servers SHALL respond to POST
and PUT
requests of standard interactions with the full resource in the response body as described here.