This page is part of the IHE ITI Scheduling (v1.0.0-comment: Publication Ballot 1) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions

2:3.118 Find Existing Appointments [ITI-118]

This section corresponds to transaction [ITI-118] of the IHE Technical Framework. Transaction [ITI-118] is used by the Scheduling Client and Scheduling Server Actors. The Find Existing Appointments [ITI-118] transaction is used to search for existing appointments on the server.

2:3.118.1 Scope

The Client [ITI-118] transaction requests a list of existing appointments from a Server for a particular patient.

2:3.118.2 Actor Roles

Table 2:3.118.2-1: Actor Roles

Actor	Role
Client	Requests a list of appointments matching the supplied set of criteria (example: status, patient, service location, etc.) from the Scheduling Server. The Scheduling Client MAY choose to persist the information received, and/or render it for viewing
Server	Returns information from appointments matching the supplied set of criteria provided by the Scheduling Client

2:3.118.3 Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0 - Appointment

2:3.118.4 Messages

Figure 2:3.118.4-1: Find Existing Appointments Interactions

2:3.118.4.1 Find Existing Appointments Query Request

This message uses the FHIR Search operation on the target Server endpoint to search for Appointment resources.

2:3.118.4.1.1 Trigger Events

When a Scheduling Client needs to needs to find existing appointments it issues a Find Existing Appointments query request.

2:3.118.4.1.2 Message Semantics

The Scheduling Client MAY use a GET or POST based search. The Scheduling Server SHALL support both GET and POST based searches. The search target follows the FHIR http specification, addressing the Appointment Resource type.

[base]/Appointment?<parameters>

2:3.118.4.1.3 Search Parameters

See the Server and Client Capability Statements for the search parameters applicable to the [ITI-18] transaction.

Table 2:3.118.4.1.2-1: Search Parameters

Parameter	Type	Definition
patient	reference	This parameter identifies the patient actor participating in this appointment either by its fhir resource id (if known to the Scheduling Client), or by a business identifier known for this patient. In case of a business identifier it is strongly recommended to use both the identifying system and value (i.e. patient.identifier=<system>|<value>). If no <system> is supplied the Scheduling Server MAY use internal logic to interpret the <value>
date	date	This parameter defines the date range to search for appointments. Normal date prefixes apply.
practitioner	reference	This parameter identifies the practitioner actor participating in this appointment either by its fhir resource id (if known to the Scheduling Client), or by a business identifier known for this practitioner. In case of a business identifier it is strongly recommended to use both the identifying system and value (i.e. practitioner.identifier=<system>|<value>). If no <system> is supplied the Scheduling Server MAY use internal logic to interpret the <value>
status	token	This parameter reflects the overall status of the appointment as defined in AppointmentStatus
location	reference	This parameter identifies the location actor participating in this appointment either by its fhir resource id (if known to the Scheduling Client), or by a name known for this location.
specialty	token	This parameter identifies the specialty of a practitioner that would be required to perform the service requested in this appointment

For example, search appointments for patient (identifier 12345), after October 21st, 2023 with practitioner (npi number: 12345678) GET https://server.example.com/fhir/4/Appointment?patient.identifier=urn:oid:1.2.3.4.5|12345&date=gt20231021&practitioner.identifier=urn:oid:2.16.840.1.113883.4.6|12345678

2:3.118.4.1.3.1 Patient Identifiers

Patient identifier SHALL be fully qualified and consist of an identifier value and system (a.k.a. assigning authority or patient identity domain). Preferably identifier systems are identified with an OID value (e.g. urn:oid:1.2.3.4.5). Alternatively a URI value MAY be used (e.g. http://hl7.org/fhir/sid/us-ssn or http://hospital-1.org).

In the case when the Scheduling Server is not able to process a identifier system in a Find Existing Appointments Query transaction it SHALL return a FHIR bundle of type searchset with 0 entries.

The case where the Scheduling Client mey need to provided multiple patient.identifiers, all belonging to the same patient as known to the client, is considered out of scope for the ITI Scheduling Profile.

2:3.118.4.1.3.2 _count

A Scheduling Client MAY add a _count parameter to the Find Appointment Query request to limit the number of responses.

2:3.118.4.1.3.3 _include

A Scheduling Client MAY add a _include parameter to request a Scheduling Server to include participation actors (Practitioner, PractitionerRole, RelatedPerson, Device, HealthcareService, or Location) in the response

2:3.118.4.1.4 Expected Actions

Table 2:3.118.4.1.4-1: Search parameter optionality

Parameter	Client	Server
patient	R	R
date	O	R
practitioner	O	O
location	O	O
specialty	O	O

The table above identifies the search parameters that are optional or mandatory to support for both the Scheduling Client and Scheduling Server. In case a Scheduling Client issues a request with no parameters included the Scheduling Server MAY determine how to respond. For example, a valid response in such case would be a FHIR Bundle of type 'searchset' with zero entries, and including an operationOutcome stating it needs a minimal set of search parameters to be defined in the search request.

2:3.118.4.2 Find Appointments Query Response

2:3.118.4.2.1 Trigger Events

The Scheduling Server has results or errors to report to the Scheduling Client. This MAY include 0, 1 or more appointments matching the search parameters specified by the Scheduling Client as a result of the Find Appointment Query request. This MAY include processing or security errors.

2:3.118.4.2.2 Message Semantics

The Find Appointments Query response sent from the Scheduling Server to the Scheduling Client consists of a FHIR Bundle of type searchset.

To limit the number of Appointment entries in the response bundle a Scheduling Server MAY choose to use pagination.

The Scheduling Server SHALL add a total attribute indicating the total number of appointments that match the Find Appointments Query request.

2:3.118.4.2.3 Expected Actions

The Scheduling Server will make a best effort to add as many Appointment resource attributes in each Appointment entry returned.

The Scheduling Server SHALL honour the _count request parameter when included in the Find Appointments Query request by a Scheduling Client

The Scheduling Server SHALL honour the _include request parameter for referenced participating actors (Practitioner, PractitionerRole, RelatedPerson, Device, HealthcareService, and Location) when included in the Find Appointments Query request by a Scheduling Client.

2:3.118.4.2.4 Error Codes

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

In case security constraints prevent a Scheduling Server from returning a response to the Scheduling Client a http 4xx error code is returned as described in Volume 2, Appendix Z.

Table 2:3.118.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.118.4.2.4-2: OperationOutcome Attributes

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

2:3.118.5 Security Considerations

See the general Security Considerations in ITI TF-1: 38.5.

2:3.118.5.1 Security Audit Considerations

Both the Scheduling Server as Scheduling Client SHALL record audit events.

2:3.118.5.1.1 Scheduling Client Audit

The Scheduling Client SHALL be grouped with an ATNA Secure Node or Secure Application (ATNA) Actor, and record a Find Appointment Query request according to the BALP basic profile for REST events - Execute as defined in RESTful activities.

2:3.118.5.1.2 Scheduling Server Audit

The Scheduling Server SHALL be grouped with an ATNA Secure Node or Secure Application (ATNA) Actor, and record a Find Appointment Query request according to the BALP basic profile for REST events - Execute as defined in RESTful activities.

2:3.118.6 Other Profile Groupings

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