On This Page:

Related Pages:

The sp:OfferAppsMultRequest API method can be used to request possible multi-job appointments (i.e. for jobs that will require multiple appointments to complete).

Description

The sp:OfferAppsMultRequest API method returns possible customer appointments which match a set of criteria where two or more appointments are required to be carried out by the same operative with an allowance for some minimum intervals between their successive end and start times.

It has three parameters:

the input parameter RequestInfo provides the criteria which apply to all of the individual requests which make up the multi-job appointment request;
the input parameter Request provides the criteria for each of the appointment requests making up the multi-job appointment request; and
the output parameter Offers contains the appointment offers which meet the criteria in all the requests.

In normal operation, it is intended that the customer would choose those offers with an appointment window which had been found to match all the appointment requirements, and then reserve those appointments in ServiceOptimizer using successive calls to the Book Appointment SOAP API, supplying the operative ID returned in the offer’s OfferText field as the mandatory operative. Once booked, the job will be fixed in time as well as to the mandatory operative.

The description of all fields are the same as that described in the Request Appointments SOAP API, except where specified.

Definition

The definition of this API is:

Click here to expand...

Web Service

Type

Description

Req?

Val?

<sp:ApptOfferMultRequest>

<RequestCount>?</RequestCount>

Unsigned int

The total number of individual appointments in the overall job.

Yes

<MultOptions>

See the "Offer/Book Options" for the definitions of the permitted MultOptions listed below.

No

<OfferBestOnlyPerEmp>?</OfferBestOnlyPerEmp>

No

<RestrictSearch>?</RestrictSearch>

No

</MultOptions>

<MinPartialMatchCount>?</MinPartialMatchCount>

Unsigned int

MinPartialMatchCount determines whether partial matches are to be returned. If, for example, RequestCount is 4 and MinPartialMatchCount is 2, and a set of 4 offers is not available for a particular employee, then partial offers containing 3 and 2 offers will be returned. In this case 4 offers will still be returned, but the ones where there is no match will be null, i.e. the first field of the SP_ApptOffer, ApptDate, will be an empty string (“”). If RequestCount and MinPartialMatchCount have the same value, no partial matches will be returned

Yes

<OfferAppts>

The OfferAppts structure is the same as the sp:ApptOfferRequest structure defined in the Request Appointments SOAP API, but with the following differences as listed below.

<start>

<date>?</date>

spDate

The value of the start date should be different for each OfferAppts supplied.

The first OfferAppts should contain a start date as it would in the sp:ApptOfferRequest structure defined in the Request Appointments SOAP API.

However, subsequent OfferAppts will contain a start date which should normally be specified in a relative way in either of the following formats:

Relative Whole Day Appointments	`+n`	In this format, the start `date` is interpreted as being exactly `n` days (operative days) after the start `date` in the previous `OfferAppts`. For example, `+1` means exactly one day after the start `date` in the previous `OfferAppts`.
	`>=n`	In this format, the start `date` is interpreted as being at least `n` days after the start `date` in the previous `OfferAppts`.
		As an example: to get offers for 3 contiguous days from a given date, the first start `date` should be that given date and the second and third start `date` values should both be `+1`. In both of the above cases, `n` must be 1 or greater, but not so great that the search isn’t within the memory horizon.
Part Day Appointments		For part day appointments, where the `promSet` field is used, for example, to specify a set of half day TimeBands, a relative start `date` will contain a count of a number of TimeBands instead of a number of days. That is:
	`+n(TBT)`	Here, the start `date` is *exactly* `n` TimeBands after (ordered by their start times) the start `date` in the previous `OfferAppts`, where `TBT` is the type of the TimeBands which `n` is counting, *but is on the same day*. For example, if, in the ServiceOptimizer database, there is a TimeBand type of “HD” for all half day timebands, then `+1(HD)` means one half day (HD) after the start `date` in the previous `OfferAppts`, but on the same day (i.e. the first appointment is in the morning, the second in the afternoon).
	`>=n(TBT)`	Similar to the above, except that the start `date` is interpreted as being *at least* `n` time bands of type `TBT` after the start `date` in the previous `OfferAppts`, but not necessarily on the same day.

</start>

<end>

<date>?</date>

spDate

