The Appointment Booking Process¶

Introduction¶

Appointment Booking is done using the Appointment Booking Engine (ABE). Note that this is a different application to the Dynamic Scheduling Engine (DSE), although the two work closely together.

If you simply wish to schedule activities at the most efficient times, then just send ordinary activities to the DSE. Appointment Booking should only be used when you want to consider putting an activity in several different time slots, and see which slots are possible and also which are the most cost-effective.

Both Appointment Requests and ordinary activities etc. are supplied using the standard Scheduling Schema XML. A single input XML file may contain both ordinary activities and appointment booking records.

The purpose of the Appointment Booking Engine is to quickly estimate whether an activity is likely to be scheduled, were it to be sent to the DSE with an availability constrained to a specific time slot. The Appointment Booking Engine is designed to give a quick response to appointment requests (typically within a few seconds), but this is at the expense of accuracy: a small proportion of appointment offers may be made which then cannot be scheduled subsequently by the DSE. This is because the ABE makes its decisions based on the latest DSE plan, which may be a few seconds out of date.

It is therefore important for the external application to check, once an appointment has been offered and accepted, that the activity is scheduled by the DSE within the next few minutes. If any accepted activities are not scheduled by the DSE, these should be raised as exceptions in the external application, and the appointment rearranged manually.

It is important to note that, whilst the DSE schedules activities to specific resources, the ABE does not give appointments for specific resources. The ABE is trying to determine whether the organisation has sufficient capacity to take an appointment at a certain time - it is not producing an optimised schedule that will determine exactly which resource to allocate to an activity.

The basic appointment booking process is described below:

1. The service-management system sends an Appointment Request to the scheduling system.
2. The Appointment Booking Engine replies with zero or more Appointment Offers
3. Non Blocking Requests Only: The service-management system accepts one of these offers using an Appointment Offer Response record. At this point no other changes should be made to the input data, and the input_updated flag on the response should be set to false.
4. Non Blocking Requests Only: The Appointment Booking Engine will now verify that the chosen slot is still available and return an Appointment_Summary record to confirm or otherwise. If the offer is no longer valid, the appointment booking process should be restarted.
5. The external system now confirms the offer the customer wishes to accept using an Appointment Offer Response record. At the same time, the external system must raise the value of the activity and constrain it to the appointment time.
6. The external system checks on all accepted appointments to ensure that they remain scheduled in the DSE. Any that drop out of the schedule must be manually resolved.

The Scheduling Window¶

A common business scenario is for appointments to be booked at any time in the next three months, say, but also there is a requirement for the schedule for the next 2 days (containing accepted appointments, and maybe other types of work as well) to be fully optimised.

The DSE and the ABE need to be thinking about the same time period, and in the example above this period is 3 months. However, the DSE does not need to be optimising the whole 3 months of activities - to do so would slow it down considerably. It merely needs to optimise the next 2 days, and be aware of the accepted appointments for the next three months.

The way to specify this is to specify in the Input_Reference record a "duration" of 2 days (for full optimisation by the DSE) and an "appointment_window_duration" of 89 days, representing the remaining period in which appointment booking will occur. Note that this gives a total period of 91 days, which is approximately three months.

The ABE may offer appointments during any of the period, i.e. in the example above, appointments can be offered on any of the 91 days. This may of course be constrained by the appointment slots requested in the Appointment_Request record.

How to Send Appointment Booking Requests¶

Appointment booking requests are specified using three records from the Scheduling Schema:

• Appointment_Request - this specifies the request.
• Activity - this is a template activity specifying all the constraints for the appointment
• Appointment_Template - this specifies which time slots to request, how long to hold the slots for, and other details.

For example:

