On This Page:

Related Pages:

The sp:BookDependencyGroupRequest API method can be used to create dependencies between pairs of jobs.

Description

The sp:BookDependencyGroupRequest API method allows dependencies to be defined between pairs of jobs. In most cases, the normal job data for each job (JobID, access hours, etc. - the data supplied in Book Non-Appointment Job SOAP API) is supplied along with the dependencies, but it is also possible to supply dependencies between jobs that are already in the ServiceOptimizer database.

The set of dependencies between pairs of jobs are contained in a sequence of SP_JobDeps:

#define SP_CostIDSize 10

typedef char SP_CostID [SP_CostIDSize +1];

Definition

The definition of this API is:

Click here to expand...

Web Service						Type	Description	Req?	Val?
`<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 `JobID`s 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 `JobID`s 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.
		`<DontCancelLoggedOn>?</DontCancelLoggedOn>`				`boolean`	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
		`<vwdlLocationType>?</vwdlLocationType>`				`EmpLocType`	When set, indicates that the appointment is virtual, with a dynamic location. The dynamic location to be used for the appointment is based on the assigned employee. Currently, only the `EmpLocType` value of `Home` is supported.
		`<restrictionRef>?</restrictionRef>`				`RestrictionRef`	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 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 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 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 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 Contract, Service and Access Hours
		`</servHoursPatts>`
		`<accHoursPatts>`
							is a set of Access Hours patterns for this jobs. See 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>`

Each pairing of earliestTime/earliestTimeUnits, latestTime/latestTimeUnits and targetTime/targetTimeUnits is optional, but at least one pairing must be specified.

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:BookDependencyGroupResponse>`
	<result>?</result>			This contains the standard return structure. This occurs once.
	`<travelTime>?</travelTime>`		`int`	If the call succeeds, this is the sum of the travel time for all of the jobs in the MultiJobID dependency group. This occurs once or not at all depending on whether the call has been successful or not.
	`<retJobs>`			This occurs once for EACH job in the booking group.
		`<jobID>?</jobID>`	`JobID`	is the regular JobID of the job
		`<empID>?</empID>`	`EmpID`	is the ID of the operative that this job is allocated to. Only if SP_OptFixToEmp was supplied in the input BookOptions will this job necessarily remain allocated to this operative. If the job is unresourced, an empty string is returned.
		`<maybeETA>?</maybeETA>`	`spDateTime`	are the ETA of the job at the time of booking. It’s unlikely to remain scheduled to this ETA. If the job is unresourced, empty strings are returned.
		`<IRU>?</IRU>`	`RUID`	the ID of the IRU to which the job has been booked, determined as follows: If the job is resourced, it’s the ID of the IRU that contains the Team that the operative provisionally assigned to the job is posted to at the time of the job. If job is unresourced, it’s the ID of the IRU that contains the Region that the job is located in. If that Region is contained in more than one IRU in the FRU where the offer is being made (i.e. there are overlapping IRUs in the FRU), it’s the first IRU’s ID, ordered alphabetically.
		`<FRU>?</FRU>`	`RUID`	the ID of the FRU to which the job has been booked
	`</retJobs>`
`</sp:BookDependencyGroupResponse>`

Return Codes

In addition to the Standard Return Codes, and the Return Codes which may be returned from the Book Non-Appointment Job SOAP API, the possible Return Codes from this API are:

Click here to expand...

SP_JOBID_EXISTS (23)
SP_BDGJOBSEQ_SIZE_INVALID (506)
SP_BDGJOBSEQ_JOBS_NULL (508)
SP_JOBDEPSEQ_SIZE_INVALID (509)
SP_JOBDEPSEQ_JOBDEPS_NULL (511)
SP_DEPJOBID_INVALID (512)
SP_DEPJOBSTIME_INVALID (513)
SP_TARGJOBID_INVALID (514)
SP_TARGJOBSTIME_INVALID (515)
SP_EARLIESTTIMEUNITS_INVALID (516)
SP_LATESTTIMEUNITS_INVALID (517)
SP_TARGETTIMEUNITS_INVALID (518)
SP_COSTID_INVALID (519)
SP_COSTID_DOES_NOT_EXIST (520)
SP_DEPEMPTYPE_INVALID (521)
SP_TARGET_TIME_BEFORE (526)
SP_TARGET_TIME_AFTER (527)
SP_CYCLIC_DEPENDENCY_TIME (528)
SP_DEPENDENCY_CONSTRAINT (529)
SP_DEPJOBID_DOES_NOT_EXIST (530)
SP_TARGJOBID_DOES_NOT_EXIST (531)
SP_CYCLIC_DEPENDENCY_EMP (532)
SP_DIFFERENT_FRUS (533)
SP_DEPJOBID_ALREADY_IN_GROUP (540)
SP_TARGJOBID_ALREADY_IN_GROUP (541)
SP_BDGRETJOBSSEQ_NULL (542)
SP_MULTIJOBID_INVALID (563)
SP_BDGJOBSEQ_DUPLICATE_JOBIDS (564)
SP_DEPJOBID_SAME_AS_TARGJOBID (565)
SP_JOB_NO_DEPENDENCY (566)
SP_NO_DEPENDENCIES (567)
SP_LATEST_BEFORE_EARLIEST (572)
SP_DEPENDENCY_ON_UNRESOURCED_JOB (573)
SP_BDGJOBSEQ_NOT_SAME_ITAA (574)
SP_ISPRIMARYJOB_INVALID (575)
SP_COSTID_NO_TARGET_TIME (576)
SP_JOBDEPSEQ_DUPLICATE_DEPENDENCIES (601)
SP_DIFFERENT_DRUS (621)
SP_DRU_NO_FRUS (625)
SP_JOBID_OUTSIDE_HORIZON (626)
SP_DEPENDENCY_ON_APPOINTMENT_JOB (815)
SP_VWDL_COMBINATION_INVALID (822)
SP_VWDL_LOCATION_INVALID (823)
SP_VWDL_TRAVEL_INVALID (824)

Browser not supported