_API EmpUpdateRequest Definition

<sp:EmpUpdateRequest>

There are also a set of options of the form SP_Opt*Set that allow an existing sequence of attributes (e.g. operative skills or range local knowledge) to be replaced by the supplied sequence of attributes. If the supplied sequence is then empty (Size = 0), the effect is to just remove all of the corresponding attributes in the existing sequence.

#define SP_OptUpdateAllowAdd               0x1

#define SP_OptEmpPostingDeallocJobs        0x2

#define SP_OptEmpShiftAssDeallocJobs       0x4

#define SP_OptEmpShiftAssSet              0x10

#define SP_OptEmpPostingSet               0x20

#define SP_OptEmpSkillSet                 0x40

#define SP_OptEmpPubHolSetSet            0x800

#define SP_OptEmpRangeLKSet               0x80

#define SP_OptEmpRegionLKSet             0x100

#define SP_OptEmpPattRangeLKSet          0x200

#define SP_OptEmpPattRegionLKSet         0x400

#define SP_OptEmpPattSet                0x1000

<empID>?</empID>

EmpID

<empAttr>

If any of the operative’s attributes are not to be updated, then the relevant field in the supplied EmpAttr should be excluded. Each of the items will normally be updated only if they already exist for this employee. For this purpose, each item is identified by its primary key, i.e:

StartDate for Postings,

SkillID & StartDate for Skills,

StartDate for Shifts

 (Note: The primary key also includes the EmpID, but this is always supplied in another parameter)

If an item in one of the Postings, Skills or Shift Assignments supplied does not already exist (as identified by its primary key), the call will fail.  However, if the supplied Options field contains UpdateAllowAdd, then any supplied items that don’t already exist will be created and added to the relevant list. If UpdateAllowAdd isn’t set and one of the supplied items doesn’t exist, then SP_POSTING_DOES_NOT_EXIST (235), SP_SKILLASS_DOES_NOT_EXIST (237) or SP_SHIFTASS_DOES_NOT_EXIST (236) will be returned, as appropriate.

<type>?</type>

SPET_Employee

<name>?</name>

<surname>?</surname>

<jobTitle>?</jobTitle>

<efficiency>?</efficiency>

between (inclusive) 10 and 999.  Normal value is 100

<maxOvertime>?</maxOvertime>

between (inclusive) 0 and 999

<noEmpInformLeadTime>?</noEmpInformLeadTime>

<informLeadTime>?</informLeadTime>

Normally the range of allowed values for InformLeadTime is held in the ServiceOptimizer database (i.e. between (inclusive) sp083.min_value and sp083.max_value where name = “TIL”). If either of these is not in the database, then the supplied value of InformLeadTime must be between 0 and 9999 respectively.

<noEmpEarmarkedJobsMax>?</noEmpEarmarkedJobsMax>

<earmarkedJobsMax>?</earmarkedJobsMax>

must be between (inclusive) 1 and 99

<homePostcode>?</homePostcode>

Postcode

<workPostcode>?</workPostcode>

Postcode

<TZType>?</TZType>

EmpTZType

<workTZ>?</workTZ>

WorkTZ is a TimeZone of the form ‘Mountain’, ‘Eastern’ ‘Greenwich’. The chosen value must exist in the ServiceOptimizer database.

<available>?</available>

Should the employee be schedulable

<defaultStartLoc>

<locType>?</locType>

<postcode>?</postcode>

Postcode

</defaultStartLoc>

<defaultEndLoc>

<locType>?</locType>

<postcode>?</postcode>

Postcode

</defaultEndLoc>

<defaultLKCLoc>

<locType>?</locType>

<postcode>?</postcode>

Postcode

</defaultLKCLoc>

<address1>?</address1>

<address2>?</address2>

<address3>?</address3>

<address4>?</address4>

<phone1>?</phone1>

<phone2>?</phone2>

<pager>?</pager>

<handHeldAdd1>?</handHeldAdd1>

<handHeldAdd2>?</handHeldAdd2>

<currentHandHeld>?</currentHandHeld>

<printer>?</printer>

<vehicleCapacity>?</vehicleCapacity>

<noEmpTOTB>?</noEmpTOTB>

<TOTB>?</TOTB>

