On This Page:

Related Pages:

The sp:EmpOverrideRequest API method can be used to override an operative's shift and/or locations.

Description

The sp:EmpOverrideRequest API method allows an operative’s shift and/or locations (start, end, and local knowledge) to be overridden for a required date.

The existing shift (or existing shift override) of an operative (EmpID) is overriden on the supplied Date if ShiftPeriod is supplied (i.e. not NULL).

Similarly, the existing locations (or existing location overrides) of an operative is overridden on the supplied Date if EmpLocs is supplied (not NULL).

Without any options set, a shift override will not be generated (if supplied) for a Date when the operative would not normally be on shift (i.e. has a shift period in their assigned shift pattern or an existing shift override) or is on a public holiday (SP_NO_SHIFT or SP_HOLIDAY will be returned, respectively).

Jobs will be shuffled after the overrides have been applied. This may result in some jobs being shuffled outside their access hours.

If, as a result of an sp:EmpOverrideRequest API call, an operative is left with jobs in non-shift time, they won’t be de-allocated, but, unless they are fixed, or have a status > tentative, the Optimizer may de-allocate them when it next runs if it can not re-allocate them.

This SOAP API is implemented in real time, i.e. the overrides can be assumed to have taken effect on successful return from the call.

The underlying shift from a shift pattern, if there is one, can be restored by using the Shift and Location Restore SOAP API.

Definition

The definition of this API is:

Click here to expand...

Web Service					Type	Description	Req?	Val?
`<sp:EmpOverrideRequest>`
	`<empID>?</empID>`				`EmpID`	Employee the override is for.
	`<date>?</date>`					Date the override is to be applied on.
	`<shiftPeriod>`					The `startDate` and `endDate` associate a shift that spans a day boundary with the supplied `date`. If not supplied, they both default to `date`. Note that, because the shift override must overlap `date` by at least one hour (FS 190, 2.6(i)), `startDate` can only be the same as `date` or a day earlier. Similarly, `endDate` can only be the same as `date` or a day later. When creating an override, if `startDate`/`startTime` and/or `endDate`/`endTime` are not supplied, the override will be created using the start and/or end times from the original shift. When creating an override on a Public Holiday (provided that `OverridePubHols` is set), if `startDate`/`startTime` and/or `endDate`/`endTime` are not supplied, the override will be created using the start and/or end times from the shift that would be in place if there was no Public Holiday on that day. When updating an override, the original shift times are no longer considered. In this case, if `startDate`/`startTime` and/or `endDate`/`endTime` are not supplied then the start/end times in the override will remain unchanged.
		`<startDate>?</startDate>`
		`<startTime>?</startTime>`
		`<endDate>?</endDate>`
		`<endTime>?</endTime>`
		`<isCapacityShift>?</isCapacityShift>`				Is this shift taken account of for capacity settings? When creating or updating an override, if it is not supplied, it defaults to the setting from the original shift pattern. If there is no existing shift on the override date, it will default to true.
		`<isAllDayJobShift>?</isAllDayJobShift>`				Can all day jobs be booked onto the shift? When creating or updating an override, if it is not supplied, it defaults to the setting from the original shift pattern. If there is no existing shift on the override date, it will default to true.
		`<breaks>`				Details of any breaks that should be applied to the override. When creating an override: If no `reqBreaks` are supplied, then the override will be created with breaks at the same times and durations as the original shift breaks. If the same `BreakName`(s) are supplied for any of the original shift breaks, these will be takes as replacing those breaks. If unique `BreakName`(s) are supplied these will be considered to be additional breaks to be taken. If any break from the original shift is not included in the `reqBreaks` container at all, then the override will be created with the times and duration of that original shift break. If an original shift break is to be removed, and not replaced, the break should appear in the sequence of overrides with a `BreakDuration` of `-1`. As with shift start and end times above, if `date` is a Public Holiday, then the break times used as defaults will be those of the shift that would be in place if there was no Public Holiday. If the day for which the override is being created already contains one or more breaks that are `Fixed`, `Started` or `Finished` then the details for these breaks should not be included in the `reqBreaks`, the override will take the fixed time/duration for these breaks. Any request to override a break in `Fixed`, `Started` or `Finished` state will silently ignore that update (no error will be returned). When updating an override, the values from the original shift are no longer considered: If no `reqBreaks` are supplied, then the breaks created by the original override will be unchanged. If the same `BreakName`(s) are supplied for any of the breaks in the original override, these will be takes as replacing those breaks. If unique `BreakName`(s) are supplied these will be considered to be additional breaks to be taken. If an break is to be removed from the override, the break should appear in the sequence of overrides with a `BreakDuration` of `-1`. If the day for which the override is being updated already contains one or more breaks that are `Fixed`, `Started` or `Finished` then the details for these breaks should not be included in the `reqBreaks`, the override will take the fixed time/duration for these breaks. Any request to override a break in `Fixed`, `Started` or `Finished` state will silently ignore that update (no error will be returned). For both creation and update, the breaks may not overlap with each other- so for each break, the `BreakLatest` + `BreakDuration` must be less than the next `BreakEarliest`. All breaks must be contained within the shift; that is: `BreakEarliest` must be greater than or equal to `startTime`; and `BreakLatest` + `BreakDuration` must be less than or equal to `endTime`. The duration of the breaks must be between `0` and `999`. A `BreakDuration` of `-1` has the effect of removing a break, however `BreakEarliest` and `BreakLatest` must still be provided, but they will be ignored. It is not possible to create a new break with a `BreakDuration` of `-1`. A maximum of `SP_BreakSeq_Max` `(10)` can be defined in the structure, but the total number of breaks in the override period once breaks have been added and removed may not exceed 5. All of the parameters in the `<reqBreaks>` section are mandatory for each `<reqBreaks>` section supplied.
			`<reqBreaks>`
				`<BreakName>?</BreakName>`	`BreakName`
				`<BreakType>?</BreakType>`
				`<BreakEarliest>?</BreakEarliest>`
				`<BreakLatest>?</BreakLatest>`
				`<BreakDuration>?</BreakDuration>`
			`</reqBreaks>`
		`</breaks>`
	`</shiftPeriod>`
	`<startLoc>`					In a supplied `EmpLocs`, if `startLoc`, `endLoc` or `LKCLoc` aren’t to be overridden, `SP_IntNoValue` or `SP_IntNoUpdate` should be supplied. `StartLocPostcode` is ignored unless `startLoc` is `Supplied`; the same applies to `EndLocPostcode` and `endLoc`, and `LKCLocPostcode` and `LKCLoc`.
		`<locType>?</locType>`
		`<postcode>?</postcode>`			`Postcode`
	`</startLoc>`
	`<endLoc>`
		`<locType>?</locType>`
		`<postcode>?</postcode>`			`Postcode`
	`</endLoc>`
	`<LKCLoc>`
		`<locType>?</locType>`
		`<postcode>?</postcode>`			`Postcode`
	`</LKCLoc>`
	`<options>`
		`<OverridePubHols>?</OverridePubHols>`				An override will be generated (or an existing override replaced) for a `date` when an operative is on a Public Holiday only if `OverridePubHol` is set.
		`<OverrideNoShift>?</OverrideNoShift>`				If `OverrideNoShift` is set, a shift override can be added (or an existing override replaced) for a non-shift date, including a date when the operative has no shift pattern assignment.
	`</options>`
