Status

colour	Green
title	5.4.0

A pass-through API to ServiceScheduling (when configured) which allows the ServiceScheduling's "Job Book Request API" API to be called.

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

Info
In this context, the ServiceScheduling "Book Appointment" API is the `sp:JobBookRequest` API API.

Panel

borderColor	grey
bgColor	whitesmoke
borderStyle	solid

On this page:

Table of Contents

maxLevel	2

Related pages:

Resource URL Summary

Panel

borderColor	grey
bgColor	whitesmoke
borderStyle	solid

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

PUT /up/v5/rest/scheduling/BookJob

Include Page

	_Default HTTP Headers
	_Default HTTP Headers

Panel

borderColor	#D3D3D3

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

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

URL

Panel

borderColor	grey
bgColor	whitesmoke
borderStyle	solid

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 ServiceScheduling "Book Job Request" API.

Book Job Request Object Format

Code Block

language	js
title	Book Job Request JSON
collapse	true

{
	"Id": "",
	"WorkType": {
		"Name": "",
		"Skills": [{
			"Id": "",
			"Comp": ""
		}]
	},
	"Location": {
		"Address": {
			"AddrLine1": "",
			"AddrLine2": "",
			"City": "",
			"PostalCode": "",
			"Region": "",
			"Latitude": "",
			"Longitude": ""
		},
		"LocationNum": "",
		"Name": "",
		"SiteId": "",
		"Contacts": [{
			"FirstName": "",
			"LastName": "",
			"ContactPoint": [{
					"Mode": "Phone",
					"Value": "7637548024"
				},
				{
					"Mode": "Phone",
					"Value": "223123123"
				}
			]
		}]
	},
	"vwdlLocationType": "",
	"RestrictionRef": "",
	"Flags": {
		"AllowRebook": false
	},
	"ExtraDuraton": "",
	"ExtraOverhead": "",
	"ReqProvider": [{
		"Id": "",
		"MPX": ""
	}],
	"ReqUnit": {
		"unitType": "",
		"RUID": ""
	},
	"Priority": "",
	"Importance": "",
	"Booking": {
		"BookLocID": "",
		"ContractEarliest": "",
		"ContractLatest": "",
		"Offer": {
			"GroupID": ""
		},
		"OpenAccHoursOvrs": {
			"OpenType": "",
			"OpenHours": [{
				"Start": "",
				"End": ""
			}]
		},
		"ClosedAccHoursOvrs": {
			"ClosedHours": [{
				"Start": "",
				"End": ""
			}]
		},
		"ClosedPubHols": {
			"PubHolSets": [
				"",
				""
			]
		},
		"ClosedDates": [{
			"Start": "",
			"End": ""
		}]
	},
	"ServHoursPreDefPatts": {
		"ServHoursPreDef": [{
			"DateRange": {
				"Start": "",
				"End": "",
				"ServHoursPattID": ""
			}
		}]
	},
	"ServHoursPatts": [{
		"DateRange": {
			"Start": "",
			"End": ""
		},
		"DayAndTimes": {
			"Day": "",
			"Start": "",
			"End": ""
		},
		"GracePeriod": ""
	}],
	"AccHoursPatts": [{
		"DateRange": {
			"Start": "",
			"End": ""
		},
		"DayAndTimes": {
			"Day": "",
			"Start": "",
			"End": ""
		}
	}],
	"BookOptions": {
		"AllowEmpOT": false,
		"SpareIgnVanStock": false,
		"FixToEmp": false,
		"ServAsAccHours": false,
		"CallToFix": false,
		"ReqConfirm": false,
		"NonConsecShift": false,
		"ConsecShift": false,
		"ContigShift": false
	},
	"ForceOptions": {
		"InTray": false,
		"InTrayWithSkill": false,
		"InTrayAfterAll": false,
		"SpareForceGo": false,
		"Reassign": false,
		"IgnoreCapacity": false,
		"NoTravel": false,
		"NoLocalKnowledge": false,
		"IgnoreAvailable": false,
		"IgnoreSkills": false
	},
	"ReqSpares": [{
		"spare": "",
		"qty": ""
	}],
	"DeliverySize": "",
	"PickupSize": "",
	"CapacityCategory": "",
	"Desc": [
		"",
		""
	],
	"Desc2": ""
}

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

Property

Type Length Description Req? Fied Mapping: ServiceScheduling
`Id`
`string`
`SS: JobID (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
see _WorkType Object Format. yes -

HTTP Response

Success

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

Code Block

language	js

{
    "Success" : true,
    "Code" : 0,
    "Message" : "OK",
    "Payload" : {
        "result" : {
            "type" : "OK",
            "code" : "0"
        },
        "TravelTime" : "3",
        "WorkItems" : [
            {
                "Id" : "Dep-1306",
                "Tech" : "DE3_9_01",
                "ETA" : "2006-01-03T08:01",
                "IRU" : "EMID_I01",
                "FRU" : "EMIDLAND"
            },
            {
                "Id" : "Dep-1307",
                "Tech" : "DE3_9_01",
                "ETA" : "2006-01-03T09:02",
                "IRU" : "EMID_I01",
                "FRU" : "EMIDLAND"
            }
        ]
    }
}

Error

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

Code Block

language	js

{
    "Success": false,
    "Code": 9,
    "Payload": {
        "returnCode": {
            "type": "Error",
            "code": "SCH Error Code"
        }
    }
}

Return Codes

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

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

Note

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

Version	Old Version 5	New Version 6
Changes made by	Jason Andrew	Jason Andrew
Saved on	Aug 03, 2023	Aug 03, 2023

Versions Compared

Key

Resource URL Summary

API Specifics

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

URL

HTTP Request Body

Book Job Request Object Format

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

Type Length Description Req? Fied Mapping: ServiceScheduling
`Id`
`string`
`SS: JobID (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
see _WorkType Object Format. yes -

HTTP Response

Success

Return Codes

Content Comparison

Versions Compared

Key

Resource URL Summary

API Specifics

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

URL

HTTP Request Body

Book Job Request Object Format

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

TypeLengthDescriptionReq?Fied Mapping: ServiceSchedulingIdstringSS: JobID (string)SS: 50Caller’s identifier of the job to be booked. It must be unique in the ServiceOptimizer database, unless AllowRebook (below) is True.YesJobIdWorkTypeobjectsee _WorkType Object Format.yes-

HTTP Response

Success

Return Codes

Type Length Description Req? Fied Mapping: ServiceScheduling
`Id`
`string`
`SS: JobID (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
see _WorkType Object Format. yes -