/
Integration ServiceOptimizer Operative Override SOAP API
Document toolboxDocument toolbox

Integration ServiceOptimizer Operative Override SOAP API

Owned by Andrew Hill (Deactivated)
Last updated: Nov 02, 2017Version comment

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.

(tick)

(tick)

 

<date>?</date>

 

Date the override is to be applied on.

(tick)

 

 

<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.

 

 

 

 

<startDate>?</startDate>

 

 

 

 

 

 

<startTime>?</startTime>

 

 

 

 

 

 

<endDate>?</endDate>

 

 

 

 

 

 

<endTime>?</endTime>

 

 

 

 

 

 

<isCapacityShift>?</isCapacityShift>

 

Is this shift taken account of for capacity settings?

If it is not supplied, and there is no existing shift on the override date, it will default to true.  If it is not supplied, and 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?

 

 

 

 

<breaks>

 

Details of any breaks that should be applied to the override.

A maximum of SP_BreakSeq_Max (5) can be defined. All of the parameters in the <reqBreaks> section are mandatory for each <reqBreaks> section supplied.

The duration of the breaks must be between SP_BreakDurationMin (0) and SP_BreakDurationMax (999).

A BreakDuration of 0 has the effect of removing a break, however BreakEarliest and BreakLatest must still be provided, and must still lie within the shift time.

If the same BreakName as original shift breaks, or previously added overrides, is used then they are taken as replacing these breaks. If they are unique then are considered to be additional breaks to be taken.

If no <reqBreaks> are supplied then it has the effect of removing any overrides and returning to the original shift breaks.

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 zero.

Breaks must be passed in chronological sequence.

 

 

   <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

 

 

(tick)

 

</startLoc>

 

 

 

 

 

<endLoc>

 

 

 

 

 

 

<locType>?</locType>

 

 

 

 

 

 

<postcode>?</postcode>

Postcode

 

 

(tick)

 

</endLoc>

 

 

 

 

 

<LKCLoc>

 

 

 

 

 

 

<locType>?</locType>

 

 

 

 

 

 

<postcode>?</postcode>

Postcode

 

 

(tick)

 

</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_EMPID_INVALID (5)
  • 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_STARTLOC_INVALID (304)
  • SP_STARTLOCPOSTCODE_INVALID (305)
  • SP_ENDLOC_INVALID (306)
  • SP_ENDLOCPOSTCODE_INVALID (307)
  • 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_LKCLOC_INVALID (347)
  • SP_LKCLOCPOSTCODE_DOES_NOT_EXIST (348)
  • SP_LKCLOCPOSTCODE_NOT_SUPPLIED (349)
  • SP_LKCLOCPOSTCODE_INVALID (350)
  • 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_ISADJSHIFT_INVALID (355)
  • SP_ISCAPSHIFT_INVALID (356)
  • 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_BREAKNAME_INVALID (655)
  • SP_BREAK_WINDOW_MAX_EXCEEDED (658)