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

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.

Actors Roles

Table: Actor Roles

Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0

Interactions

Figure: Find Potential Appointments Interactions

Find Potential Appointments request

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

Trigger Events

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

Message Semantics

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

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.

'’TODO: discuss the Organization parameter. A FHIR Appointment Resource does not include an Organization reference. Hence, it may not be possible to use it as a search parameter. Since a location is always linked to an organization ‘’

Example: GET In case the Scheduling Client uses a GET method it the search parameters are added to the request URL like:

[base]/Appointment/$find?practitioner.identifier=urn:oid:2.16.840.1.113883.4.6|1234567&start=2023-10-30&end=2023-11-30

Example: POST In case the Scheduling Client uses a POST method it is expected to add the search parameters to the request payload like:

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.identifier",
        "valueIdentifier: "urn:oid:2.16.840.1.113883.4.6|1234567"
    }]
}

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 shall support FHIR Pagination when the Scheduling Server paginates its response.

Find Potential Appointments Response Message

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.

Message Semantics

The list of potential appointments is returned as a FHIR Bundle of type searchsetis returned containing 0, 1 or more Appointment resources

'’TODO: include IHE ITI Appointment Bundle Profile ‘’

Expected Actions

The Scheduling Server shall make a best effort to find potential Appointments. Each Appointment resource included in the response Bundle should me as complete as possible allowing the Scheduling Client to render the appointment information in such a way a (human) user is able to reserver 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.

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: Error Codes

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

Table: OperationOutcome Attributes

CapabilityStatement Resource

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

Security Considerations

See MHD Security Considerations

Security Audit Considerations

'’TODO: The security audit criteria ‘’

Client Audit

'’TODO: the specifics’’

Server Audit

'’TODO: the specifics’’