If the end date is supplied in the first OfferAppts but not in subsequent ones, those end date values will be defaulted to be the same number of days after their corresponding start date as the first end date value is after the first start date value.

</end>

<band></band>

The entire band structure of the sp:ApptOfferRequest API method must not be used inside the OfferAppts structure for an sp:ApptOfferMultRequest API method call.

<displayCostBreakdown>?</displayCostBreakdown>

boolean

If true return the Schedule Cost Breakdown structure details as part of the response. When set to true for at least one OfferApts structure, then the Cost Breakdown structure will be returned for all responses.

However, If either the forceOptions InTray or InTrayWithSkill options are set to true, then the Schedule Cost Breakdown structure will not be returned in the response.

No

</OfferAppts>

<OfferCount>?</OfferCount>

No

<allowRebookJobID>?</allowRebookJobID>

JobID

Optional parameter. When searching for offers, the scheduler will exclude any job where the job's ID matches the allowRebookJobID value, so that the existing job's window may be considered for offers.

Any offers returned when this value is not empty should then be booked using the same JobID with allowRebook = 1.

No

</sp:ApptOfferMultRequest>

All of the fields to do with dates and times are assumed to use customer local TZ, i.e. local to the region where the job is located.

The use of spares has not been validated for the 14.1 Request Multi-Job Appointments SOAP API.

No special function is provided to book multiple appointments. Instead, the caller should iteratively book the set of offers for one operative returned from a call to ApptOfferMultRequest. The ID of the operative should be supplied as the ‘mandatory tech’ in the EmpID field of the SP_ApptBook struct parameter to each call of ApptBookRequest; the StdExtraDuration field can be set to SPSD_DurationOneDay for ‘all day’ jobs.

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:ApptOfferMultResponse>`
	`<returnCode>?</returnCode>`			This contains the standard return structure.
	`<offers>`			Returned `offers` and `splitOffers` are of the same format as in the `ApptOfferResponse` structure.
		`<latitude>?</latitude>`	`Double`	This parameter is not supported for this API.	N	Y
		`<longitude>?</longitude>`	`Double`	This parameter is not supported for this API.	N	Y
		`<costBreakDownInformation>`		The `costBreakDownInformation` structure is only included in the response when required by the use of the `displayCostBreakdown` parameter in the request.
				See 14.1 Schedule Cost Breakdown for details of the `costBreakDownInformation` structure.
		`</costBreakDownInformation>`
	`</offers>`
	`<splitOffers>`

	`</splitOffers>`
`</sp:ApptOfferMultResponse>`

All of the fields to do with dates and times are assumed to use customer local TZ, i.e. local to the region where the job is located.

In the returned SP_ApptOffer structs:

The OfferText field will contain the ID of the RU (as it does now) followed (separated by a single space) by the EmpID of the operative tentatively assigned to this offer. This will allow the SMS to group together those offers which are for the same operative, and use the EmpID as the mandatory technician when subsequently booking appointments.
Offers are effectively grouped into sub-sets each containing RequestCount offers, so the returned value of OfferCount is always a multiple of RequestCount. Each sub-set contains RequestCount appointments for the same employee. Where partial matching has been specified (MinPartialMatchCount < RequestCount), null offers (empty ApptDate) are returned to maintain this. There can be more than one sub-set for the same employee only if OfferBestOnlyPerEmp is not set.
There can, of course, be sets of offers for more than one operative on the same ApptDates.
Where the StartDates in the supplied SP_ApptOffer structs use the relative notation described earlier, those offer sub-sets which cover the least elapsed time will be ranked lowest, i.e. best. Sub-sets with the same appointment dates, but for different operatives will be ranked according to the ranking of each individual offer, which will include a measure of the distance of the job from the operative’s start location.

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

Click here to expand...

SP_RELATIVE_START_DATE_INVALID (116)
SP_MAX_OFFER_COUNT_REACHED (117)
SP_UNITTYPE_INVALID (77)
SP_FORCEOPTIONS_INVALID (150)
SP_SITE_OR_GROUP_ID_INVALID (502)
SP_NOT_AVAILABLE (627)

If SPUT_D is supplied for any UnitType field, then SP_UNITTYPE_INVALID (77) will be returned.