Pass Through Call to Scheduling's "Job Book Request" API

This RESTified API will perform a pass-through call to the Scheduling sub-system's "Book Job Request" API (when configured).

URL

PUT /up/v5/rest/scheduling/BookJob

HTTP Request Body

This request requires a JSON object supplied in the HTTP request body, which defines the parameters that will be passed through to the Scheduling "Book Job Request" API.

Book Job Request Object Format

Book Job Request JSON

js

Book Job Request Object Properties (bold property names indicate required field)

Property	Type	Length	Description	Req?	Field Mapping: Scheduling
`Id`	`string`	SS: 50	Caller’s identifier of the job to be booked. It must be unique in the ServiceOptimizer database, unless AllowRebook (below) is True	Yes	jobID
WorkType	object		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.	Yes	see WorkType.objects
Location	object		Pending	Yes	see Location.objects
vwdlLocationType	string SS: EmpLocType	SS: See Valid Values	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. SS Valid Values: "Home", "Work", "Depot", "Supplied", "None"	No	vwdlLocationType
RestrictionRef	string SS: RestrictionRef (string)	SS: 30	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.	No	restrictionRef
Flags	object		Cancel Dependency Group Jobs	No	See Flags.objects
ExtraDuraton	string		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.	No	extraDuration
ReqProvider	array		Allows for a list of up to 10 reqEmps to be specified.	No	see RegProvider.objects
ReqUnit	object		Pass through parameter to the Scheduling BookJob API.	No	see RegUnit.objects
Priority	string SS: integer		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. Priority the job should have. If priority isn’t being used, it should be set to 50. Must be set between 1 and 99.	No	?
Importance	string SS: integer		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.	No	importance
Booking	object		Pass through parameter to the Scheduling BookJob API.	Yes	see Booking.objects
ServHoursPreDefPatts	object		A set of Service Hours patterns that are pre-defined in ServiceOptimizer.ServHoursPreDefPatts can’t be supplied as well as ServHoursPatts (below).	No	see ServHoursPreDefPatts.objects
ServHoursPatts	array		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).	No	see ServHoursPatts.objects
AccHoursPatts	array		A set of Access Hours patterns for the job. The actual Access Hours for each pattern must be the same, though the `DateRange` can be different.	No	see AccHoursPatts.objects
BookOptions	object		Pass through parameter to the Scheduling BookJob API.		see BookOptions.objects

HTTP Response

Success

On success, a JSON-formatted version of the Scheduling "Book Job Request" API response will be returned.

js

Error

On error, a JSON-formatted version of the Scheduling "Book Job Request" API response will be returned.

js

Return Codes

In addition to the Standard Return Codes, and the Scheduling Error codes, the possible Return Codes from this API are:

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)
SP_VWDL_COMBINATION_INVALID (822)
SP_VWDL_LOCATION_INVALID (823)
SP_VWDL_TRAVEL_INVALID (824)

Please Note:

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