On This Page:

Related Pages:

The sp:ApptOfferRequest API method can be used to request possible appointments for a job.

Description

The sp:ApptOfferRequest API method returns possible customer appointments which match a set of criteria.

The response will either return an offers structure or a splitOffers structure (see below). The number of individual offers in either response structure can vary and are returned in total cost order, with the lowest cost being first.

Offers

In conversation with the consumer, an appropriate offer can be chosen and the corresponding job booked. Offers (in an offers structure) must be booked using the Book Appointment SOAP API.

Split Offers

When a call to sp:ApptOfferRequest is for a job whose job type specifies that it can be fragmented and the job is of sufficient duration, a set of offers called an offer group may be returned. (In some cases, where the length of the job is greater than the Long Job: Split Threshold but less than the length of the operative’s shift, a single offer can be returned as well.) All of the offers in an offer group are for the same operative. Where the last part of the job is short enough, the previous job is the last job in its shift, and the AllowEmpOT option has been set, it will be included as AOT in that previous shift; this will save the extra visit.

In conversation with the consumer, an appropriate offer group can be chosen and the corresponding set of jobs booked. Split offers (in a splitOffers structure) must be booked using the Book Split Dependency Group Jobs SOAP API.

Thereafter, the functionality available (e.g. Gantt, SOAP call, dispatch, jeopardy) is the same as for any other dependency group.

Definition

