Appointment Booking

Call center agents require calendar information to make appointments while talking to the customer on the phone. Often, they work with a call center application, using their own customer database. To allow for integration with these applications, external systems can query Optimize My Day for available time slots. In contrast to the option calculation in the Visual Scheduler, in which case the best option is presented first, the appointment booking request delivers slot availabilities over a period of time. The resulting list of options hides resource information, but specifies the quality of each available slot in comparison to other slots.

It is the responsibility of the calling application to parse the returned options and present them to the call center agent. Once the agent has made a choice, the option can be confirmed using the ConfirmOption request.

Options Request

The GET request must have the form:

/Options?<parameters> where <parameters> is a concatenated list of the following information:

Name	Description	Example
earliest	The first day on which options are to be calculated	2012-03-12
latest	The last day on which options are to be calculated	2012-03-25
estimatedDuration	The estimated duration of the task in minutes	45
territory	The identifier of the territory of the task. If no value is specified, the territory will not be considered a constraint.	133
skill	The required skill for the task. If no value is specified, the skill will not be considered a constraint.	KC395A
street	The street of the location of the task.	Sesamstreet 4
postalCode	The postal code (zip code) of the location of the task.	84784
city	The city of the location of the task.	Somecity
country	The country of the location of the task.	US
latitude	If available, a latitude value can be used instead of the address data. In that case, both longitude and latitude must be specified.	51.235482
longitude	If available, a longitude value can be used instead of the address data. In that case, both longitude and latitude must be specified.	6.813044
requiredResource	The identifier of the required resource. Optional.	12534
preferredResource	The identifier of the preferred resource. Optional.	12534
backupResource	The identifier of the backup resource. Optional.	12534
slot1	The first slot of the day for which appointments should be calculated	08:00-12:00
slot2	The second slot of the day for which appointments should be calculated	12:00-14:00
slot3	The third slot of the day for which appointments should be calculated	14:00-17:00
..., slotN	The n-th slot of the day for which appointments should be calculated	17:00-19:00
taskId	The identifier of the task if it already exists in the database.	1248445

Note that parameter values need to be URL-encoded.

Options Response

The resulting XML contains a list of Option elements, each containing the following list of attributes.

Attribute	Description	Example
date	The date of the option.	2012-03-12
slot	The slot of the option.	08:00-12:00
start	The earliest start time of the task within the specified time slot.	10:02:00
travelTime	The total increase of travel time (in minutes), once the option is confirmed.	42
travelDistance	The total increase of travel distance (in kilometers), once the option is confirmed.	35
quality	A value indicating the cost quality of the option. A indicates a cheap option, B an median option and C indicates an expensive option. Slots without an option are not part of the response.	A
idleTime	The time that will remain between this task and the next one, once the task is added to the trip. Idle time can occur if the next task is not movable, i.e. fixed in time.	75
tripId	The internal identifier of the trip object of the best option within this time slot.	4725274
version	The version of the trip. This value can be used during option confirmation to verify if the trip has been changed since the last query.	8

The following XML document contains a sample list of options:

Option Confirmation

If appointment booking is not time-critical and the chance of concurrent booking is minimal, the requesting application may choose to simply upload the task information including the planning data. Alternatively, the requesting application may confirm an option by sending the GET request

/ConfirmOption?<parameters> where <parameters> is a concatenated list of the following information:

Name	Description	Example
taskId	The identifier of the task if it already exists in the database.	1248445
start	The start date and time of the task.	2012-03-12 10:15:00
earliest	The new earliest date and time of the task. Optional.	2012-03-12 09:00:00
latest	The new latest date and time of the task. Optional.	2012-03-12 12:00:00
fixedAppointment	Indicates if the appointment is fixed in time, i.e. the task can not be moved within the earliest/latest time frame.	true
tripId	The internal identifier of the trip object of the best option within this time slot.	4725274
version	The version of the trip. This value is used to verify if the trip has been changed since the last query.	8

Note that the task must exist. If the requesting application had not yet inserted the task before asking for options, it is required to insert the task prior to option confirmation using one of the upload web services.

The result of this confirmation is again an XML document with a result tag, indicating the success of the confirmation:

A false success indicates that is was not possible to confirm the appointment. The message attribute may indicate further information about the reason. One possible reason is that the trip has changed since the Options request.

The Options Request has a few limitations with regards to the capabilities of the Visual Scheduler option calculations.

floating stops are not supported
breaks must be split into single breaks per day
task grouping is not supported
service stops are not supported
Minimum time for route calculation not added (if specified)
Adjustment to opening hours is not supported