5.4.0

A pass-through API to Scheduling (when configured) which allows the Scheduling's ActUpdate API to be called.

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 LoggedOff or Cleared will generate a return value of SP_JOB_GT_LOGGEDON (275)

On this page:

Related pages:

Pass Through Call to Scheduling's "DVForceFixJobRequest" API

This RESTified API will perform a pass-through call to the Scheduling sub-system's "DVForceFixJobRequest" API (when configured).

URL

PUT /up/v5/rest/scheduling/ForceFixJob

HTTP Request Body

This request requires a JSON object supplied in the HTTP request body, which defines the parameters that will be passed through to the Scheduling "DVForceFixJobRequest" API.

ForceFixJob Object Format

ForceFixJob JSON

{
	"Id": "",
	"Tech": "",
	"SchdStart": "",
	"Options": {
		"AllowShuffle": false,
		"IgnAll": false,
		"IgnOverlapJobs": false,
		"IgnOverlapStdActs": false,
		"IgnEmpReqs": false,
		"IgnLK": false,
		"IgnContract": false,
		"IgnSkill": false,
		"IgnStatus": false,
		"IgnSpares": false,
		"IgnMaxOvertime": false,
		"IgnAppointment": false,
		"IgnServiceHours": false,
		"IgnAccessHours": false,
		"IgnCapacity": false,
		"IgnSched": false,
		"IgnShift": false
	}
}

ForceFixJob Object Properties (Bold property names indicate the field is required)

Property	Type	Length	Description	Req?	Field Mapping: Scheduling
Id	string SS: JobID	SS: 50	The caller’s identifier of the job to be booked. The error `SP_JOBID_INVALID (1)` will be returned if the supplied `JobID` does not exist in the ServicePower database.	Yes	jobID
Tech	string SS: EmpID	SS: 25	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.	Yes	empID
SchdStart	string SS: spDateTime (string)	SS: 16	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. Example: "2023-03-30T14:15"	Yes	expectedStart
Options	object		A set of options which specify which constraints normally applied when moving jobs should be ignored for this fn.	No	see ForceFixJob.Options.Objections

HTTP Response

Success

On success, a JSON-formatted version of the Scheduling "DVForceFixJobRequest" API response will be returned.

{
    "Success": true,
    "Code": 0,
    "Message": "OK",
    "Payload": {
        "result": {
            "type": "OK",
            "code": "0"
        }
    }
}

Error

On error, a JSON-formatted version of the Scheduling "DVForceFixJobRequest" API response will be returned.

{
    "Success": false,
    "Code": 9,
    "Payload": {
        "returnCode": {
            "type": "Error",
            "code": "SCH Error Code"
        }
    }
}

Return Codes

In addition to the Standard Return Codes, and the Scheduling API return codes, the possible Return Codes from this API are:

Click here to expand...

SP_OK (0)
SP_JOBID_INVALID (1)
SP_EMPID_INVALID (5)
SP_NO_TIME_AVAILABLE (8)
SP_DATE_INVALID (14)
SP_JOBTYPE_NOT_IN_DATE (49)
SP_JOBTYPE_CANNOT_BE_FORCED (51)
SP_OUTSIDE_HORIZON (53)
SP_EMP_NOT_SKILLED (75)
SP_STATUS_BACKWARDS (85)
SP_OVERLAPPED_JOBS (132)
SP_FORCEOPTIONS_INVALID (150)
SP_EMP_ZERO_LK (155)
SP_OVERLAPPED_STDACTS (160)
SP_OUTSIDE_FRU_POSTING (264)
SP_OUTSIDE_CONTRACT (266)
SP_EMP_NO_SPARES (267)
SP_EMP_MAXOVERTIME_EXCEEDED (268)
SP_CAPACITY_EXCEEDED (269)
SP_EMP_NOT_REQEMP (270)
SP_EMP_NO_SHIFT_ASS (271)
SP_SPARES_AND_NOT_TENTATIVE (272)
SP_EMP_NOT_SCHEDULABLE (273)
SP_EMP_NOT_ON_SHIFT (274)
SP_JOB_GT_LOGGEDON (275)
SP_OUTSIDE_APPOINTMENT (276)
SP_OUTSIDE_SERVICE_HOURS (404)
SP_OUTSIDE_ACCHOURS (423)
SP_AFTER_JEOPARDY_ETA (440)

ServiceBroker 5

ForceFixJob RESTified API

Analytics

Resource URL Summary

HTTP Headers

API Specifics