_API ApptBookRequest Definition

<sp:ApptBookRequest>

<jobID>?</jobID>

JobID

is the caller’s identifier of the job to be booked. It must be unique in the ServiceOptimizer database, unless AllowRebook (below) is True

<jobType>?</jobType>

JobTypeID

must be one of the job types (aka task codes) set up in ServiceOptimizer

<postcode>?</postcode>

Postcode

is the full post code of the location of the job. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<latitude>?</latitude>

Double

Is the latitude of the location of the job, format length 18 with max 9 decimal places. If postcode is ‘UNKNOWN’ then latitude and longitude are used to create a named place for the job. . Such named places will NOT be visible on a ServicePlanner map. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<longitude>?</longitude>

Double

Is the longitude of the location of the job, format length 18 with max 9 decimal places. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<vwdlLocationType>?</vwdlLocationType>

<date>?</date>

spDate

The date on which the job is to be booked. Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.

Each job may optionally have a restrictionRef. If specified, it must exist in the ServiceOptimizer database. Jobs with a restrictionRef will not show sensitive information for the job on the Gantt, unless the Gantt user has been given permission to view the full jobs details.

See Integration ServiceOptimizer Job Restrictions SOAP APIs for further details.

<allowRebook>?</allowRebook>

Boolean

If the value of this field is True, the call to ApptBookRequestwill not fail if the JobID already exists in the ServiceOptimizer database. Instead, the existing job is deleted and replaced by this one.  If AllowRebook is set and the job doesn’t already exist, the ApptBookRequestcall continues anyway

<extraDuration>?</extraDuration>

Unsigned int

is the time (in minutes) required to complete the job in addition to what is defined in ServiceOptimizer for this job type. The maximum value which will be accepted for this field plus ExtraOverhead (below) is specified by the SJEDMax database parameter. The maximum total duration for the job is specified by the SJTDMax database parameter. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<extraOverhead>?</extraOverhead>

Unsigned int

is the extra overhead time required to do this job in addition to the overhead time defined for this job type. The extra time is in minutes. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<extraSkills>

is a list of the extra Skills  (skill IDs) needed to do this job, in addition to those specified in ServiceOptimizer for this job’s type. If one or more of the supplied ExtraSkills is already required by the JobType, it will be ignored unless it’s the first ExtraSkill and the ExtraSkillLevel (below) is different from that specified for the JobType.  The maximum number of skills that can be supplied is 10 however, only the skillLevel for the first skillID in the list has any meaning other skills are assumed to require no specific level. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<reqSkills>

<skillID>?</skillID>

SkillID

<skillLevel>?</skillLevel>

int

is the level of the skillID required in the skillID field above. If the first of the skillID (above) specifies a skill which is already required by the JobType, then ExtraSkillLevel will replace the skill level required by the JobType for the first of the skillID. If a skill level is not required, the supplied value for this field should be 1.

</reqSkills>

</extraSkills>

<ListReqEmps>

Allows for a list of up to 10 reqEmps to be specified. See MPX employee options. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<reqEmp>

<empID>?</empID>

EmpID

names preferred, mandatory or excluded operatives for this job

<MPX>?</MPX>

</reqEmp>

</ListReqEmps>

<sameUnit>?</sameUnit>

SameUnit

if Final, specifies that the job should only be assigned to an employee in the FRU supplied in Unit field in the corresponding previous call to OfferApptRequest. This option relies on OfferToken (see below) being the one which was supplied from that OfferApptRequest) call. Values other than Final are not implemented and will cause the code SP_UNITTYPE_INVALID (77) to be returned. If OfferToken is not supplied, this field must also be omitted, otherwise SP_UNITTYPE_INVALID (77) is returned.

<stdExtraDuration>?</stdExtraDuration>

StdExtraDuration

specifies one of two things:

• that extra time (how much time is set up in the ServiceOptimizer database) should be added to the normal amount for the job type (useful, for example, if additional time should be allowed for a key to be collected (LocalKeyPU)), or
• that this job has a ‘special’ duration (only DurationOneDay is currently implemented)

Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<bookLoc>?</bookLoc>

BookLocID

is the unique identifier of the location (or service) from which the job is booked. If at a later time, for example when a job becomes earmarked, ServiceOptimizer needs to send out a message, this location is used to look up (in the ServiceOptimizer database) the address of the service it is sent to.

