<sp:BookDependencyGroupRequest>

<multiJobID>?</multiJobID>

JobID

is the identifier (ID) of the dependency group as a whole.  Dependency group IDs have a separate name space from regular job IDs.

<bookOptions>

<AllowRebookAll>?</AllowRebookAll>

boolean

When true, if the dependency group identified by MultiJobID is already in the ServiceOptimizer database then that whole dependency group, including all of the jobs in it (subject to the options below), will be cancelled first, after which sp:BookDependencyGroupRequest will work just as it does when AllowRebookAll is not set. This allows both the MultiJobID and all of the JobIDs in the dependency group to be reused. All of the jobs supplied must be in the same FRU as the jobs in the original DG, otherwise SP_DIFFERENT_FRUS (533) is returned.

If AllowRebookAll is set, but the supplied MultiJobID isn’t already in the ServiceOptimizer database, the call will continue (i.e AllowRebookAll is effectively ignored) as long as none of the supplied jobs (in SP_BDGJobSeq) already exist, in which case, SP_JOBID_EXISTS (23) is returned.

When AllowRebookAll is set, sp:BookDependencyGroupRequest is an atomic operation, i.e. it won’t return part way through with the existing dependency group cancelled but its replacement not booked.

If one or more of the existing JobIDs in the dependency group are outside the ServiceOptimizer memory horizon, the dependency group can’t be re-booked and will fail with SP_JOBID_OUTSIDE_HORIZON (626).

<DontCancelCleared>?</DontCancelCleared>

boolean

When true, any jobs in the dependency group/split dependency group whose status is Cleared won’t be cancelled.

If DontCancelCleared is set but AllowRebookAll isn’t, SP_OPTION_COMBINATION_INVALID (159) will be returned.

<DontCancelLoggedOff>?<DontCancelLoggedOff>

boolean

When true, any jobs in the dependency group/split dependency group whose status is Logged Off won’t be cancelled.

If DontCancelLoggedOff is set but AllowRebookAll isn’t, SP_OPTION_COMBINATION_INVALID (159) will be returned.

When true, any jobs in the dependency group/split dependency group whose status is Logged On won’t be cancelled.

If DontCancelLoggedOn is set but AllowRebookAll isn’t, SP_OPTION_COMBINATION_INVALID (159) will be returned.

</bookOptions>

<job>

is the set of jobs to be booked in this call.

Each of these jobs contains the same information as in a call of JobBookRequest (see 6.6). There is an additional field, IsPrimaryJob, that isn’t implemented yet and should be set to SP_False.  A value of SP_True will be ignored and SP_False will be assumed.  Any other value supplied will return SP_ISPRIMARYJOB_INVALID (575) (575).  There are, however some special rules for some of the fields. AllowRebook is not available for any jobs in a dependency group.  If it’s set to SP_True, it will be ignored; if set to any value other than SP_False or SP_True, SP_ALLOWREBOOK_INVALID (87) (87) is returned.  ReqUnit should the same FRUID for all of the jobs in a dependency group, otherwise SP_DIFFERENT_FRUS (533) (533) will be returned.   The only ForceOption available for any job in an BookDependencyGroupRequest call is SP_OptInTrayAfterAll and it should either be set for all jobs in the same call or for none of them.

<jobID>?</jobID>

JobID

job ID of the ‘dependent’ job (ie parts pickup or helper call)

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

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

<longitude>?</longitude>

Double

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

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.

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

<extraOverhead>?</extraOverhead>

Unsigned int

Is the extra overhead time in minutes required to do this job in addition to the overhead time defined for this job type.

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

<reqSkills>

<skillID>?</skillID>

SkillID

<skillLevel>?</skillLevel>

is the level of the extra skill 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 field should be omitted

</reqSkills>

</extraSkills>

<ListReqEmps>

Allows for a list of up to 10 reqEmps to be specified. See MPX employee options

<reqEmp>

<empID>?</empID>

EmpID

names preferred, mandatory or excluded operatives for this job

<MPX>?</MPX>

</reqEmp>

</ListReqEmps>

<reqUnit>

<unitType>?</unitType>

UnitType

If an RUID is supplied it is assumed to Mandatory as other values are not supported.

<RUID>?</RUID>

RUID

FRU or DRU

</reqUnit>

<priority>?</priority>

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

<importance>?</importance>

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

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

<contractEarliest>?</contractEarliest>

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

<contractLatest>?</contractLatest>

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

This field is mandatory.

<servHoursPreDefPatts>