must be between (inclusive) 0 and 1440

<noEmpTOTA>?</noEmpTOTA>

<TOTA>?</TOTA>

must be between (inclusive) 0 and 1440

<showOperativeStatus>?</showOperativeStatus>

<showTravelStatus>?</showTravelStatus>

<noEmpFreezeTheDay>?</noEmpFreezeTheDay>

<freezeTheDayLeadTime>?</freezeTheDayLeadTime>

both FreezeTheDayLeadTime and FreezeTheDayTimeOfDay should be supplied or both should not be supplied.  If only one is supplied, either SP_FDLT_NOT_SUPPLIED (586) or SP_FDT_NOT_SUPPLIED (587) will be returned.  In a call of EmpUpdateRequest, both can be supplied or neither can be supplied. Also, only one of them can be supplied as long as the other is already set for this operative.

<freezeTheDayTimeOfDay>?</freezeTheDayTimeOfDay>

SP_TIME_INVALID (29) (29) will be returned if the supplied FreezeTheDayTimeOfDay isn’t between 0000 and 2400.

<customKWVs>

The two Keywords that can be supplied in CustomKWVs are HourlyRate and OvertimeRate

<keyword>?</keyword>

<value>?</value>

</customKWVs>

</empAttr>

<postings>

If any of the supplied postings overlap each other, the call will fail and return SP_POSTINGS_OVERLAP (241).

The call will also fail (SP_POSTING_STDACT_OVERLAP (246)) if any of the supplied postings overlap an existing standard activity.

The call will fail (SP_POSTING_WOULD_DEALLOC (247)) if any of the supplied postings would cause the operative to change FRUs at a time when he has one or more jobs assigned to him (unless those jobs’ status is LoggedOff or Cleared, in which case SP_POSTING_WOULD_ORPHAN (648) will be returned). If the supplied Options field contains PostingDeallocJobs, then any such jobs will be deallocated (unless their status is LoggedOff or Cleared, in which case again SP_POSTING_WOULD_ORPHAN (648) will be returned) into the in-tray of their containing FRU and the call will succeed.

If the operative is to be posted to a team that has been created or assigned to a different IRU since ServiceOptimizer was started, then the call will fail and return SP_TEAM_CHANGE_REQUIRES_RESTART (647). This may also be returned if (one of) the teams to which the operative is currently posted has changed in this way.

If a supplied posting causes an operative to move from one FRU to another, then any of the operative’s existing standard activities that take place during the new posting should move to the new FRU with the operative.  If the new FRU is in a different time zone, the local start and end times will be preserved where possible, e.g. a standard activity between 08:00 and 10:00 in the old FRU will usually remain between 08:00 and 10:00 in the new FRU, even if it’s in a different time zone or moves between DST and non-DST.  If the activity crosses the DST to non-DST boundary, adjustments of one hour may be made to the start or end times in the new FRU to ensure that the end time is always after the start.  And where the time is ambiguous because it’s in the hour that occurs twice in the DST to non-DST changeover, the earlier time is used.  Therefore, where a posting to a FRU in a different time zone moves a standard activity, the user is advised to check its new position in the schedule.

Additionally, if a posting change causes an operative to move from one FRU to another and this would cause an existing special period to span postings then SP_POSTING_CONFLICTS_SPECIAL_PERIOD (688)will be returned.

For example:

To keep existing postings
Postings is NOT supplied

To update existing postings (Supplied postings must exist)
Postings is supplied
Options: PostingSet is NOT set
Options: AllowAdd is NOT set

To update existing postings (Supplied postings may include new postings)
Postings is supplied
Options: PostingSet is NOT set
Options: AllowAdd is set

To replace/remove existing postings
Postings is supplied
Options: PostingSet is set

Note: When Options: PostingSet is set, Options: AllowAdd is ignored.

<teamID>?</teamID>

<startDate>?</startDate>

<endDate>?</endDate>

If the end of a posting isn’t specified, then it’s assumed that the operative is posted to that team ‘for ever’.

</postings>

<skills>

The call will fail (SP_SKILLS_OVERLAP (243)) if any of the supplied skill assignments for the same skill overlap in time with each other.