`</sp:EmpOverrideRequest>`

Return Structure

The API returns the standard return structure.

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_DATE_INVALID (14)
SP_OUTSIDE_HORIZON (53)
SP_START_DATE_INVALID (55)
SP_END_DATE_INVALID (56)
SP_START_TIME_INVALID (62)
SP_END_TIME_INVALID (63)
SP_OPTIONS_INVALID (80)
SP_EMP_NOT_IN_TEAM (124)
SP_EMPID_DOES_NOT_EXIST (231)
SP_FRU_UNAVAILABLE (259)
SP_STARTLOCPOSTCODE_DOES_NOT_EXIST (309)
SP_ENDLOCPOSTCODE_DOES_NOT_EXIST (310)
SP_STARTLOCPOSTCODE_NOT_SUPPLIED (314)
SP_ENDLOCPOSTCODE_NOT_SUPPLIED (315)
SP_BREAK_EARLIEST_INVALID (321)
SP_BREAK_LATEST_INVALID (322)
SP_BREAK_DURATION_INVALID (323)
SP_SO_NO_SHIFT (325)
SP_SO_HOLIDAY (326)
SP_SHIFTS_WOULD_OVERLAP (344)
SP_SHIFTS_TOO_CLOSE (345)
SP_LKCLOCPOSTCODE_DOES_NOT_EXIST (348)
SP_LKCLOCPOSTCODE_NOT_SUPPLIED (349)
SP_SO_SHIFT_END_NOT_AFTER_START (351)
SP_BREAK_EARLIEST_AFTER_LATEST (352)
SP_BREAK_EARLIEST_BEFORE_SHIFT_START (353)
SP_BREAK_LATEST_AFTER_SHIFT_END (354)
SP_OK_WITH_OVERLAPS (373)
SP_SHIFT_TOO_LONG (375)
SP_DST_TIME_INVALID (379)
SP_NO_OVERRIDES (548)
SP_SO_NWD_TOO_SHORT (551)
SP_SO_START_INVALID (553)
SP_SO_END_INVALID (554)
SP_SO_START_NO_TIME (555)
SP_SO_END_NO_TIME (556)
SP_SO_BREAK_OUTSIDE (557)
SP_SO_ADJ_IN_SHIFT (558)
SP_OK_CAPACITY_EXCEEDED (640)
SP_BREAKTYPE_INVALID (650)
SP_BREAKTYPE_NOT_OVERRIDDEN (651)
SP_BREAKSEQ_SIZE_INVALID (652)
SP_BREAKSEQ_DUPLICATE_BREAKNAMES (653)
SP_BREAKSEQ_OVERLAPS (654)
SP_BREAK_WINDOW_MAX_EXCEEDED (658)

Browser not supported