_API JobBookRequest Definition

<sp:JobBookRequest>

<jobID>?</jobID>

JobID

is the caller’s identifier of the job to be booked. It must be unique, unless AllowRebook (above) is SP_True.

Yes

Yes

<jobType>?</jobType>

JobTypeID

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

Yes

Yes

<postcode>?</postcode>

Postcode

is the full post code of the location of the job.

Yes

Yes

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

No

Yes

<longitude>?</longitude>

Double

Is the longitude of the location of the job, format length 18 with max 9 decimal places

No

Yes

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

Jobs of long duration cannot be rebooked – if this field is true, and the JobID already exists and is a long job, then SP_MULTIJOBID_ALREADY_EXISTS (539) will be returned

For all other jobs, if this field has the value SP_True, the call to JobBookRequest will 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 JobBookRequest call continues anyway.

No

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

No

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

No

Yes

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

No

Yes

<reqSkills>

<skillID>?</skillID>

SkillID

Yes

Yes

<skillLevel>?</skillLevel>

is the level of the extra skill required in the ExtraSkills field, above. If the first of the ExtraSkills (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 ExtraSkill. If a skill level is not required, the field should be set to a value of 1.

Yes

</reqSkills>

</extraSkills>

<ListReqEmps>

Allows for a list of up to 10 <reqEmp>s to be specified. See Integration ServiceOptimizer Common API Concepts Mandatory Preferred Excluded Employees for details.

No

<reqEmp>

No

<empID>?</empID>

EmpID

names preferred, mandatory or excluded operatives for this job

Yes

Yes

<MPX>?</MPX>

Yes

</reqEmp>

</ListReqEmps>

<reqUnit>

No

<unitType>?</unitType>

if Mandatory, specifies that the job must only be assigned to an employee in the FRU or DRU supplied in the supplied Unit field (below), i.e. the supplied FRU or DRU is mandatory. Values other than Mandatory are not implemented and will cause SP_REQTYPE_INVALID (74) to be returned. The only supported combinations of this and the next two fields are: (1) Mandatory, Final and an FRU ID, or (2) Mandatory, SPUT_D and an DRU ID.

Yes

<RUID>?</RUID>

RUID

Yes

Yes

</reqUnit>

<priority>?</priority>

int

is used to determine the cost of the job being overdue. The ABS and the optimizer will normally cost the lateness of a high priority (SLA) job higher than a low priority job. This should have the effect of making it less likely that a high priority job will be significantly overdue (late). (Lateness is the amount by which a job’s scheduled start time (or finish time in the case of call-to-fix jobs – see callToFix, below)) exceeds its time.  Must be set to value between 1 and 99

No

<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

No

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

No

Yes

<contractEarliest>?</contractEarliest>

spDateTime

is the earliest time that the job should be started (ETA). If  ContractEarliest is not supplied, then ContractEarliest will be defaulted to <now>. See Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

No

<contractLatest>?</contractLatest>

spDateTime

is the time by which the job should either be started (ETA) or completed, depending on the value of callToFix. See Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

Yes

<servHoursPreDefPatts>

is a set of Service Hours patterns that are pre-defined in ServiceOptimizer.ServHoursPreDefPatts can’t be supplied as well as ServHoursPatts (below). See Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

No

<servHoursPreDef>

<dateRange>

<start>?</start>

spDate

The date ranges can be ‘open-ended’ in the sense that either the StartDate or the EndDate (or both) may be missing, in which case the Service Hours pattern is assumed to continue ‘for ever’ in the corresponding direction. 

No

<end>?</end>

spDate

No

</dateRange>

<servHoursPattID>?</servHoursPattID>

ServHoursPattID

The same ServHoursPattID must be supplied for each, though the accompanying DateRanges can be different.

Yes

Yes

</servHoursPreDef>

</servHoursPreDefPatts>

<servHoursPatts>

No

is a repeating sequence of Service Hours time periods that each apply to a day of the week. ServHoursPatts can’t be supplied as well as ServHoursPreDefPatts (above). See full details in Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

</servHoursPatts>

<accHoursPatts>

No

is a set of Access Hours patterns for this job.  The actual Access Hours for each pattern must be the same, though the DateRange can be different. See full details in Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

</accHoursPatts>

<openAccHoursOvrs>

is a set of open Access Hours overrides for this job. 

If overlapping open Access Hours override periods are supplied, the overlaps are silently removed – two overlapping open Access Hours overrides will be merged into one, for example.  Similarly, overlapping closed Access Hours overrides periods are also merged.

No

<openType>?</openType>

OpenHoursOvrType

If OpenType is Add, then the open overrides are added to the existing Access Hours for the job.

If OpenType is Replace, the supplied replace open overrides work in a per-calendar-day manner, i.e. the overrides replace the existing Access Hours time periods that start on the same day that the supplied open overrides start on.  So, for example, if a job has two existing Access Hours periods starting on a particular day, and there’s only one replace open override starting on that day, then the end result is to only have one Access Hours time period starting on that day.

Yes

<openHours>

Yes

<start>?</start>

Yes

<end>?</end>

Yes

</openHours>

</openAccHoursOvrs>

<closedAccHoursOvrs>

is a set of closed Access Hours overrides for this job.  Closed overrides are converted into open overrides before being stored.

No

<closedHours>

Yes

<start>?</start>

Yes

<end>?</end>

Yes

</closedHours>

</closedAccHoursOvrs>

<closedPubHols>

NA

No

<pubHolSets>?</pubHolSets>

Yes

Yes

</closedPubHols>

<closedDates>

is a set of closed dates (i.e. closed whole days) for this job. ClosedDates applies only to Service Hours, not to Access Hours.

No

<dateRange>

Yes

<start>?</start>

Yes

<end>?</end>

Yes

</dateRange>

</closedDates>

<bookOptions>

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

No

<AllowEmpOT>?</AllowEmpOT>

No

<SpareIgnVanStock>?</SpareIgnVanStock>

No

<FixToEmp>?</FixToEmp>

No

<ServAsAccHours>?</ServAsAccHours>

No

<CallToFix>?</CallToFix>

No

<ReqConfirm>?</ReqConfirm>

No

<NonConsecShift>?</NonConsecShift>

if a long duration job is to be booked

No

<ConsecShift>?</ConsecShift>

if a long duration job is to be booked

No

<ContigShift>?</ContigShift>

if a long duration job is to be booked

No

</bookOptions>

<forceOptions>

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

Force Options are not available for use in conjunction with Long jobs that are to be split across multiple shifts, an attempt to set this will result in SP_FORCEOPTIONS_INVALID (150).

No

<InTray>?</InTray>

No

<InTrayWithSkill>?</InTrayWithSkill>

No

<InTrayAfterAll>?</InTrayAfterAll>

No

<SpareForceGo>?</SpareForceGo>

No

<Reassign>?</Reassign>

No

<IgnoreCapacity>?</IgnoreCapacity>

No

<NoTravel>?</NoTravel>

No

<NoLocalKnowledge>?</NoLocalKnowledge>

No

</forceOptions>

<reqSpares>

No

See Spares Information for details of the <reqSpares> structure.

</reqSpares>

<deliverySize>?</deliverySize>

int

is the amount of space occupied by equipment to 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.

No

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

No

<siteID>?</siteID>

SiteID

Each job can optionally have 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.

No

Yes

<groupID>?</groupID>

GroupID

Each job can optionally be given () a GroupID when it’s booked. 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.

No

<capacityCategory>?</capacityCategory>

CapacityCategoryName

Each job can optionally be given () a CapacityCategory when it’s booked.  Capacity constraints, in the form of a reserved or/and limit level can be defined for each Category and a check can be done in JobBookRequest to book only those jobs where none of these constraints would be broken.

No

Yes

<customer>

No

No

is customer information (See section 4.4.3)

</customer>

<desc>?</desc>

is free format text describing the job (See section 4.4.4)

No

<desc2>?</desc2>

is free format text about the job that appears in the “More Notes” window on the Gantt.  If it conforms to the XML schema gantt.morenotes.xsd, it will appear in a two column table (see[2] and §17).

No

</sp:JobBookRequest>