Scheduling
1.0.0 - Trial-Implementation
Scheduling
1.0.0 - Trial-Implementation
This page is part of the IHE ITI Scheduling (v1.0.0: Publication) 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
| Active as of 2024-12-12 |
<OperationDefinition xmlns="http://hl7.org/fhir">
<id value="appointment-find"/>
<text>
<status value="generated"/>
<div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationDefinition appointment-find</b></p><a name="appointment-find"> </a><a name="hcappointment-find"> </a><a name="appointment-find-en-US"> </a><p>URL: [base]/Appointment/$find</p><h3>Parameters</h3><table class="grid"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>start</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#dateTime">dateTime</a></td><td/><td><div><p>The period of time that SHOULD be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no start date is provided, all available appointments prior to the end date are in scope (subject to limits imposed by local business rules).</p>
</div></td></tr><tr><td>IN</td><td>end</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#dateTime">dateTime</a></td><td/><td><div><p>The period of time that SHOULD be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no end date is provided, all available appointments after the start date are in scope (subject to limits imposed by local business rules).</p>
</div></td></tr><tr><td>IN</td><td>specialty</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a><br/>(<a href="http://hl7.org/fhir/R4/search.html#token">token</a>)</td><td>https://profiles.ihe.net/ITI/SCHED/ValueSet/specialty (Example)</td><td><div><p>The code for which specialty is requested for the appointment. ( e.g., 'Dermatology'). If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors). Each parameter value SHALL contain <em>both</em> the system property and the code property for a code using the general syntax <code>specialty=[system]|[code]</code>. See the examples below for how this is implemented.</p>
</div></td></tr><tr><td>IN</td><td>visit-type</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a><br/>(<a href="http://hl7.org/fhir/R4/search.html#token">token</a>)</td><td>https://profiles.ihe.net/ITI/SCHED/ValueSet/visit-type (Example)</td><td><div><p>The code for one of the common appointment visit types for scheduling. ( e.g.,'Echocardiography' or 'Well child visit' ). This list of visit types is extensible and implementers MAY choose to add there own codes. If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these services (i.e. this does not drive joint appointment with multiple services). Each parameter value SHALL contain <em>both</em> the system property and the code property for a code using the general syntax <code>service-type=[system]|[code]</code>. See the examples below for how this is implemented.</p>
</div></td></tr><tr><td>IN</td><td>practitioner</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a> (<a href="http://hl7.org/fhir/R4/practitioner.html" title="http://hl7.org/fhir/StructureDefinition/Practitioner">Practitioner</a>)</td><td/><td><div><p>The Practitioner reference when performing a provider based query. This is a reference to a FHIR Practitioner resource, e.g. 'Practitioner/123'. If multiple practitioner references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors).</p>
</div></td></tr><tr><td>IN</td><td>organization</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a> (<a href="http://hl7.org/fhir/R4/organization.html" title="http://hl7.org/fhir/StructureDefinition/Organization">Organization</a>)</td><td/><td><div><p>The Organization reference when performing a provider based query. This is a reference to a FHIR Organization resource, e.g. 'Organization/abc'. If multiple organization references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors).</p>
</div></td></tr><tr><td>IN</td><td>location-string</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a><br/>(<a href="http://hl7.org/fhir/R4/search.html#string">string</a>)</td><td/><td><div><p>A (part of the) address of the location of interest. (e.g., zip codes, city or state). This string parameter is interpreted as a <a href="https://hl7.org/fhir/R4/search.html#string">String search parameter</a> and covers the <code>string</code> type elements in the <a href="https://hl7.org/fhir/R4/datatypes.html#Address">Address datatype</a>. If multiple locations are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)</p>
</div></td></tr><tr><td>IN</td><td>location-reference</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a> (<a href="http://hl7.org/fhir/R4/location.html" title="http://hl7.org/fhir/StructureDefinition/Location">Location</a>)</td><td/><td><div><p>A Location reference when performing an operation where the Location resource <code>id</code> is known. If multiple location references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)</p>
</div></td></tr><tr><td>IN</td><td>patient-reference</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a> (<a href="http://hl7.org/fhir/R4/patient.html" title="http://hl7.org/fhir/StructureDefinition/Patient">Patient</a>)</td><td/><td><div><p>A Patient reference when performing an operation where the Patient resource <code>id</code> is known. Patient resources include demographics and patient preferences that could be important for availability searches. If multiple patient references are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment.</p>
</div></td></tr><tr><td>IN</td><td>patient-resource</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/patient.html">Patient</a> (<a href="http://hl7.org/fhir/R4/patient.html" title="http://hl7.org/fhir/StructureDefinition/Patient">Patient</a>)</td><td/><td><div><p>This parameter uses the Patient resource type instead of a simple reference because it is possible for the patient record to not exist when performing availability searches. (If the Patient resource id is known, use the <code>patient-reference</code> parameter instead.) If the appointment is for a new patient, the patient record SHOULD NOT be created until just before booking an appointment. If multiple patient resources are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment.</p>
</div></td></tr><tr><td>IN</td><td>reason</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a><br/>(<a href="http://hl7.org/fhir/R4/search.html#token">token</a>)</td><td><a href="http://hl7.org/fhir/R4/valueset-condition-code.html">Condition/Problem/Diagnosis Codes</a> (Preferred)</td><td><div><p>A clinical sign, symptom, diagnosis or health concern that this appointment is intended to treat. This MAY is used in conjunction with the specialty to determine which schedulable resources are needed for the visit. For example, for an orthopedics appointment, the reason could drive whether a hip specialist or knee specialist is preferred. Each parameter value SHALL contain both the system property and the code property for a code using the general syntax <code>specialty=[system]|[code]</code>. See the examples below for how this is implemented.</p>
</div></td></tr><tr><td>IN</td><td>referral-identifier</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#Identifier">Identifier</a></td><td/><td><div><p>When an appointment needs to be made as part of a referral, this parameter can contain the ServiceRequest identifier for the referral.</p>
</div></td></tr><tr><td>IN</td><td>timing</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#Timing">Timing</a></td><td/><td><div><p>Provides information about the preferred times for the appointment</p>
</div></td></tr><tr><td>IN</td><td>insurance-reference</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a> (<a href="http://hl7.org/fhir/R4/insuranceplan.html" title="http://hl7.org/fhir/StructureDefinition/InsurancePlan">InsurancePlan</a>)</td><td/><td><div><p>Reference to the insurance information for the patient for whom the potential appointment is about to be made.</p>
</div></td></tr><tr><td>OUT</td><td>return</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/bundle.html">Bundle</a> (<a href="StructureDefinition-ihe-sched-avail-bundle.html" title="https://profiles.ihe.net/ITI/Scheduling/StructureDefinition/ihe-sched-avail-bundle">IHE ITI Scheduling Bundle Profile</a>)</td><td/><td><div><p>An <a href="StructureDefinition-ihe-sched-avail-bundle.html">IHE Appointment Bundle Profile</a> of type <code>searchset</code> with entries of proposed <a href="https://hl7.org/fhir/R4/appointment.html">Appointment</a> resources and MAY also contain an <a href="https://hl7.org/fhir/R4/operationoutcome.html">OperationOutcome</a> with errors, warnings or information as a result of processing the operation - e.g., an informational notice that the returned appointments are not within the requested start and end times. An empty bundle means no available appointments based on inputs</p>
</div></td></tr></table><div><ul>
<li>For input parameters that are codes, the simple FHIR <a href="https://hl7.org/fhir/R4/search.html#token">token</a> search parameter type is used instead of the complex <code>Coding</code> datatype. This allows either the 'GET' or the 'POST' syntax to be used to initiate the interaction in many cases. The <code>Reference</code> datatype is used for resources references, which allows the requester to use either a reference to existing resource, or an identifier (<a href="https://hl7.org/fhir/R4/references-definitions.html#Reference.identifier">logical reference</a>). Examples of both are shown below.</li>
<li>If multiple patients are provided as parameters, this conveys the need for a group appointment.</li>
<li>If more than one non-patient participant type of parameter is present (e.g. a Provider and a Location), the response SHOULD contain appointments with <em>all</em> of these participants (i.e, this is a logical 'AND'). If a particular participant type is repeated, the response SHOULD contain appointments with <em>any</em> of these participants and SHOULD be interpreted as the order of preference (i.e. this is a logical 'OR' and does not drive a joint appointment with multiple practitioners. locations or organizations). Ultimately the server is responsible for determining the first/best available appointment options to return.</li>
<li>References can be to an absolute URL, but the Scheduling Server can create or modify resources only on the resources on the server or a defined domain.</li>
<li>To set the upper limit on the total number of available appointment options to return use the standard <a href="https://hl7.org/fhir/R4/search.html#count"><code>_count</code></a> search parameter. See the examples below for how this is implemented.</li>
<li>The Scheduling Server SHALL NOT include any held appointments (i.e. appointments that were reserved as a result of a previous <code>$hold</code> operation, and for which the holding period had not expired) in the list of potential appointments.</li>
</ul>
</div></div>
</text>
<url
value="https://profiles.ihe.net/ITI/Scheduling/OperationDefinition/appointment-find"/>
<version value="1.0.0"/>
<name value="Find_Appointments_Operation"/>
<status value="active"/>
<kind value="operation"/>
<date value="2024-12-12"/>
<publisher value="IHE IT Infrastructure Technical Committee"/>
<contact>
<telecom>
<system value="url"/>
<value value="https://www.ihe.net/ihe_domains/it_infrastructure/"/>
</telecom>
</contact>
<contact>
<telecom>
<system value="email"/>
<value value="iti@ihe.net"/>
</telecom>
</contact>
<contact>
<name value="IHE IT Infrastructure Technical Committee"/>
<telecom>
<system value="email"/>
<value value="iti@ihe.net"/>
</telecom>
</contact>
<description
value="Searches for availability for a future appointment(s) within a time period of defined by date range input parameters. If neither a start or end date is given then the maximum period as defined by local business rules and starting from when the operation was transacted will be used. Other input parameters further refine the search and include practitioner references, specialties, visit type, locations, patient and referral information. From these criteria, a system determines which schedulable resources ( e.g., people, rooms, equipment) are needed for the visit, and provides proposed appointments for the time slots where all required resources are available."/>
<jurisdiction>
<coding>
<system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/>
<code value="001"/>
</coding>
</jurisdiction>
<code value="find"/>
<comment
value="- For input parameters that are codes, the simple FHIR [token](https://hl7.org/fhir/R4/search.html#token) search parameter type is used instead of the complex `Coding` datatype. This allows either the 'GET' or the 'POST' syntax to be used to initiate the interaction in many cases. The `Reference` datatype is used for resources references, which allows the requester to use either a reference to existing resource, or an identifier ([logical reference](https://hl7.org/fhir/R4/references-definitions.html#Reference.identifier)). Examples of both are shown below.
- If multiple patients are provided as parameters, this conveys the need for a group appointment.
- If more than one non-patient participant type of parameter is present (e.g. a Provider and a Location), the response SHOULD contain appointments with *all* of these participants (i.e, this is a logical 'AND'). If a particular participant type is repeated, the response SHOULD contain appointments with *any* of these participants and SHOULD be interpreted as the order of preference (i.e. this is a logical 'OR' and does not drive a joint appointment with multiple practitioners. locations or organizations). Ultimately the server is responsible for determining the first/best available appointment options to return.
- References can be to an absolute URL, but the Scheduling Server can create or modify resources only on the resources on the server or a defined domain.
- To set the upper limit on the total number of available appointment options to return use the standard [`_count`](https://hl7.org/fhir/R4/search.html#count) search parameter. See the examples below for how this is implemented.
- 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."/>
<resource value="Appointment"/>
<system value="false"/>
<type value="true"/>
<instance value="false"/>
<parameter>
<name value="start"/>
<use value="in"/>
<min value="1"/>
<max value="1"/>
<documentation
value="The period of time that SHOULD be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no start date is provided, all available appointments prior to the end date are in scope (subject to limits imposed by local business rules)."/>
<type value="dateTime"/>
</parameter>
<parameter>
<name value="end"/>
<use value="in"/>
<min value="1"/>
<max value="1"/>
<documentation
value="The period of time that SHOULD be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no end date is provided, all available appointments after the start date are in scope (subject to limits imposed by local business rules)."/>
<type value="dateTime"/>
</parameter>
<parameter>
<name value="specialty"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="The code for which specialty is requested for the appointment. ( e.g., 'Dermatology'). If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors). Each parameter value SHALL contain *both* the system property and the code property for a code using the general syntax `specialty=[system]|[code]`. See the examples below for how this is implemented."/>
<type value="string"/>
<searchType value="token"/>
<binding>
<strength value="example"/>
<valueSet
value="https://profiles.ihe.net/ITI/SCHED/ValueSet/specialty"/>
</binding>
</parameter>
<parameter>
<name value="visit-type"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="The code for one of the common appointment visit types for scheduling. ( e.g.,'Echocardiography' or 'Well child visit' ). This list of visit types is extensible and implementers MAY choose to add there own codes. If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these services (i.e. this does not drive joint appointment with multiple services). Each parameter value SHALL contain *both* the system property and the code property for a code using the general syntax `service-type=[system]|[code]`. See the examples below for how this is implemented."/>
<type value="string"/>
<searchType value="token"/>
<binding>
<strength value="example"/>
<valueSet
value="https://profiles.ihe.net/ITI/SCHED/ValueSet/visit-type"/>
</binding>
</parameter>
<parameter>
<name value="practitioner"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="The Practitioner reference when performing a provider based query. This is a reference to a FHIR Practitioner resource, e.g. 'Practitioner/123'. If multiple practitioner references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors)."/>
<type value="Reference"/>
<targetProfile
value="http://hl7.org/fhir/StructureDefinition/Practitioner"/>
</parameter>
<parameter>
<name value="organization"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="The Organization reference when performing a provider based query. This is a reference to a FHIR Organization resource, e.g. 'Organization/abc'. If multiple organization references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors)."/>
<type value="Reference"/>
<targetProfile
value="http://hl7.org/fhir/StructureDefinition/Organization"/>
</parameter>
<parameter>
<name value="location-string"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="A (part of the) address of the location of interest. (e.g., zip codes, city or state). This string parameter is interpreted as a [String search parameter](https://hl7.org/fhir/R4/search.html#string) and covers the `string` type elements in the [Address datatype](https://hl7.org/fhir/R4/datatypes.html#Address). If multiple locations are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)"/>
<type value="string"/>
<searchType value="string"/>
</parameter>
<parameter>
<name value="location-reference"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="A Location reference when performing an operation where the Location resource `id` is known. If multiple location references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)"/>
<type value="Reference"/>
<targetProfile value="http://hl7.org/fhir/StructureDefinition/Location"/>
</parameter>
<parameter>
<name value="patient-reference"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="A Patient reference when performing an operation where the Patient resource `id` is known. Patient resources include demographics and patient preferences that could be important for availability searches. If multiple patient references are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment."/>
<type value="Reference"/>
<targetProfile value="http://hl7.org/fhir/StructureDefinition/Patient"/>
</parameter>
<parameter>
<name value="patient-resource"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="This parameter uses the Patient resource type instead of a simple reference because it is possible for the patient record to not exist when performing availability searches. (If the Patient resource id is known, use the `patient-reference` parameter instead.) If the appointment is for a new patient, the patient record SHOULD NOT be created until just before booking an appointment. If multiple patient resources are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment."/>
<type value="Patient"/>
<targetProfile value="http://hl7.org/fhir/StructureDefinition/Patient"/>
</parameter>
<parameter>
<name value="reason"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="A clinical sign, symptom, diagnosis or health concern that this appointment is intended to treat. This MAY is used in conjunction with the specialty to determine which schedulable resources are needed for the visit. For example, for an orthopedics appointment, the reason could drive whether a hip specialist or knee specialist is preferred. Each parameter value SHALL contain both the system property and the code property for a code using the general syntax `specialty=[system]|[code]`. See the examples below for how this is implemented."/>
<type value="string"/>
<searchType value="token"/>
<binding>
<strength value="preferred"/>
<valueSet value="http://hl7.org/fhir/ValueSet/condition-code"/>
</binding>
</parameter>
<parameter>
<name value="referral-identifier"/>
<use value="in"/>
<min value="0"/>
<max value="1"/>
<documentation
value="When an appointment needs to be made as part of a referral, this parameter can contain the ServiceRequest identifier for the referral."/>
<type value="Identifier"/>
</parameter>
<parameter>
<name value="timing"/>
<use value="in"/>
<min value="0"/>
<max value="1"/>
<documentation
value="Provides information about the preferred times for the appointment"/>
<type value="Timing"/>
</parameter>
<parameter>
<name value="insurance-reference"/>
<use value="in"/>
<min value="0"/>
<max value="*"/>
<documentation
value="Reference to the insurance information for the patient for whom the potential appointment is about to be made."/>
<type value="Reference"/>
<targetProfile
value="http://hl7.org/fhir/StructureDefinition/InsurancePlan"/>
</parameter>
<parameter>
<name value="return"/>
<use value="out"/>
<min value="0"/>
<max value="1"/>
<documentation
value="An [IHE Appointment Bundle Profile](StructureDefinition-ihe-sched-avail-bundle.html) of type `searchset` with entries of proposed [Appointment](https://hl7.org/fhir/R4/appointment.html) resources and MAY also contain an [OperationOutcome](https://hl7.org/fhir/R4/operationoutcome.html) with errors, warnings or information as a result of processing the operation - e.g., an informational notice that the returned appointments are not within the requested start and end times. An empty bundle means no available appointments based on inputs"/>
<type value="Bundle"/>
<targetProfile
value="https://profiles.ihe.net/ITI/Scheduling/StructureDefinition/ihe-sched-avail-bundle"/>
</parameter>
</OperationDefinition>
IG © 2024+ IHE IT Infrastructure Technical Committee. Package ihe.iti.scheduling#1.0.0 based on FHIR 4.0.1. Generated 2024-12-12
Links: Table of Contents |
QA Report
| New Issue | Issues
Version History |
|
Propose a change