On This Page:

Related Pages:

The sp:ApptBookRequest API method can be used to book a job, based on an offered appointment.

Description

A particular appointment time can be reserved in ServiceOptimizer by calling the sp:ApptBookRequest API method. It will normally be called after a customer has chosen one of the possible appointments returned from a call to the Request Appointments SOAP API, however sp:ApptBookRequest can be called directly, in which case the system invokes the Request Appointments SOAP API and books the ‘best’ solution returned.

When called directly, this API may be used to book appointments of long duration which require splitting/fragmenting across multiple shifts, however, if the Request Appointments SOAP API interface has been called initially, then the resultant offers must instead be booked using the Book Split Dependency Group Jobs SOAP API.

Definition

The definition of this API is:

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:ApptBookRequest>`
	`<jobID>?</jobID>`			`JobID`	is the caller’s identifier of the job to be booked. It must be unique in the ServiceOptimizer database, unless AllowRebook (below) is 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. 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.
	`<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. 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.
	`<longitude>?</longitude>`			`Double`	Is the longitude of the location of the job, format length 18 with max 9 decimal places. 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.
	`<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.
	`<date>?</date>`			`spDate`	The date on which the job is to be booked. Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.
	`<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`	If the value of this field is True, the call to ApptBookRequestwill 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 ApptBookRequestcall 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. 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.
	`<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. The extra time is in minutes. 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.
	`<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. 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.
		`<reqSkills>`
			`<skillID>?</skillID>`	`SkillID`
			`<skillLevel>?</skillLevel>`	`int`	is the level of the skillID 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 supplied value for this field should be 1.
		`</reqSkills>`
	`</extraSkills>`
	`<ListReqEmps>`				Allows for a list of up to 10 reqEmps to be specified. See MPX employee options. 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.
		`<reqEmp>`
			`<empID>?</empID>`	`EmpID`	names preferred, mandatory or excluded operatives for this job
			`<MPX>?</MPX>`
		`</reqEmp>`
	`</ListReqEmps>`
	`<sameUnit>?</sameUnit>`			`SameUnit`	if Final, specifies that the job should only be assigned to an employee in the FRU supplied in Unit field in the corresponding previous call to OfferApptRequest. This option relies on OfferToken (see below) being the one which was supplied from that OfferApptRequest) call. Values other than Final are not implemented and will cause the code SP_UNITTYPE_INVALID (77) to be returned. If OfferToken is *not* supplied, this field must also be omitted, otherwise SP_UNITTYPE_INVALID (77) is returned.
	`<stdExtraDuration>?</stdExtraDuration>`			`StdExtraDuration`	specifies one of two things: that extra time (how much time is set up in the ServiceOptimizer database) should be added to the normal amount for the job type (useful, for example, if additional time should be allowed for a key to be collected (LocalKeyPU)), or that this job has a ‘special’ duration (only DurationOneDay is currently implemented) 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.
	`<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.
	`<priority>?</priority>`			`int`	is the priority the job should have. If priority isn’t being used, it should be set to 50. Must be set 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. 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.
	`<offerToken>?</offerToken>`			`OfferToken`	should have the same value that was returned by ApptOfferRequest. It is used to speed up the booking process. If OfferToken is not supplied, a call to ApptOfferRequest is done first, and the lowest ranked appointment returned is chosen and booked.
	`<promBand>`
		`<timeBandID>?</timeBandID>`		`TimeBandID`	is the name of the time band of the promise required, e.g. “M” for a time band which has been set up in ServiceOptimizer as 8:30 to 12:30. The job will be started within these two times. Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.
		`<start>?</start>`		`spTime`	start time overrides the start times defined by the timeBandID above. If neither timeBandID nor start is supplied, then defaults to 00:00 (start of day). Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.
		`<end>?</end>`		`spTime`	end time overrides the end times defined by the timeBandID above. If neither timeBandID nor end is supplied, then defaults to 24:00 (end of day). Where this booking is based on an offer from a previous call to OfferAppts, this must be the value obtained from the selected offer.
	`</promBand>`
	`<bookOptions>`				See the "Offer/Book Options" for the definitions of the permitted `bookOptions` listed below. The `bookOptions` below that are also valid for the Request Appointments SOAP API call must be passed in as they were in the call to `sp:OfferApptRequest`. For example, if `AllowEmpOT` was not passed into the Request Appointments SOAP API call, then it must also not be passed into the `sp:ApptBookRequest` call; or, if `AllowEmpOT` was set to `true` for the Request Appointments SOAP API call, then it must also be set to `true` for the `sp:ApptBookRequest` call.
		`<AllowEmpOT>?</AllowEmpOT>`
		`<SpareIgnVanStock>?</SpareIgnVanStock>`
		`<ReqConfirm>?</ReqConfirm>`
	`</bookOptions>`
	`<forceOptions>`				Please refer to the Force Options section on the Integration ServiceOptimizer Common Options page for defintions and settings values. This field is not valid for use where the appointment is of long duration and required splitting across multiple shifts – any values passed will result in a return code of `SP_FORCEOPTIONS_INVALID (150)`.
		`<InTray>?</InTray>`
		`<InTrayWithSkill>?</InTrayWithSkill>`
		`<SpareForceGo>?</SpareForceGo>`
		`<Reassign>?</Reassign>`
		`<IgnoreCapacity>?</IgnoreCapacity>`
		`<NoTravel>?</NoTravel>`
		`<NoLocalKnowledge>?</NoLocalKnowledge>`
	`</forceOptions>`
	`<reqSpares>`				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.
					See Integration ServiceOptimizer Common API Concepts Spares Information for details of the `<reqSpares>` structure.
	`</reqSpares>`
	`<deliverySize>?</deliverySize>`			`int`	is the amount of space occupied by equipment that will 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. 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.
	`<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. 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.
	`<siteID>?</siteID>`			`SiteID`	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. 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.
	`<groupID>?</groupID>`			`GroupID`	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. 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.
	`<capacityCategory>?</capacityCategory>`			`CapacityCategoryName`	Capacity constraints, in the form of a reserved or/and limit level can be defined for each capacityCategory and a check can be done in ApptOfferRequest so that only those offers where none of these constraints would be broken are returned. 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.
	`<customer>`
					See section 4.4.3
	`</customer>`
	`<desc>?</desc>`			`desc`	See section 4.4.4
	`<desc2>?</desc2>`			`desc2`	See section 4.4.4
`</sp:ApptBookRequest>`

All of the fields to do with dates and times are assumed to use customer local TZ, i.e. local to the region where the job is located.

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:ApptBookResponse>`
	`<return_>?</return_>`			This contains the standard return structure.
	`<bookInfo>`
		`<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.
	`</bookInfo>`
`</sp:ApptBookResponse>`

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_BAND_INVALID (16)
SP_ABS_LOGGED_ERROR (20)
SP_EMP_UNAVAILABLE (21)
SP_JOBID_EXISTS (23)
SP_SKILL_INVALID (27)
SP_PROM_SET_INVALID (30)
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_PROM_START_TIME_INVALID (60)
SP_PROM_END_TIME_INVALID (61)
SP_SEPMAX_EXCEEDED (73)
SP_REQTYPE_INVALID (74)
SP_EMP_NOT_SKILLED (75)
SP_STDEXTRADURATION_INVALID (76)
SP_UNITTYPE_INVALID (77)
SP_OPTIONS_INVALID (80)
SP_OFFERTOKEN_INVALID (82)
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_OPTION_COMBINATION_INVALID (159)
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_OFFERTOKEN_OPTIONS_MISMATCH (336)
SP_OK_IMPORTANCE_IGNORED (346)
SP_OK_ABS_SEARCH_TIMEOUT (369)
SP_NTA_ABS_SEARCH_TIMEOUT (370)
SP_DST_TIME_INVALID (379)
SP_IMPORTANCE_NO_COST (476)
SP_SITEID_INVALID (500)
SP_GROUPID_INVALID (501)
SP_NO_POSTINGS (545)
SP_CAPACITYCATEGORY_NOT_DEFINED (581)
SP_CAPACITYCATEGORY_DOES_NOT_EXIST (602)
SP_CAPACITYCATEGORY_INVALID (603)
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)

Since a search for available capacity may be performed as part of a Integration ServiceOptimizer Book Appointment SOAP API call (i.e. when no offerToken parameter is supplied), it’s possible that SP_OK_ABS_SEARCH_TIMEOUT (369) or SP_NTA_ABS_SEARCH_TIMEOUT(370) will 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. The Appointment Search Window (see 6.2) will be used to limit the time period over which a search is done.

If a SOAP API has been made with the login information included in the call, then all of the error codes returned by the login request can also be returned. See the Integration ServiceOptimizer Login SOAP API for a list of all login error codes.

Browser not supported