Scheduling, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.0.0-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.Scheduling/ and changes regularly. See the Directory of published versions

2:3.115 Find Potential Appointments [ITI-115]

This section corresponds to transaction [ITI-115] of the IHE Technical Framework. Transaction [ITI-115] is used by the Scheduling Client and Scheduling Server Actors. The Find Potential Appointments [ITI-115] transaction is used to provide a set of parameters to the server, and based on them to get back a list of possible appointments.

2:3.115.1 Scope

The Find Potential Appointments [ITI-115] transaction allows a Scheduling Client to retrieve a list of available slots for potential appointments from a Scheduling Server based on certain search criteria.

2:3.115.2 Actors Roles

Table 2:3.115.2-1: Actor Roles

2:3.115.3 Referenced Standards

• HL7 FHIR Release 4

2:3.115.4 Messages

Figure 2:3.115.4-1: Find Potential Appointments Interactions

2:3.115.4.1 Find Potential Appointments Request

This transaction uses the $find operation as defined in the Operation Definition.

2:3.115.4.1.1 Trigger Events

When a Scheduling Client needs to find potential slot to book a new appointment it issues a "Find Potential Appointments" request.

2:3.115.4.1.2 Message Semantics

The Find Potential Appointment request is defined as a FHIR Operation. Please see the corresponding Operation Definition.

2:3.115.4.1.2.1 Request Parameters

The request parameters in the table, which is part of the operation definition, are derived from search parameters defined for the FHIR Appointment Resource, and from additional functionally relevant entities, for example organization or referral.

Example: The Scheduling Client uses an HTTP POST with the body containing the search parameter like this:

POST  [base]/Appointment/$find

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "start",
        "valueDateTime" : "2017-07-15T20:00:00Z"
    },
    {
        "name": "end",
        "valueDateTime" : "2017-07-17T20:00:00Z"
    },
    {
        "name": "practitioner",
        "valueReference": {"identifier": {"system":"urn:oid:1.3.6.1.4.1.19376.1.2.999", "value": "PR23143"},"display":"Dr. Pro Vider" }
    }]
}

2:3.115.4.1.3 Expected Actions

Binding to CodeSets and ValueSets are expected to be localized. In no localization is available the Scheduling Client is expected to use a code from the:

Note 1: Practice Setting Code ValueSet.

Note 2: Appointment Reason Code ValueSet.

Note 3: Service Category ValueSet.

Note 4: Service Type ValueSet.

The Scheduling Client SHALLsupport FHIR Pagination when the Scheduling Server paginates its response.

2:3.115.4.2 Find Potential Appointments Response Message

2:3.115.4.2.1 Trigger Events

Upon receiving a Find Potential Appointments request the Scheduling Server apply internal (business) logic to determine possible appointment (slots) that meet the search criteria specified by the Scheduling Client. The Scheduling Server returns a list of potential Appointment option the Scheduling Client can choose from to reserve or book an appointment.

2:3.115.4.2.2 Message Semantics

The list of potential appointments is returned as a FHIR Bundle of type searchset is returned containing 0, 1, or more Appointment resources. The details are in the Bundle profile.

2:3.115.4.2.3 Expected Actions

The Scheduling Server will make a best effort to find potential Appointments. Each Appointment resource included in the response Bundle needs to be as complete as possible allowing the Scheduling Client to render the appointment information in such a way that a (human) user is able to reserve or book an appointment.

The Scheduling Server SHALL honour the _count request parameter when included in the Find Appointments Query request by a Scheduling Client by limiting the number of potential appointments to match the _count value.

The Scheduling Server SHALL include a total attribute in the FHIR Bundle response indicating the total number of potential appointments it has determined.

The Scheduling Server MAY use pagination allowing a Scheduling Client to page through the results.

The Scheduling Server SHALL NOT include any held appointments (i.e. appointments that were reserved as a result of a previous $hold operation, and for which the holding period had not expired) in the list of potential appointments.

2:3.115.4.2.4 Error Codes

In the absence of any processing errors a http 200 (OK) error code is returned.

In case security or other constraints prevent a Scheduling Server from returning a response to the Scheduling Client a http 4xx error code is returned.

Table 2:3.115.4.2.4-1: Error Codes

The Scheduling Server MAY include an OperationOutcome to the response where it uses the values from the Error Codes table.

Table 2:3.115.4.2.4-1: OperationOutcome Attributes

2:3.115.5 CapabilityStatement Resource

A Server implementing this transaction SHALL provide a CapabilityStatement Resource as described in ITI TF-2x: Appendix Z.3 indicating the transaction has been implemented.

• Requirements CapabilityStatement for Client
• Requirements CapabilityStatement for Server

2:3.115.6 Security Considerations

See IHE Scheduling Security Considerations

2:3.115.6.1 Security Audit Considerations

''TODO: The security audit criteria ''

2:3.115.6.2 Client Audit

''TODO: the specifics''

2:3.115.6.3 Server Audit

''TODO: the specifics''