<priority>?</priority>

int

is the priority the job should have. If priority isn’t being used, it should be set to 50. Must be set between 1 and 99

<importance>?</importance>

int

is used to try and ensure that the jobs left in the in-tray are the less important ones and that the more important jobs are in the schedule. Must take a value between 0 and 9. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<offerToken>?</offerToken>

OfferToken

should have the same value that was returned by ApptOfferRequest. It is used to speed up the booking process. If OfferToken is not supplied, a call to ApptOfferRequest is done first, and the lowest ranked appointment returned is chosen and booked.

<promBand>

<timeBandID>?</timeBandID>

TimeBandID

is the name of the time band of the promise required, e.g. “M” for a time band which has been set up in ServiceOptimizer as 8:30 to 12:30. The job will be started within these two times. Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.

<start>?</start>

spTime

start time overrides the start times defined by the timeBandID above. If neither timeBandID nor start is supplied, then defaults to 00:00 (start of day). Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.

<end>?</end>

spTime

end time overrides the end times defined by the timeBandID above. If neither timeBandID nor end is supplied, then defaults to 24:00 (end of day). Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.

</promBand>

<bookOptions>

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

The bookOptions below that are also valid for the Request Appointments SOAP API call must be passed in as they were in the call to sp:OfferApptRequest. For example, if AllowEmpOT was not passed into the Request Appointments SOAP API call, then it must also not be passed into the sp:ApptBookRequest call; or, if AllowEmpOT was set to true for the Request Appointments SOAP API call, then it must also be set to true for the sp:ApptBookRequest call.

<AllowEmpOT>?</AllowEmpOT>

<SpareIgnVanStock>?</SpareIgnVanStock>

<ReqConfirm>?</ReqConfirm>

</bookOptions>

<forceOptions>

Please refer to the Force Options section on the Integration ServiceOptimizer Common Options page for defintions and settings values.

This field is not valid for use where the appointment is of long duration and required splitting across multiple shifts – any values passed will result in a return code of SP_FORCEOPTIONS_INVALID (150).

<InTray>?</InTray>

<InTrayWithSkill>?</InTrayWithSkill>

<SpareForceGo>?</SpareForceGo>

<Reassign>?</Reassign>

<IgnoreCapacity>?</IgnoreCapacity>

<NoTravel>?</NoTravel>

<NoLocalKnowledge>?</NoLocalKnowledge>

</forceOptions>

<reqSpares>

Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

See Integration ServiceOptimizer Common API Concepts Spares Information for details of the <reqSpares> structure.

</reqSpares>

<deliverySize>?</deliverySize>

int

is the amount of space occupied by equipment that will be removed from the operative’s vehicle as part of this job. SP_VEHICLE_CAPACITY_EXCEEDED (662) will be returned if no single vehicle within the FRU has a vehicle capacity large enough. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<pickupSize>?</pickupSize>

int

is the amount of space occupied by equipment that will be loaded onto the operative’s vehicle as part of this job. SP_VEHICLE_CAPACITY_EXCEEDED (662) will be returned if no single vehicle within the FRU has a vehicle capacity large enough. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<siteID>?</siteID>

SiteID

A Site Identifier.  ServiceOptimizer will attempt to schedule jobs with the same siteIDs: (a) consecutively, so that there’s zero travel time between them, and (b) with the overhead time (from the Job Type and the supplied ExtraOverhead) removed from all but the first of them.  ServiceOptimizer treats the siteID as an opaque value that it uses only to group jobs together. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<groupID>?</groupID>

GroupID

Jobs with the same groupID should be allocated in the minimum number of contiguous groups that are needed to meet their Access Hours constraints.  Like a siteID, a groupID is treated as an opaque value by ServiceOptimizer. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<capacityCategory>?</capacityCategory>

CapacityCategoryName

Capacity constraints, in the form of a reserved or/and limit level can be defined for each capacityCategory and a check can be done in ApptOfferRequest so that only those offers where none of these constraints would be broken are returned. Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

<customer>

See section 4.4.3

</customer>

<desc>?</desc>

desc

See section 4.4.4

<desc2>?</desc2>

desc2

See section 4.4.4

</sp:ApptBookRequest>