/
Integration ServiceOptimizer Request Multi-Job Appointments SOAP API

Integration ServiceOptimizer Request Multi-Job Appointments SOAP API

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

(tick)

 

 

<MultOptions>

 

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

 

(error)

 

 

 

<OfferBestOnlyPerEmp>?</OfferBestOnlyPerEmp>

 

 

(error)

 

 

 

<RestrictSearch>?</RestrictSearch>

 

 

(error)

 

 

</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

(tick)

 

 

<OfferAppts>

 

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

 

 

 

 

<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.

 

 

 

</OfferAppts>

 

 

 

 

 

<OfferCount>?</OfferCount>

 

 

(error)

 

</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 Integration ServiceOptimizer 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 ApptOfferResponse

 

 

 

 

<latitude>?</latitude>

Double

This parameter is not supported for this API

(error)

(tick)

 

 

<longitude>?</longitude>

Double

This parameter is not supported for this API

(error)

(tick)

 

</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.