On This Page:

Requesting Appointments

Arranging an appointment that is satisfactory to both the end customer and to the business is a compromise. From the customer’s point of view, the more specific the promised arrival time the better. From the business point of view, the situation is just the opposite: maximum flexibility and lowest costs can be achieved by making the least specific promise possible.

The compromise is to promise that the work will start within a particular time band, e.g. ‘during Thursday morning’, or ‘between 2 o’clock and 4 o’clock in the afternoon next Tuesday’.

To help with the process of making promises to the customer, ServiceOptimizer can take time slots when employees are available for work and convert them into promises suitable to make to a customer. This is known as packaging.

Within ServiceOptimizer, a Time Band is made up of two times: a start time and an end time. It also has a one or two character name and a type. The following are examples of Time Bands that can be put into the ServiceOptimizer database:

Band Name	Start Time	End Time	Band Type	Comment
D	08:30	17:00	D	The Time Band name ‘D’ is short for ‘day’. The Time Band type ‘D’ is the same.
M	08:30	12:30	H	The Time Band name ‘M’ is short for ‘morning’. The Time Band type ‘H’ is short for ‘half-day’.
A	12:30	17:00	H	The Time Band name ‘A’ is short for ‘afternoon’. The Time Band type ‘H’ is short for ‘half-day’.
08	08:00	10:00	2	The Time Band name ‘08’ is short for ‘the time slot starting at 08:00’. The Time Band type ‘2’ is short for ‘2 hour duration’.
10	10:00	12:00	2	The Time Band name ‘10’ is short for ‘the time slot starting at 10:00’. The Time Band type ‘2’ is again short for ‘2 hour duration’.
etc

Promise Sets

Packaging is based on the use of lists of Time Bands called Promise Sets. When ServiceOptimizer is requested to offer some appointments, a Promise Set is supplied. If an employee is available to work on a job starting at a particular time, and if that time is between the start time and end time of one or more Time Bands in the Promise Set, then those Time Bands are returned as the promises to be offered to the customer. The other important part of packaging is that any duplicate promises are discarded.

As an example, assume that:

The Time Bands ‘D’, ‘M’ and ‘A’ are defined in ServiceOptimizer, as in the above table;
There is a Promise Set which contains those Time Bands, in that order; and
There is an employee available to do the job, starting at either 10:00 or at 13:00.

The first time when the employee is available, 10:00, is within the Time Bands D and M. This would therefore generate two promises to be offered: D and M. The second time, 13:00, is within Time Bands D and A, so two more promises are generated: D and A. However this second D is a duplicate of the first D, so it is discarded. The promises returned are therefore: D, M and A.

Note that these three promises are of two different Time Band types: one is of type D, the other two are of type H.

When appointments (promises) are requested, one of the parameters to the Request Appointments SOAP API, numReq, is the number of appointments required. It represents the number of promises required of the particular Time Band type given in the parameter numReqType.

In the previous example, if numReq was given the value 1, and numReqType was D, then all three promises would be returned.

The Request Appointments SOAP API numReq parameter only limits the number of appointments returned of the Time Band type requested by the numReqType parameter.

Any other appointments found as a result of the Promise Sets requested via the promSet parameter will not be discarded, and will returned along with the limited set of appointments.

Thus, in the above example, three appointments found (Band D with Type D, Band M with Type H and Band A with Type H), the single appointment with type D does not need to be restricted, based on a request for numReq of 1 with numReqType of D; while no restrictions are applied to the other appointments of type H; so, all three appointments are returned.

If, on the other hand, numReq was given the value 1, and numReqType was H, then only the D and M appointments would be returned, because the M promise is the first of the two appointments of type H, while the appointment of type D has no restrictions applied.

This way of using the numReq and numReqType parameters is necessary because a Promise Set can contain Time Bands of different types. When this is the case, it is difficult to know how big to make the array supplied to the Integration ServiceOptimizer Request Appointments SOAP API to contain the offers returned. In the worst possible case, if numReq has the value N, and the number of Time Bands in the Promise Set requested is M, the number of offered appointments will be N×M.

This situation is simpler if all of the Time Bands in a given Promise Set are of the same type and do not overlap. Then the number of offers returned will always be no greater than the value of numReq.

Browser not supported