14.1 Force/Fix Job Operative SOAP API
- Billy Sewell (Unlicensed)
- Jason Andrew
The sp:DVForceFixJobRequest API method can be used to "fix" a job to a date, time and employee.
Description
It is sometimes necessary to update the schedule with a promise to service a job at a particular date and time, irrespective of the impact on the rest of the schedule. Generally this would be managed via the Gantt - however in some circumstances a programming interface is required. The sp:DVForceFixJobRequest API method allows a specified existing job to be fixed to a date, time and employee.
The overall intention is to provide a function which achieves a similar result as would have been available through move/drag and drop (D&D) of a job on the Gantt, followed by setting the job to "fixed".
As with a Gantt move/D&D, the travel time and job duration will be recalculated based on the new position/employee for the job.
Unlike a Gantt move/D&D, the job may be moved no matter what its current dispatch status (except where spares are involved or status is LoggedOff or Cleared, see below). No unearmark dispatch interface call will be made. It is assumed that the person moving the job is the employee themselves, or has spoken to the employee in order to decide that the job should be moved.
Earmarking for the job in its new position will follow the usual rules.
Jobs may be moved to any date, including a date in the past - but only if this date is within the system horizon.
Having moved the job there may be conflicts/overlaps with other jobs and standard activities. An option is available, SP_OptForceFixAllowShuffle, to cause these conflicts to be addressed (as far as is possible). If the option is not set the conflicts may never be resolved.
As with general usage, once a job has been marked as fixed it will remain fixed unless express action is taken to change it.
In line with Gantt D&D rules (see [2]), the following constraints cannot be overridden:
- This API method applies to previously booked jobs only (whether allocated or in the in-tray) - if not true,
SP_JOBID_INVALID (1)is returned. - The employee must have a shift assignment for the full duration of the job - if not true,
SP_EMP_NO_SHIFT_ASS (271)is returned. - The job may only be allocated within the same FRU as it is currently booked (i.e. the employee must be posted to that FRU at the time required) - if not true,
SP_OUTSIDE_FRU_POSTING (264)is returned. - The interface will error if the job requires spares and is not at status SPDS_Tentative - the return value will be
SP_SPARES_AND_NOT_TENTATIVE (272). - Jobs that are already at status
LoggedOfforClearedwill generate a return value ofSP_JOB_GT_LOGGEDON (275).
Definition
The definition of this API is:
Web Service | Type | Description | Req? | Val? | ||
|
|
|
|
| ||
|
| The caller’s identifier of the job to be booked. The error |
|
| ||
|
| is the caller’s identifier of the employee who is to do the job. The function will error (returning SP_EMPID_INVALID (5)) if EmpID does not exist in the ServicePower database. |
|
| ||
|
| is the time at which the employee will start travelling to the job. The function will error if StartDateTime breaks any of the hard constraints required by JobID, unless appropriate ForceOptions are used. Various soft constraints may also cause error – again appropriate ForceOptions can overcome these. |
|
| ||
|
|
| is a set of options which specify which constraints normally applied when moving jobs should be ignored for this fn. These are optional parameters. |
|
| |
|
|
| All the overrides are applied |
|
| |
|
|
| (0x100000) |
|
| |
|
|
| If new position for the job overlaps existing jobs, this will be ignored. (0x4000) |
|
| |
|
|
| If new position for the job overlaps existing standard activities, this will be ignored. (0x8000) |
|
| |
|
|
| If the job has Mandatory/Preferred employees other than EmpID, or EmpID is one of the excluded employees, this will be ignored. (0x80) |
| ||
|
|
| If EmpID does not have any local knowledge for the region of the job, this will be ignored. (0x400) |
|
| |
|
|
| If new position for the job is outside its required contract hours (SLA only), this will be ignored. (0x10000) |
|
| |
|
|
| If EmpID does not have all the required skills, at the required level, for the job, this will be ignored. (0x800) |
|
| |
|
|
| If the job currently has status other than SPDS_Tentative, this will be ignored. (0x20000) |
| ||
|
|
| If the job requires spares that EmpID does not have, this will be ignored (0x40000) |
|
| |
|
|
| If the new job position would take EmpID over his defined maximum allowed over time, this will be ignored (0x80000) |
|
| |
|
|
| If new position for the job is outside the period Earliest time to Latest time (appoinments only), this will be ignored (0x200000) |
|
| |
|
|
| If new position for the job is outside the defined Service Hours,including the Grace Period (SLAonly), this will be ignored. (0x400000) |
|
| |
|
|
| If new start time (or end time if CallToFix) for the job is outside the defined open Access Hours, or within the defined closed Access Hours(SLA only), this will be ignored (0x800000) |
|
| |
|
|
| Any capacity constraints on the day in question will be ignored. (0x8) |
|
| |
|
|
| If EmpID is marked as unschedulable this will be ignored (0x100). |
|
| |
|
|
| If EmpID is not on shift at the time of the job this will be ignored. (0x200) |
|
| |
|
|
|
|
|
| |
|
|
|
|
| ||
The startDateTime is local to what is specified in the tz_CJS database parameter.
This can be set such that startDateTime is local to the timezone of the region where the job is located, local to the timezone of the responsibility unit which contains the job, local to the employee that the job is allocated to, or local to a specified or default timezone.
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: