On This Page:

Related Pages:

The sp:JobBookRequest API method can be used to book a job, without first obtaining an offered appointment.

Description

The sp:JobBookRequest API method creates a new job in ServiceOptimizer without having to go through the appointment offering process. It is normally used for business to business relationships where an exact appointment is not given to the customer; rather, an SLA or response time agreement is in place.

As with the Book Appointment SOAP API, this interface may be used to book long duration jobs (ones requiring more than one shift) with the system automatically choosing the best solution from the possible positions available.

Definition

The definition of this API is:

Click here to expand...

Web Service						Type	Description	Req?	Val?
`<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.
	`<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
	`<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 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 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 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.
			`</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.
			`<reqEmp>`
				`<empID>?</empID>`		`EmpID`	names preferred, mandatory or excluded operatives for this job
				`<MPX>?</MPX>`
			`</reqEmp>`
	`</ListReqEmps>`
	`<reqUnit>`
			`<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.
			`<RUID>?</RUID>`			`RUID`
	`</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
	`<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
	`<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>`					`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
	`<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
	`<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
			`<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.
					`<end>?</end>`	`spDate`
				`</dateRange>`
				`<servHoursPattID>?</servHoursPattID>`		`ServHoursPattID`	The same ServHoursPattID must be supplied for each, though the accompanying DateRanges can be different.
			`</servHoursPreDef>`
	`</servHoursPreDefPatts>`
	`<servHoursPatts>`
							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>`
							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.
			`<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.
			`<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>`						See the "Offer/Book Options" for the definitions of the permitted `bookOptions` listed below.
			`<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>`						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)`.
			`<InTray>?</InTray>`
			`<InTrayWithSkill>?</InTrayWithSkill>`
			`<InTrayAfterAll>?</InTrayAfterAll>`
			`<SpareForceGo>?</SpareForceGo>`
			`<Reassign>?</Reassign>`
			`<IgnoreCapacity>?</IgnoreCapacity>`
			`<NoTravel>?</NoTravel>`
			`<NoLocalKnowledge>?</NoLocalKnowledge>`
	`</forceOptions>`
	`<reqSpares>`
							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.
	`<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.
	`<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).
`</sp:JobBookRequest>`

All of the fields to do with dates and times (contract hours and access hours) are local to what is specified in the tz_BJAPIIn database parameter (see [1]). This can be configured such that the dates and times are local to the timezone of the region where the job is located (customer local) or local to the default timezone.

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:JobBookResponse>`
	<result>?</result>			This contains the standard return structure
	`<bookJobInfo>`
		`<empID>?</empID>`	`EmpID`	The ID of the employee to whom this Job has been allocated. This parameter is not returned if the Job is un-resourced.
		`<IRU>?</IRU>`		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>`		the ID of the FRU to which the job has been booked
	`</bookJobInfo>`
`</sp:JobBookResponse>`

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

Click here to expand...

SP_OK (0)
SP_JOBID_INVALID (1)
SP_JOBTYPE_INVALID (2)
SP_POSTCODE_INVALID (3)
SP_LOCATION_INVALID (4)
SP_EMPID_INVALID (5)
SP_NO_TIME_AVAILABLE (8)
SP_DURATION_INVALID (12)
SP_DATE_INVALID (14)
SP_EMP_UNAVAILABLE (21)
SP_JOBID_EXISTS (23)
SP_SKILL_INVALID (27)
SP_UNIT_INVALID (28)
SP_END_NOT_GT_START_TIME (31)
SP_SKILLLEVEL_INVALID (32)
SP_CANNOT_FORCE_SKILL (33)
SP_JOBTYPE_NOT_IN_DATE (49)
SP_JOBTYPE_CANNOT_BE_FORCED (51)
SP_OUTSIDE_HORIZON (53)
SP_EXTRA_DURATION_INVALID (54)
SP_REQTYPE_INVALID (74)
SP_EMP_NOT_SKILLED (75)
SP_UNITTYPE_INVALID (77)
SP_OPTIONS_INVALID (80)
SP_PRIORITY_INVALID (81)
SP_ALLOWREBOOK_INVALID (87)
SP_EMPSMAX_EXCEEDED (88)
SP_EMPID_DUPLICATED (89)
SP_CUSTID_INVALID (95)
SP_CUSTNAME_INVALID (96)
SP_CUSTADD1_INVALID (97)
SP_CUSTADD2_INVALID (98)
SP_CUSTADD3_INVALID (99)
SP_CUSTADD4_INVALID (100)
SP_CONTACTNAME_INVALID (101)
SP_CUSTPHONE1_INVALID (102)
SP_CUSTPHONE2_INVALID (103)
SP_DESC1_INVALID (104)
SP_DESC2_INVALID (105)
SP_DESC3_INVALID (106)
SP_DESC4_INVALID (107)
SP_SPAREID_INVALID (111)
SP_QUANTITY_INVALID (112)
SP_NO_REG_TO_RU_MAPPING (115)
SP_EXTRASKILL_DUPLICATED (118)
SP_JOBSKILLSMAX_EXCEEDED (119)
SP_SPARE_SUBS_EXCEEDED (147)
SP_FORCEOPTIONS_INVALID (150)
SP_EMP_ZERO_LK (155)
SP_NO_SKILL (156)
SP_OPTION_COMBINATION_INVALID (159)
SP_EMP_NOT_POSTED (178)
SP_POSTCODE_NOT_MAPPED (179)
SP_EMPID_DOES_NOT_EXIST (231)
SP_SPARE_SUB_DUPLICATED (254)
SP_IMPORTANCE_INVALID (287)
SP_DELIVERY_SIZE_INVALID (333)
SP_PICKUP_SIZE_INVALID (334)
SP_DESCRIPTION2_INVALID (335)
SP_OK_IMPORTANCE_IGNORED (346)
SP_OK_ABS_SEARCH_TIMEOUT (369)
SP_NTA_ABS_SEARCH_TIMEOUT (370)
SP_DST_TIME_INVALID (379)
SP_SERVHOURS_DUPLICATED (389)
SP_ACCHOURS_DUPLICATED (390)
SP_OPEN_ENDED_ACCHOURS_NOT_ALLOWED (391)
SP_DOTW_INVALID (394)
SP_GRACE_PERIOD_INVALID (395)
SP_SERVHOURS_STARTTIME_INVALID (397)
SP_SERVHOURS_ENDTIME_INVALID (398)
SP_SERVHOURS_OVERLAP (399)
SP_SERVHOURS_STARTDATE_INVALID (400)
SP_SERVHOURS_ENDDATE_INVALID (401)
SP_SERVHOURSPATTSEQ_PATTS_NULL (403)
SP_SERVHOURSPREDEFPATTSEQ_PATTS_NULL (405)
SP_SERVHOURS_PATTID_INVALID (406)
SP_SERVHOURS_PATTID_DOES_NOT_EXIST (407)
SP_DAYANDTIMEPERIODSEQ_PERIODS_NULL (410)
SP_ACCHOURS_STARTTIME_INVALID (411)
SP_ACCHOURS_ENDTIME_INVALID (412)
SP_ACCHOURS_OVERLAP (413)
SP_ACCHOURS_STARTDATE_INVALID (414)
SP_ACCHOURS_ENDDATE_INVALID (415)
SP_ACCHOURSPATTSEQ_PATTS_NULL (417)
SP_SERVHOURSPATTSEQ_SIZE_INVALID (418)
SP_DAYANDTIMEPERIODSEQ_SIZE_INVALID (419)
SP_SERVHOURSPREDEFPATTSEQ_SIZE_INVALID (420)
SP_ACCHOURSPATTSEQ_SIZE_INVALID (421)
SP_SERVHOURSPATTSEQ_NOT_SAME (429)
SP_DATETIMERANGESEQ_RANGES_NULL (431)
SP_DATETIMERANGESEQ_SIZE_INVALID (432)
SP_OPENHOURSOVRTYPE_INVALID (433)
SP_OPENACCHOURSOVR_START_INVALID (434)
SP_OPENACCHOURSOVR_END_INVALID (435)
SP_OPENACCHOURSOVR_END_NOT_GT_START (436)
SP_CLOSEDACCHOURSOVR_START_INVALID (437)
SP_CLOSEDACCHOURSOVR_END_INVALID (438)
SP_CLOSEDACCHOURSOVR_END_NOT_GT_START (439)
SP_CONTRACT_EARLIEST_INVALID (441)
SP_CONTRACT_LATEST_INVALID (442)
SP_NO_ACCHOURS (443)
SP_SERVHOURS_DATERANGE_END_NOT_GT_START (444)
SP_SERVHOURS_DATERANGE_OVERLAP (446)
SP_SERVHOURSPREDEFPATTSEQ_NOT_SAME (448)
SP_CLOSEDDATES_SEQ_SIZE_INVALID (460)
SP_CLOSEDDATES_SEQ_DATERANGES_NULL (462)
SP_CLOSEDDATES_STARTDATE_INVALID (463)
SP_CLOSEDDATES_ENDDATE_INVALID (464)
SP_ACCHOURS_DATERANGE_END_NOT_GT_START (465)
SP_ACCHOURS_DATERANGE_OVERLAP (466)
SP_ACCHOURSPATTSEQ_NOT_SAME (468)
SP_CLOSEDDATES_END_NOT_GT_START (470)
SP_PRIORITY_NO_COST (475)
SP_IMPORTANCE_NO_COST (476)
SP_SITEID_INVALID (500)
SP_GROUPID_INVALID (501)
SP_MULTIJOBID_ALREADY_EXISTS (539)
SP_NO_POSTINGS (545)
SP_CAPACITYCATEGORY_NOT_DEFINED (581)
SP_CAPACITYCATEGORY_DOES_NOT_EXIST (602)
SP_CAPACITYCATEGORY_INVALID (603)
SP_DRU_NO_FRUS (625)
SP_VEHICLE_CAPACITY_EXCEEDED (662)
SP_LISTREQEMPS_NULL (684)
SP_LISTREQEMPS_SIZE_GT_MAX (685)
SP_LISTREQEMPS_SIZE_INVALID (686)
SP_LISTREQEMPS_COMBINATION_INVALID (689)
SP_UDLOC_FAILED_REGION_MAPPING (692)
SP_TOO_MANY_MANDATORYORDERED (694)
SP_RESTRICTION_REF_DOES_NOT_EXIST (697)

Since a search for available capacity is done as part of JobBookRequest, ABS_search_timeout can be used, and so SP_OK_ABS_SEARCH_TIMEOUT (369) (369) or SP_NTA_ABS_SEARCH_TIMEOUT (370) (370) may be returned. ABS_search_timeout won’t be used if Reassign is to be tried, since the time allowed for re-assign is separately limited by the timeout ABS_reassign_timeout.

Within this window, the job can only be allocated to start (and finish if it’s a call-to-fix job) within its Access Hours.

If InTray is set, a search window isn’t needed and effectively the whole memory horizon is searched.

Browser not supported