Scheduling
1.0.1-current - ci-build

Scheduling, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.0.1-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

Actor | Role
--- | ---
Scheduling Client | Sends a "Find Potential Appointments" request to Server
Scheduling Server | Receives and processes the "Find Potential Appointments" request and responds with 0, 1 or more potential appointment slots

### 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 Find Potential Appointments 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 Find Potential Appointments 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. If 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 SHALL support 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 an 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 an http 4xx error code is returned.

Table 2:3.115.4.2.4-1: Error Codes

Error Code | Description | Explanation
--- | --- | ---
400 | Bad Request | The server cannot or will not process the request due to an apparent client error
401 | Unauthorized | The server cannot or will not process the request due to an authorization issue with the request
403 | Forbidden | The server cannot or will not process the request because the Scheduling Client (or a user) is not authorized for the request

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-2: OperationOutcome Attributes

Attribute | Value
--- | ---
severity | Fatal
code | <http error description>
diagnostics | <http error explanation>

### 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

The Find Potential Appointments Transaction, when it contains a Patient resource or reference as one of the parameters, is a Patient Record event as defined in Table 3.20.4.1.1.1-1. The actors involved SHALL record audit events according to the following:

##### 2:3.115.6.1.1 Client Audit

The Scheduling Client, when grouped with the ATNA Secure Node or Secure Application Actor, SHALL be able to record an audit event consistent with the Find Potential Appointments Source AuditEvent. Audit Example for a Find Potential Appointments transaction from the client perspective.

##### 2:3.115.6.1.2 Server Audit

The Scheduling Server, when grouped with the ATNA Secure Node or Secure Application Actor, SHALL be able to record an audit event consistent with the Book Potential Appointments Recipient AuditEvent. Audit Example for a Find Potential Appointments transaction from the server perspective.

### 2:3.115.7 Other Profile Groupings

Both the Scheduling Client and Scheduling Server MAY be grouped with their respective Internet User Authentication (IUA) Actors.