If an operative’s skills are updated, this might mean that that operative no longer has the skills needed to do one or more of the jobs currently assigned to him. At present, this is not reported and the update call succeeds anyway. In future releases, the update may be rejected unless an override flag is set.

The Option SP_OptEmpSkillSet allows the operative’s existing skills to be entirely replaced by the supplied sequence Skills.  If Skills is empty (that is Skills is not NULL, but Skills.Size is 0) then all of the existing skills are removed.   All fields in Skills must be supplied, i.e. SP_IntNoUpdate and SP_StrNoUpdate are not allowed. When SP_OptEmpSkillSet is set, SP_OptUpdateAllowAdd is ignored.

<skillWithLevel>

<skillID>?</skillID>

SkillID

<skillLevel>?</skillLevel>

Each skill has a level associated with it that represents the level of that skill that the operative possesses. The scheduling process makes sure that that an operative is not assigned a job for which he doesn’t have all of the required skills at the required level or above.

</skillWithLevel>

<startDate>?</startDate>

<endDate>?</endDate>

If the end isn’t specified, then the operative has the skill ‘for ever’.

</skills>

<shifts>

If any of supplied shift assignments overlap, the call will fail and return SP_SHIFTASS_OVERLAP (242).  If any of the supplied or resulting shifts would overlap, SP_SHIFTS_WOULD_OVERLAP (344) is returned.  If any of the supplied or resulting shifts are closer than glob_min_shift_gap, then SP_SHIFTS_TOO_CLOSE (345) will be returned unless SP_OptEmpAllowShiftsTooClose is set.

At present, no update to a job’s attributes is done as a result of changes to the shift assignments of the operative assigned to the job. This might mean that a job ends up on a non-working day or is to be done in overtime, and the amount of overtime and the travel time recorded in memory and in the database might therefore be incorrect. In a future release, the update may be rejected unless an override flag is set.

The call will fail (SP_SHIFTASS_WOULD_DEALLOC (248)) if any changes to the operative’s shifts as a result of applying the supplied shift assignments would mean that the operative would then have jobs allocated to him which were not wholly within a shift assignment time (unless those jobs’ status is SPDS_LoggedOff or SPDS_Cleared, in which case SP_SHIFTASS_WOULD_ORPHAN (649) will be returned). (Note that this doesn’t apply to uncleared jobs that fall outside a shift period but otherwise remain within a shift assignment). If the supplied Options field contains SP_OptEmpShiftAssDeallocJobs, then any such jobs will be deallocated into the in-tray (unless those jobs’ status is SPDS_LoggedOff or SPDS_Cleared, in which case, again SP_SHIFTASS_WOULD_ORPHAN (649) will be returned). In a future release, it may be (optionally) possible to deallocate jobs which are outside a shift period, not just those outside a shift assignment.

The Option SP_OptEmpShiftAssSet allows the operative’s existing shift assignments to be entirely replaced by the supplied sequence Shifts.  If Shifts is empty (that is Shifts is not NULL, but Shifts.Size is zero) then all the existing shift assignments are removed.   All fields in Shifts must be supplied, i.e. SP_IntNoUpdate and SP_StrNoUpdate are not allowed. When SP_OptEmpShiftAssSet is set, SP_OptUpdateAllowAdd is ignored.

<shiftPatternID>?</shiftPatternID>

<startDate>?</startDate>

A shift pattern assignment is a period of days (between startDate and endDate) when an operative is ‘working’ a particular shift pattern.

<endDate>?</endDate>

If endDate isn’t specified, then it’s assumed that the operative will work that shift pattern ‘for ever’.

</shifts>

<defaultRangeLKs>

<travelTime>?</travelTime>

TravelTime must be less than SP_TravelTimeInMinsMax(255)

<LKValue>?</LKValue>

All supplied values of LKValue must be between SP_LocalKnowledgeMin(0)  & SP_LocalKnowledgeMax(10). 

</defaultRangeLKs>

<defaultRegionLKs>

<regionID>?</regionID>

<LKValue>?</LKValue>

the LKValue must be between SP_LocalKnowledgeMin(0) & SP_LocalKnowledgeMax(10)

</defaultRegionLKs>

<pubHols>?</pubHols>

<workPatt>

This allowsLocalKnowledgeRanges, Local Knowledge Regions, Local Knowledge Centres, Start Locations and End Locations to be supplied as part of a multi-week repeating work pattern. 