The definition of this API is:

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:ApptOfferRequest>`
	`<numReq>?</numReq>`			`unsigned int`	The number of appointments required (of type `numReqType`, below). If not set, then a default is used (database parameter `num_req_default`). This field has a maximum value of `99`. The total number of appointments returned may be fewer than the number defined by the `numReq` parameter, in the event that the requested number of appointments cannot be found. However, the total number of appointments returned may also exceed the number defined by the `numReq` parameter, as appointments of different `PromTypeID`s from those defined by the `numReqType` parameter may also be returned; however, the total number of appointments of the type requested will not exceed `numReq`.
	`<numReqType>?</numReqType>`			`PromTypeID`	The type of appointment (usually whole-day, half-day, or 2-hour) which `numReq` counts. If not set, then the type is inferred from bands in the specified promise set `promSet` (though if the promise set contains time bands of more than one type, `SP_PROMSET_MULTIPLE_BAND_TYPES (645)` is returned). For long duration jobs, that are to be split across multiple shifts, only offers of this type are returned, even if the `promSet` also contains other types.
	`<index>?</index>`			`unsigned int`	The sequence number of the *first* appointment of type `numReqType` required. For example, if 6 appointments are initially wanted, `index` is set to 1 and `numReq` to 6. If none of these appointments is acceptable, the next 6 available (of type `numReqType`) can be requested by setting `index` to 7 and leaving `numReq` at 6. Note: This field has a maximum allowed value of `999`.
	`<jobType>?</jobType>`			`JobTypeID`	The type of work to be performed.
	`<postcode>?</postcode>`			`Postcode`	The *full* postal code of the location of the job.
	`<latitude>?</latitude>`			`double`	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. 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.
	`<promSet>?</promSet>`			`PromSetID`	The name of the set of promise time bands to be used to translate available capacity into the returned offered appointments. If certain force options are to be used (see below) the `promSet` should contain only a single, all day, band.
	`<extraDuration>?</extraDuration>`			`unsigned int`	The time (in minutes) required to complete the job in addition to what is defined in ServiceOptimizer for the job's type. The maximum value that will be accepted for this field plus `extraOverhead` 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`	The extra overhead time required to do this job in addition to the overhead time defined for the job's type. This is the extra time in minutes.
	`<extraSkills>`				A list of the extra skills needed to do this job, in addition to those specified in ServiceOptimizer for the job's type. If one or more of the supplied `extraSkills` is already required by the `JobType`, it will be ignored, unless it is the first `extraSkill` and the `skillLevel` (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>`	`unsigned int`	The level of the extra skill required in the skillID field, above. If the first of the skillIDspecifies a skill which is already required by the `JobType`, then `skillLevel` 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 `reqEmp`s to be specified, specifying any required MPX employee options.
		`<reqEmp>`
			`<empID>?</empID>`	`EmpID`	Defined a preferred, mandatory or excluded operative for the job.
			`<MPX>?</MPX>`
		`</reqEmp>`
	`</ListReqEmps>`
	`<stdExtraDuration>?</stdExtraDuration>`			`StdExtraDuration`	Specially defined extra time added to the normal amount for the job type. This time is specified in the DB.
	`<reqUnit>`
		`<unitType>?</unitType>`		`UnitType`	If `Final`, specifies that the `RUID` field is an FRU ID, or, if `DRU`, specifies that `RUID` is a DRU ID.
		`<RUID>?</RUID>`		`RUID`	The name of an FRU or DRU (set of FRUs) that must provide the employee assigned to the job. The job must be located at a postcode that is mapped to the supplied FRU or DRU, whether or not any of the In-Tray options are true (see `forceOptions`).
	`</reqUnit>`
	`<days>?</days>`			`DayOfTheWeek`	Represents the days of the week for which appointments are required, starting on Monday. The character `Y` means that appointments whose arrival time (ETA) is on this day are required; any other character means they aren’t. `YYYYYNN`, for example, means that appointments are required for weekdays only. If a `NULL` string is supplied, the default value `YYYYYNN` is used. When requesting appointments for long duration jobs, that are to be split across multiple shifts, the segments of the long job appointments will only occur on the requested day(s).
	`<start>`				Combined with the `end` parameter, defines an inclusive date and time range between which appointments are required. Note that the `start` and `end` parameter's `time` values can *not* be used to define a time band between which appointments should be returned on *every* day within the range defined by the `start` and `end` parameter's `date` values; rather, the start and end parameters define only the start and end points of the range in which appointments are required. To define a time band for each day in the range `start` to `end` range, use the `band` parameter. In the event that an invalid inclusive date and time range between which appointments are required is specified, either `SP_NO_TIME_AVAILABLE (8)` or `SP_END_NOT_GE_START_DATE (19)` will be returned.
		`<date>?</date>`		`spDate`	If not supplied, ServiceOptimizer will use a default start date and time value of `<now>` plus the number of days specified in the Booking Lead Time for the `jobType`.
		`<time>?</time>`		`Time`	If not supplied, ServiceOptimizer will use a default of `0000` on the start date (above), or `<now>` if the start date is `<today>`.
	`</start>`
	`<end>`				Combined with the `start` parameter, defines an inclusive date and time range between which appointments are required. See the description of the `start` parameter for details.
		`<date>?</date>`		`spDate`	If not supplied, ServiceOptimizer will use a default of the start date (above) plus the Appointment Booking Horizon (see `abs_appt_days_after`).
		`<time>?</time>`		`Time`	If not supplied, ServiceOptimizer will use a default of `2400` on the end date.
	`</end>`
	`<preferredDate>?</preferredDate>`			`spDate`	Defines the date of the appointments which should be returned first. If `preferredDate` is outside the date range defined by the `start` and `end` `date` parameters, additional appointments may be returned, even if the `start` date value has been defaulted using the Booking Lead Time (as described above). Note: When requesting appointments for long duration jobs, that are to be split across multiple shifts, the `preferredDate` parameter must not be supplied; supplying the parameter will result in inconsistent results.
	`<band>`				The `band` parameters `timeBandID`, `start`, and `end` values are used to generate a notional filter band, FilterStartTime to FilterEndTime. The FilterStartTime is set to: The value of `start`, if supplied; or, if not The `timeBandID`'s `StartTime`, if `timeBandID` is supplied; or, if not The start of the day. Similarly, the FilterEndTime is set to: The value of `end`, if supplied; or, if not The `timeBandID`'s `EndTime`, if `timeBandID` is supplied; or, if not The end of the day. As jobs can span midnight, the FilterEndTime can appear to be before FilterStartTime, but this is interpreted as being on the next day. If the filter band is totally outside the initially-generated offer (i.e. there is no overlap between them), the offer is not returned at all. If FilterStartTime is within an offered appointment, i.e. is between the initially-generated values of PromStartTime and PromEndTime (see later in this section), then PromStartTime will be changed to FilterStartTime before returning that offer. Similarly, if FilterEndTime is within the appointment, then PromEndTime will be changed to FilterEndTime. Note: An initially-generated offer can never be lengthened by application of the filter band, only shortened.
		`<timeBandID>?</timeBandID>`		`TimeBandID`	The name of a time band that can be supplied to further filter out certain appointments and to modify the start and/or end times of the offers returned.
		`<start>?</start>`		`Time`
		`<end>?</end>`		`Time`
	`</band>`
	`<importance>?</importance>`			`int`	When set, will generate offers for a more important job by assuming that less important jobs can be de-allocated when the job is subsequently booked.
	`<offerOptions>`				See the Offer/Book Options section for the definitions of the permitted `offerOptions` listed below.
		`<AllowEmpOT>?</AllowEmpOT>`			Note: When requesting appointments for long duration jobs, that are to be split across multiple shifts, overtime will only ever be used (when appropriate) for the final shift; overtime will not be used on any other shift.
		`<OfferTextEmpID>?</OfferTextEmpID>`			Note: For Long jobs this parameter is not used and EmpId is always returned within the offer response.
		`<DupUseEmpID>?</DupUseEmpID>`
		`<SpareIgnVanStock>?</SpareIgnVanStock>`
		`<OfferTextCost>?</OfferTextCost>`
		`<NonConsecShift>?</NonConsecShift>`
		`<ConsecShift>?</ConsecShift>`
		`<ContigShift>?</ContigShift>`
		`<useExtraDuration>?</useExtraDuration>`			If `useExtraDuration` is set to true, but there is no `extraDuration` supplied, then the `SP_OPTION_COMBINATION_INVALID (159)` will be returned.
		<UseFRUFilter>?</UseFRUFilter>			RESERVED. For internal use only.

	`<forceOptions>`				See the Force Options section for the definitions of the permitted `forceOptions` listed below. With the exception of `IgnoreOverlap`, `forceOptions` are not available for use in conjunction with long duration 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>`
		`<SpareForceGo>?</SpareForceGo>`
		`<Reassign>?</Reassign>`
		`<IgnoreCapacity>?</IgnoreCapacity>`
		`<NoTravel>?</NoTravel>`
		`<NoLocalKnowledge>?</NoLocalKnowledge>`
		`<IgnoreOverlap>?</IgnoreOverlap>`
	`</forceOptions>`
	`<reqSpares>`
					See Spares Information for details of the `<reqSpares>` structure.
	`</reqSpares>`
	`<deliverySize>?</deliverySize>`			`int`	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.
	`<pickupSize>?</pickupSize>`			`int`	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`	A Site Identifier. ServiceOptimizer will attempt to schedule jobs with the same `siteID`s: (a) consecutively, so that there is 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`	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`	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 the `sp:ApptOfferRequest` API so that only those offers where none of these constraints would be broken are returned. This parameter, if used, contains the name of the Capacity Category to which this Job belongs; if this parameter is not supplied then (in a system in which Capacity management is being used) the Capacity Category specified on the Job's Job Type is used.
