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`.	N
	`<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.	N	Y
	`<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`.	Y
	`<jobType>?</jobType>`			`JobTypeID`	The type of work to be performed.	Y	Y
	`<postcode>?</postcode>`			`Postcode`	The *full* postal code of the location of the job.	Y	Y
	`<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.	N	Y
	`<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.	N	Y
	`<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.	Y	Y
	`<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.	N
	`<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.	N
	`<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.	N	Y
		`<reqSkills>`				N
			`<skillID>?</skillID>`	`SkillID`		Y	Y
			`<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`.	Y
		`</reqSkills>`
	`</extraSkills>`
	`<ListReqEmps>`				Allows for a list of up to 10 `reqEmp`s to be specified, specifying any required MPX employee options.	N
		`<reqEmp>`				N
			`<empID>?</empID>`	`EmpID`	Defined a preferred, mandatory or excluded operative for the job.	Y	Y
			`<MPX>?</MPX>`			Y
		`</reqEmp>`
	`</ListReqEmps>`
	`<displayCostBreakdown>?</displayCostBreakdown>`			`boolean`	If `true` return the Schedule Cost Breakdown structure details as part of the response. If either the `forceOptions` `InTray` or `InTrayWithSkill` options are set to true, then the Schedule Cost Breakdown structure will not be returned in the response.	N
	`<stdExtraDuration>?</stdExtraDuration>`			`StdExtraDuration`	Specially defined extra time added to the normal amount for the job type. This time is specified in the DB.	N	Y
	`<reqUnit>`					N
		`<unitType>?</unitType>`		`UnitType`	If `Final`, specifies that the `RUID` field is an FRU ID, or, if `DRU`, specifies that `RUID` is a DRU ID.	Y	Y
		`<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`).	Y	Y
	`</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).	Y
	`<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.	N
		`<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`.	N
		`<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>`.	N
	`</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.	N
		`<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`).	N
		`<time>?</time>`		`Time`	If not supplied, ServiceOptimizer will use a default of `2400` on the end date.	N
	`</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.	N
	`<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.	N
		`<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.	Y	Y
		`<start>?</start>`		`Time`		N
		`<end>?</end>`		`Time`		N
	`</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.	N
	`<offerOptions>`				See the Offer/Book Options section for the definitions of the permitted `offerOptions` listed below.	N
		`<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.	N
		`<OfferTextEmpID>?</OfferTextEmpID>`			Note: For Long jobs this parameter is not used and `EmpId` is always returned within the offer response.	N
		`<DupUseEmpID>?</DupUseEmpID>`				N
		`<SpareIgnVanStock>?</SpareIgnVanStock>`				N
		`<OfferTextCost>?</OfferTextCost>`				N
		`<NonConsecShift>?</NonConsecShift>`				N
		`<ConsecShift>?</ConsecShift>`				N
		`<ContigShift>?</ContigShift>`				N
		`<useExtraDuration>?</useExtraDuration>`			If `useExtraDuration` is set to true, but there is no `extraDuration` supplied, then the `SP_OPTION_COMBINATION_INVALID (159)` will be returned.	N
		<UseFRUFilter>?</UseFRUFilter>			RESERVED. For internal use only.	N
	`</offerOptions>`
	`<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)`.	N
		`<InTray>?</InTray>`				N
		`<InTrayWithSkill>?</InTrayWithSkill>`				N
		`<SpareForceGo>?</SpareForceGo>`				N
		`<Reassign>?</Reassign>`				N
		`<IgnoreCapacity>?</IgnoreCapacity>`				N
		`<NoTravel>?</NoTravel>`				N
		`<NoLocalKnowledge>?</NoLocalKnowledge>`				N
		`<IgnoreOverlap>?</IgnoreOverlap>`				N
	`</forceOptions>`
	`<reqSpares>`					N
					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.	N
	`<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.	N
	`<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.	N	Y
	`<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.	N	N
	`<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.	N	Y
`</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.

Browser not supported