_API ApptOfferRequest Response

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.
			`<costBreakDownInformation>`		The `costBreakDownInformation` structure is only included in the response when required by the use of the `displayCostBreakdown` parameter in the request.
					See Schedule Cost Breakdown for details of the `costBreakDownInformation` structure.
			`</costBreakDownInformation>`
		`</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.