`</sp:ApptOfferRequest>`

On input, 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.

This will also be the case for returned values, except where the sp083_system_ parameter value use_iso8601 is set to YES, in which case the returned dates and times will be in ISO 8601 format, which is the local time with UTC offset in one string. For example a time returned for the 16th of October 2014, 11pm EST would be 2014-10-16T23:00:00-05:00.

Return Structure

The API returns a non-standard return structure.

Either an offers structure, or a splitOffers structure will be returned, depending on the type and duration of the job for which offers are being requested. The structures are, in the main, very similar, the fields are described in more detail below.

"Offers" Response

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:ApptOfferResponse>`
	`<returnCode>?</returnCode>`				This contains the standard return structure.
	`<offers>`
		`<offer>`
			`<start>?</start>`	`spDateTime`	The start date and time of the offer, which will fall within the inclusive date and time range between which appointments were requested using the `start` and `end` parameters of the call to `sp:ApptOfferRequest`. For jobs of long duration, that are split across multiple shifts, all of the split parts of the offer will fall within the inclusive date and time range between which appointments were requested.
			`<end>?</end>`	`spDateTime`	The end date and time of the offer, which will fall within the inclusive date and time range between which appointments were requested using the `start` and `end` parameters of the call to `sp:ApptOfferRequest`. For jobs of long duration, that are split across multiple shifts, all of the split parts of the offer will fall within the inclusive date and time range between which appointments were requested.
			`<promBand>?</promBand>`	`TimeBandID`	The name of the promise band of the appointments, e.g. `M` could be the name of the promise band between 8:30 and 12:30.
			`<promType>?</promType>`	`PromTypeID`	The type of the promise band, e.g. `H` could be the type (half-day) of the promise band between 8:30 and 12:30.
			`<day>?</day>`	`DayOfTheWeek`	Indicates which day of the week the appointment falls on: “Mon”, “Tue”, “Wed”, “Thu”, “Fri”, “Sat”, “Sun”.
			`<offerToken>?</offerToken>`	`OfferToken`	A data item returned by ServiceOptimizer to identify each appointment in a way which is opaque to the caller. It should not be altered, but returned when Book Appointment SOAP API is called.
			`<offerText>?</offerText>`	`OfferText`	Previous items returned in this field are now returned in specific fields within the response - DRU, FRU, IRU, empID and siteIndicator and these fields must be used to retrieve data. Note. `Cost` is still returned within this field.
			`<travelTime>?</travelTime>`	`int`	The difference in travel time between having the offer in the schedule and not having it, measured between the previous location and the next location. If the offer is positioned in an otherwise empty operative day, `travelTime` is the time to travel to the job only. Where a ‘forced’ offer is requested (i.e. `InTray` , `InTrayWithSkills` or `OptNoTravel` is set), `travelTime` is `SP_IntNoValue`. The `travelTime` for an all-day job is the same as for a non-all-day job, i.e. not zero.
			`<DRU>?</DRU>`	`RUID`	The ID of the DRU that contains the FRU (below) from which this offer is being made. If that FRU isn’t in a DRU, this field is empty.
			`<FRU>?</FRU>`	`RUID`	The ID of the FRU from which this offer is being made.
			`<IRU>?</IRU>`	`RUID`	The IRU containing the offer, determined as follows: If the offer is for a resourced job, 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 the offer is for an unresourced (forced) job, 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.
			`<empID>?</empID>`	`EmpID`	If `offerTextEmpID` is set, is the `EmpID` of the operative that this offer is provisionally assigned to. Note: For Long jobs, EmpId is always returned.
			`<siteIndicator>?</siteIndicator>`	`char`	If this offer is adjacent to an existing job on the same operative day with the same `siteID` or `groupID`, then `siteIndicator` will be `S` (SameSite) or `C` (SameCustomer), respectively.
		`</offer>`
		`<more>?</more>`		`boolean`	Indicates that more appointments matching the supplied criteria are available (for example, by adding to `index` and calling `sp:ApptOfferRequest` again). This is only when the `offers` structure is not contained within a `splitOffers` structure. For `splitOffers`, only the one offer group for each available operative is returned with any one call.
	`</offers>`
`</sp:ApptOfferResponse>`

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.

The amount of time spent searching for available capacity can be limited by setting a value for the database parameter ABS_search_timeout. If offers have been found within this time then SP_OK_ABS_SEARCH_TIMEOUT (369) is returned; if none have been found then SP_NTA_ABS_SEARCH_TIMEOUT (370) is returned instead. ABS_search_timeout won’t be used if Reassign is to be tried, since the time allowed for re-assign is limited by the timeout ABS_reassign_timeout.

"Split Offers" Response

Click here to expand...

Web Service					Type	Description	Req?	Val?
`<sp:ApptOfferResponse>`
	`<returnCode>?</returnCode>`					This contains the standard return structure.
	`<splitOffers>`
		`<group>`
			`<groupNumber>?</groupNumber>`		`int`	Allow the multiple offers for each long job to be grouped together – offers in the same group have the same `groupNumber`, which are ascending integer values starting at 1.
			`<groupDuration>?</groupDuration>`		`int`	The total duration of the combined split parts (in minutes).
			`<groupType>?</groupType>`		`SplitGrpType`	One of `ContigShift`, `ConsecShift`, or `NonConsecShift`. Returned with the first offer in each offer group to provide an indication of what type of offer group this is (it is undefined in the other offers in the same offer group): `ContigShift` means that the offers in this group are on contiguous shifts for the relevant operative. That is, every shift that the operative will visit the site is on consecutive days; `ConsecShift` means that the offers in this group are on consecutive shifts for the relevant operative. That is, every shift that the operative will visit the site is on consecutive days except for off-shift time and weekends/public holidays; `NonConsecShift` means that the offers in this group aren’t in contiguous or consecutive shifts, but will still be no more than `Long Job: Max Fragment Gap` days apart.
			`<offer>`			Fields are as in the `offer` section of the "Offers" Response above plus:
				`<duration>?</duration>`	`int`	The duration of the individual fragment of the split job (in minutes).
			`</offer>`
		`</group>`
	`</splitOffers>`
`</sp:ApptOfferResponse>`

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.

The amount of time spent searching for available capacity can be limited by setting a value for the database parameter ABS_search_timeout. If offers have been found within this time then SP_OK_ABS_SEARCH_TIMEOUT (369) is returned; if none have been found then SP_NTA_ABS_SEARCH_TIMEOUT (370) is returned instead.

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_JOBTYPE_INVALID (2)
SP_POSTCODE_INVALID (3)
SP_EMPID_INVALID (5)
SP_NO_TIME_AVAILABLE (8)
SP_DURATION_INVALID (12)
SP_DAY_INVALID (15)
SP_BAND_INVALID (16)
SP_INDEX_INVALID (17)
SP_COUNT_INVALID (18)
SP_END_NOT_GE_START_DATE (19)
SP_ABS_LOGGED_ERROR (20)
SP_EMP_UNAVAILABLE (21)
SP_SKILL_INVALID (27)
SP_UNIT_INVALID (28)
SP_PROM_SET_INVALID (30)
SP_END_NOT_GT_START_TIME (31)
SP_SKILLLEVEL_INVALID (32)
SP_CANNOT_FORCE_SKILL (33)
SP_JOBTYPE_NOT_IN_DATE (49)
SP_PROMTYPE_INVALID (50)
SP_JOBTYPE_CANNOT_BE_FORCED (51)
SP_OUTSIDE_HORIZON (53)
SP_EXTRA_DURATION_INVALID (54)
SP_START_DATE_INVALID (55)
SP_END_DATE_INVALID (56)
SP_PREFERRED_DATE_INVALID (57)
SP_DAY_START_TIME_INVALID (58)
SP_DAY_END_TIME_INVALID (59)
SP_START_TIME_INVALID (62)
SP_END_TIME_INVALID (63)
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_EMPSMAX_EXCEEDED (88)
SP_EMPID_DUPLICATED (89)
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_PREFERRED_DATE_OUTSIDE_HORIZON (339)
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_DRU_NO_FRUS (625)
SP_NUMREQ_NO_DEFAULT (644)
SP_PROMSET_MULTIPLE_BAND_TYPES (645)
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)

Browser not supported