<dsScheduleDataxmlns="http://360Scheduling.com/Schema/dsScheduleData.xsd">
    <Input_Reference>
        <id>1</id>
        <datetime>2006-01-01T08:00:01</datetime>
        <input_type>CHANGE</input_type>
    </Input_Reference>
    <Activity>
        <id>271</id>
        <activity_class_id>CALL</activity_class_id>
        <activity_type_id>REPAIR</activity_type_id>
        <location_id>271</location_id>
        <priority>1</priority>
        <split_allowed>false</split_allowed>
    </Activity>
    <Location>
        <id>271</id>
        <latitude>52.5220264342716</latitude>
        <longitude>-2.1123596677329</longitude>
        <post_code_zip/>
    </Location>
    <Activity_Status>
        <activity_id>271</activity_id>
        <status_id>0</status_id>
        <visit_id>1</visit_id>
        <date_time_stamp>2006-01-01T08:00:00</date_time_stamp>
        <date_time_status>2006-01-01T08:00:00</date_time_status>
        <duration>PT1H00M</duration>
    </Activity_Status>
    <Activity_SLA>
        <sla_type_id>PM</sla_type_id>
        <activity_id>271</activity_id>
        <datetime_start>2006-01-01T08:00:00</datetime_start>
        <datetime_end>2006-02-06T09:00:00</datetime_end>
    </Activity_SLA>
    <Appointment_Request>
        <id>819234</id>
        <activity_id>271</activity_id>
        <offer_expiry_datetime>2006-01-01T08:05:01</offer_expiry_datetime>
        <appointment_template_id>AT1</appointment_template_id>
        <appointment_template_datetime>2006-01-01T08:00:01</appointment_template_datetime>
        <appointment_template_duration>P14D</appointment_template_duration>
    </Appointment_Request>
    <Appointment_Template>
        <id>AT1</id>
        <day_pattern>YYYYYNN</day_pattern>
        <number_of_slots>100</number_of_slots>
        <appointment_window_length>PT1H</appointment_window_length>
        <granularity>PT15M</granularity>
        <minimum_delay>P0D</minimum_delay>
        <template_start_day_of_week>0</template_start_day_of_week>
        <template_start_time_of_day>PT9H</template_start_time_of_day>
        <exclude_to_template_start>false</exclude_to_template_start>
        <start_based>true</start_based>
        <offer_expiry_window>PT5M</offer_expiry_window>
        <default_template>false</default_template>
        <description>Two hour slots</description>
    </Appointment_Template>
    <Appointment_Template_Item>
        <appointment_template_id>AT1</appointment_template_id>
        <slot_start_time>PT8H</slot_start_time>
        <slot_end_time>PT10H</slot_end_time>
    </Appointment_Template_Item>
    <Appointment_Template_Item>
        <appointment_template_id>AT1</appointment_template_id>
        <slot_start_time>PT10H</slot_start_time>
        <slot_end_time>PT12H</slot_end_time>
    </Appointment_Template_Item>
    <Appointment_Template_Item>
        <appointment_template_id>AT1</appointment_template_id>
        <slot_start_time>PT13H</slot_start_time>
        <slot_end_time>PT15H</slot_end_time>
    </Appointment_Template_Item>
    <Appointment_Template_Item>
        <appointment_template_id>AT1</appointment_template_id>
        <slot_start_time>PT15H</slot_start_time>
        <slot_end_time>PT17H</slot_end_time>
    </Appointment_Template_Item>
</dsScheduleData>

Updates to the schedule should always be made using a CHANGE input type. Just like other scheduling data, Appointment Requests and Offers are cleared out when a new initial load is received.

Non-blocking Appointment Requests¶

The ABE blocks out time for appointment slots when it is assessing an appointment request. This can lead to slots being returned as unavailable because they have been blocked out by previous outstanding requests or earlier slots within the same request. For example if two different appointment requests have a slot at the same time only one will get an appointment offer the other will be unavailable. This can happen more often when using linked calls due to the linked call from the previous slot blocking time. This can stop the linked calls from being allocated in the following slots. In cases where this is particularly bad it can be more useful to request a non-blocking appointment.

To make a request non-blocking the blocking attribute should be set to false on either the appointment request or the appointment template:

<Appointment_Request>
    <id>819234</id>
    <activity_id>271</activity_id>
    <offer_expiry_datetime>2006-01-01T08:05:01</offer_expiry_datetime>
    <appointment_template_id>AT1</appointment_template_id>
    <appointment_template_datetime>2006-01-01T08:00:01</appointment_template_datetime>
    <appointment_template_duration>P14D</appointment_template_duration>
</Appointment_Request>
<Appointment_Template>
    <id>AT1</id>
    <day_pattern>YYYYYNN</day_pattern>
    <number_of_slots>100</number_of_slots>
    <appointment_window_length>PT1H</appointment_window_length>
    <granularity>PT15M</granularity>
    <minimum_delay>P0D</minimum_delay>
    <template_start_day_of_week>0</template_start_day_of_week>
    <template_start_time_of_day>PT9H</template_start_time_of_day>
    <exclude_to_template_start>false</exclude_to_template_start>
    <start_based>true</start_based>
    <offer_expiry_window>PT5M</offer_expiry_window>
    <default_template>false</default_template>
    <description>Two hour slots</description>
    <blocking>false</blocking>