<syncDate>?</syncDate>

The syncDate parameter is a date on which the corresponding day of the week of the first week of a multi-week Working Pattern should coincide (not the date on which the Working Pattern starts).  For example if the Working Pattern is for 4 weeks starting on a Monday, and the SyncDate is 16^th March 2005 ( a Wednesday), the first Wednesday of the Working Pattern should be on 16^th march 2005.  The second Wednesday will therefore be on 23^rd March 2005.  The previous Sunday (13^th March 2005) will be for the fourth Sunday in the four week Working Pattern since it starts on a Monday.

<workPattDay>

<weekNum>?</weekNum>

<day>?</day>

DayOfTheWeek

<rangeLKoption>?</rangeLKoption>

Where rangeLK is being specified this option must be omitted.

To set this operative to have no range local knowledge on this workPattDay (maybe he only has region local knowledge), supply a rangeLKoption element with the value noRangeLK (instead of any rangeLK elements).

To set this operative to have his default range local knowledge on this day (i.e what’s supplied in defaultRangeLKs in both EmpCreateRequest and EmpUpdateRequest), supply a rangeLKoption element with the value empDefaultRangeLK (instead of any rangeLK elements).

<rangeLK>

<travelTime>?</travelTime>

<LKValue>?</LKValue>

</rangeLK>

<regionLKoption>?</regionLKoption>

Where regionLK is being specified this option must be omitted.

 To set this operative to have no region local knowledge on this workPattDay (maybe he only has range local knowledge), supply a regionLKoption element with the value noRegionLK (instead of any regionLK elements).

To set this operative to have his default region local knowledge on this day (i.e what’s supplied in defaultRegionLKs in both EmpCreateRequest and EmpUpdateRequest), supply a regionLKoption element with the value empDefaultRegionLK (instead of any regionLK elements).

<regionLK>

<regionID>?</regionID>

<LKValue>?</LKValue>

</regionLK>

<startLoc>

<locType>?</locType>

<postcode>?</postcode>

Postcode

</startLoc>

<endLoc>

<locType>?</locType>

<postcode>?</postcode>

Postcode

</endLoc>

<LKCLoc>

<locType>?</locType>

<postcode>?</postcode>

Postcode

</LKCLoc>

</workPattDay>

</workPatt>

<options>

There are some Options for EmpUpdateRequest that are mandatory if the corresponding data is supplied (see below).

If any of these required Options isn’t set, SP_REQ_OPTION_NOT_SET (471)  is returned.  This restriction may be removed in a future release.

There are no options available to allow jobs that should be de-allocated because of changes to local knowledge (both range and region) or public holiday assignments. Affected jobs will be left where they are in the schedule in the expectation that the Optimizer will subsequently attempt to move them or they will remain in jeopardy until the user moves them manually.

<AllowAdd>?</AllowAdd>

<PostingDeallocJobs>?</PostingDeallocJobs>

<ShiftAssDeallocJobs>?</ShiftAssDeallocJobs>

<AllowShiftsTooClose>?</AllowShiftsTooClose>

AllowShiftsTooClose overrides the limit on how close shift patterns are allowed to be

<PostingSet>?</PostingSet>

<SkillSet>?</SkillSet>

<ShiftAssSet>?</ShiftAssSet>

<RangeLKSet>?</RangeLKSet>

Is mandatory if DefaultRangeLKs is set

(M)

<RegionLKSet>?</RegionLKSet>

Is mandatory if DefaultRegionLKs is set

(M)

<PubHolSet>?</PubHolSet>

Is mandatory if PubHols is set

(M)

<PattSet>?</PattSet>

is mandatory if  workPatt. is set

 (M)

<PattRangeLKSet>?</PattRangeLKSet>

Is mandatory if any EmpWorkPatt. WorkPattDays[].RangeLKs is set

(M)

<PattRegionLKSet>?</PattRegionLKSet>

Is mandatory if any EmpWorkPatt.WorkPattDays[].RegionLKs is set

(M)

</options>

<externalData>

See 15.6

<name>?</name>

<SPESDTType>?</ SPESDTType >

<value>?</value>

</externalData>

</sp:EmpUpdateRequest>