is a set of Service Hours patterns that are pre-defined in ServiceOptimizer.  The same ServHoursPattID must be supplied for each, though the accompanying DateRanges can be different.  The date ranges can be ‘open-ended’ in the sense that either Start or End (or both) may be missing, in which case the Service Hours pattern is assumed to continue ‘for ever’ in the corresponding direction.  ServHoursPreDefPatts can’t be supplied as well as ServHoursPatts (below). See Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

<servHoursPreDef>

<dateRange>

<start>?</start>

<end>?</end>

</dateRange>

<servHoursPattID>?</servHoursPattID>

ServHoursPattID

</servHoursPreDef>

</servHoursPreDefPatts>

<servHoursPatts>

ServHoursPatts can’t be supplied as well as ServHoursPreDefPatts (above). See Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

</servHoursPatts>

<accHoursPatts>

is a set of Access Hours patterns for this jobs. See Integration ServiceOptimizer Common API Concepts Contract Service and Access Hours

</accHoursPatts>

<openAccHoursOvrs>

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

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.

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.

<openType>?</openType>

OpenHoursOvrType

<openHours>

<start>?</start>

<end>?</end>

</openHours>

</openAccHoursOvrs>

<closedAccHoursOvrs>

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

<closedHours>

<start>?</start>

<end>?</end>

</closedHours>

</closedAccHoursOvrs>

<closedPubHols>

NA

<pubHolSets>?</pubHolSets>

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

<dateRange>

<start>?</start>

<end>?</end>

</dateRange>

</closedDates>

<bookOptions>

For definitions of these see Options

<AllowEmpOT>?</AllowEmpOT>

<SpareIgnVanStock>?</SpareIgnVanStock>

<FixToEmp>?</FixToEmp>

<ServAsAccHours>?</ServAsAccHours>

<CallToFix>?</CallToFix>

<ReqConfirm>?</ReqConfirm>

<NonConsecShift>?</NonConsecShift>

if a long duration job is to be booked

<ConsecShift>?</ConsecShift>

if a long duration job is to be booked

<ContigShift>?</ContigShift>

if a long duration job is to be booked

</bookOptions>

<forceOptions>

For definitions of these see Options

The same set of options are supported as with other job booking interfaces except for NoLocalKnowledge – this option is ignored and behaviour will be as if it is not set.

<InTray>?</InTray>

<InTrayWithSkill>?</InTrayWithSkill>

<InTrayAfterAll>?</InTrayAfterAll>

<SpareForceGo>?</SpareForceGo>

<Reassign>?</Reassign>

<IgnoreCapacity>?</IgnoreCapacity>

<NoTravel>?</NoTravel>

</forceOptions>

<reqSpares>

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

</reqSpares>

<deliverySize>?</deliverySize>

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.

<pickupSize>?</pickupSize>

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.

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

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

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

<customer>

is customer information (See section 4.4.3)

</customer>

<desc>?</desc>

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

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

<isPrimaryJob>?</isPrimaryJob>

Is this the job fromwhich the dependencies should be taken?

</job>

<jobDep>

<depJobID>?</depJobID>

JobID

job ID of the ‘dependent’ job (ie parts pickup or helper call)

<depJobsTime>?</depJobsTime>

DepTimeType

What part of the ‘dependent’ job is of consequence to the relationship

<targJobID>?</targJobID>

JobID

The job ID of the regular job

<targJobsTime>?</targJobsTime>

DepTimeType

What part of the regular job is of consequence to the relationship

<earliestTime>?</earliestTime>

Int

What is the maximum time difference there should be between the DepJobsTime and TargetJobsTime

See note below re: required status.

<earliestTimeUnits>?</earliestTimeUnits>

DepUnits

What is the Unit of the above time.  If zero then any unit can be supplied

See note below re: required status.

<latestTime>?</latestTime>

Int

What is the minimum time difference there should be between the DepJobsTime and TargetJobsTime

See note below re: required status.

<latestTimeUnits>?</latestTimeUnits>

DepUnits

What is the unit of the above.  If zero then any unit can be supplied

See note below re: required status.

<targetTime>?</targetTime>

Int

What is the target difference between depJobsTime and targetJobsTime

See note below re: required status.

<targetTimeUnits>?</targetTimeUnits>

DepUnits

What is the unit of the above.  If zero then any unit can be supplied

See note below re: required status.

<costID>?</costID>

What is the CostID for variances from the TargetTime. If there is no TargetTime no value should be passed (otherwise SP_COSTID_NO_TARGET_TIME (576) is returned).

<depEmpType>?</depEmpType>

DepEmpType

What is the relationship for the employee requirements for the target and dependent job.

</jobDep>

</sp:BookDependencyGroupRequest>