</Appointment_Template>

Configuring Appointment Request Times¶

There are several attributes that can be used to configure which slots are considered and how slot usage rules are applied.

When using appointment templates, the appointment_template_datetime on the appointment request can be set to specify when slots will first be considered from. If the appointment_template_datetime has not been specified then the appointment_base_datetime will be used for this purpose. If this has also not been specified then the current schedule time is used.

For example, to only consider slots starting next week, the appointment_template_datetime should be set to midnight on the Monday of that week.

The attribute appointment_base_datetime on the appointment request allows the user to change the base time used when applying slot usage rules and a minimum delay (specified on the appointment template). If the appointment_base_datetime has not been specified then the current schedule time is used.

For example, to apply slot usage rules consistently throughout the day, the appointment_base_datetime should be set to midnight of the current day.

Appointment Offer Broadcasts¶

In broadcast requests, it is possible to choose DSE output, ABE output, or both.

DSE output includes all the Allocation records and normal scheduling output; whilst ABE output includes Appointment Offers only.

The default is for broadcasts to broadcast both types of output.

To specify this option, include the attribute 'alloction_type' in the Broadcast request:

<Broadcast>
  <id>BroadcastAppointment</id>
  <broadcast_type_id>FILE</broadcast_type_id>
  <plan_type>CHANGE</plan_type>
  <allocation_type>2</allocation_type>
</Broadcast>

The parameter value should be chosen as follows:

1 = DSE output only
2 = ABE output only
3 = Both DSE and ABE output

Output from the Appointment Booking Engine¶

The result of an appointment request such as the one above will be a number of appointment offer records in the scheduling output XML: one for each slot requested. If an offer can be made for a slot, then an appointment offer record will be created with element "available" set to "true", and a time slot of the requested duration will be specified in the offer_start_datetime and offer_end_datetime. If an offer cannot be made, then an appointment offer record will be created with element "available" set to "false", and the offer_start_datetime and offer_end_datetime will be set to the start and end times of the requested slot.

An Appointment Offer record looks like this:

<Appointment_Offer>
    <appointment_request_id>819234</appointment_request_id>
    <id>7</id>
    <offer_start_datetime>2006-01-03T15:00:00+00:00</offer_start_datetime>
    <offer_end_datetime>2006-01-03T16:00:00+00:00</offer_end_datetime>
    <offer_value>2615.3742633269112</offer_value>
    <plan_id>3376</plan_id>
    <available>true</available>
    <reason_type_id>0</reason_type_id>
    <window_start_datetime>2006-01-03T15:00:00+00:00</window_start_datetime>
    <window_end_datetime>2006-01-03T17:00:00+00:00</window_end_datetime>
    <prospective_allocation_start>2006-01-03T15:23:40+00:00</prospective_allocation_start>
    <prospective_resource_id>R1001</prospective_resource_id>
</Appointment_Offer>

Accepting an Appointment Offer¶

Following an appointment offer, the service-management system must accept the offer within a specified timeout period (specified in the appointment request offer_expiry_datetime sent previously). To accept an offer, send an appointment offer response

Appointment Offer Responses should always be made using a CHANGE input type.

Accepting an Offer - Blocking Requests¶

For blocking appointment requests the appointment offer should be accepted and the input data updated at the same time:

<Appointment_Offer_Response>
    <appointment_request_id>819234</appointment_request_id>
    <appointment_offer_id>7</appointment_offer_id>
    <input_updated>true</input_updated>
</Appointment_Offer_Response>
<Availability>
    <id>6102</id>
    <datetime_start>2006-01-03T15:00:00</datetime_start>
    <datetime_end>2006-01-03T17:00:00</datetime_end>
    <activity_id>271</activity_id>
    <start_based>true</start_based>
    <availability_type>ACCEPTED_APPOINTMENT</availability_type>
</Availability>
<Activity>
    <id>271</id>
    <activity_class_id>CALL</activity_class_id>
    <activity_type_id>ACCEPTED_APPOINTMENT</activity_type_id>
    <location_id>271</location_id>
    <priority>1</priority>
    <split_allowed>false</split_allowed>
</Activity>

The above response does three things, all of which are necessary:

1. The Appointment Offer Response tells the ABE that the offers which were not used need no longer be reserved.
2. The activity must be constrained to the time slot in the appointment offer. The preferred way of doing this is to create an availability record of type ACCEPTED_APPOINTMENT. The constrained time slot must be at least as long as the original appointment offer.
3. The activity must be made more important i.e. increased in value. In the example above, this is achieved by switching the activity to a different Activity_Type. This assumes that you have two Activity_Types: provisional_appointment and accepted_appointment. The latter would have a higher base_value. On accepting an appointment offer, the activity is simply changed to have activity_type accepted_appointment. This is important to ensure that new, unappointed activities do not displace appointments that a customer has accepted.

Confirming Non-blocking Appointment Requests¶

When using non-blocking appointment requests there is always a chance that another appointment request could be allocated in the same slot causing the chosen appointment slot to become unavailable. For this reason the appointment offer response must be validated. To do this send an appointment offer response for the chosen slot with input_updated false. The Appointment Booking Engine will then confirm of the offer is still valid and if so block out the time.

<Appointment_Offer_Response>
    <appointment_request_id>819234</appointment_request_id>
    <appointment_offer_id>7</appointment_offer_id>
    <input_updated>false</input_updated>
</Appointment_Offer_Response>

Once the appointment offer response has been validated an Appointment_Summary record is created. The appointed attribute should be used to check if the appointment offer is still valid. If the appointment offer response was unsuccessful another appointment request should be made.

<Appointment_Summary>
    <appointment_request_id>819234</appointment_request_id>
    <activity_id>271</activity_id>
    <appointed>true</appointed>
    <request_outstanding>false</request_outstanding>
    <appointment_start_datetime>2006-01-03T15:00:00+00:00</appointment_start_datetime>
    <appointment_end_datetime>2006-01-03T16:00:00+00:00</appointment_end_datetime>
    <appointment_value>2615.3742633269112</appointment_value>
    <plan_id>3389</plan_id>
    <input_updated>false</input_updated>
</Appointment_Summary>

After checking the appointment was still appointed the appointment offer response can then be resent with the input_updated flag set to true and the activity updated.

<Appointment_Offer_Response>
    <appointment_request_id>819234</appointment_request_id>
    <appointment_offer_id>7</appointment_offer_id>
    <input_updated>true</input_updated>
</Appointment_Offer_Response>
<Availability>
    <id>6102</id>
    <datetime_start>2006-01-03T15:00:00</datetime_start>
    <datetime_end>2006-01-03T17:00:00</datetime_end>
    <activity_id>271</activity_id>
    <start_based>true</start_based>
    <availability_type>ACCEPTED_APPOINTMENT</availability_type>
</Availability>
<Activity>
    <id>271</id>
    <activity_class_id>CALL</activity_class_id>
    <activity_type_id>ACCEPTED_APPOINTMENT</activity_type_id>
    <location_id>271</location_id>
    <priority>1</priority>
    <split_allowed>false</split_allowed>
</Activity>

Declining an Appointment Offer¶

If none of the available slots for a request are suitable, the appointment request should be explicitly declined. To do this, an Appointment_Offer_Response must be sent without specifying an appointment_offer_id.

Activity Deletion & Scheduling Guidelines¶

If the activity associated with the request is no longer needed, it can either be deleted or marked as ‘do not schedule’.

If deleting the activity is preferred, an OBJECT_DELETION should be sent for the activity, we recommend disabling cascade deletions to maintain control over related data. In this setup, it becomes the responsibility of the integrator to delete all entities linked to the activity.

Refer to the Scheduling Schema documentation for more details on OBJECT_DELETION.

The alternative method, set the activity’s status to -1(do not schedule) and assign it to a dedicated object group. This allows users to filter it out from the workbench. These activities will be automatically cleared during the next initial load, ensuring they do not interfere with active scheduling.

Note: This alternative method will increase the size of data in the schedule. This could have an impact on performance, especially with heavy usage.

Regardless of the chosen approach, we recommend declining the offer. While offers will be declined automatically after the request timeout period elapses, this should only be treated as a fallback mechanism, not the primary method of offer rejection.

<Appointment_Offer_Response>
    <appointment_request_id>819234</appointment_request_id>
    <appointment_offer_id>-1</appointment_offer_id>
    <input_updated>false</input_updated>
</Appointment_Offer_Response>