Versions Compared

Version Old Version 5 New Version Current
Changes made by

Jason Andrew

Jason Andrew

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Status
colourGreen
title5.4.0

A pass-through API  to ServiceScheduling Scheduling (when configured) which allows the ServiceSchedulingScheduling'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)


Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

On this page:

Table of Contents
maxLevel2

Related pages:


Resource URL Summary


Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

Pass Through Call to ServiceSchedulingScheduling's "DVForceFixJobRequest" API

PUT /up/v5/rest/scheduling/ForceFixJob

Include Page
_Default HTTP Headers
_Default HTTP Headers


API Specifics



Panel
borderColor#D3D3D3

Pass Through Call to

ServiceScheduling

Scheduling's "DVForceFixJobRequest" API

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

URL

Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

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 ServiceScheduling Scheduling "DVForceFixJobRequest" API.

ForceFixJob Object Format 

Code Block
languagejs
titleForceFixJob JSON
collapsetrue
{
	"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: 
ServiceSchedulingScheduling

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

Optionsobject

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 ServiceScheduling Scheduling "DVForceFixJobRequest" API response will be returned.

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

Error

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

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

Return Codes

In addition to to the Standard Return Codes, and the general ServiceScheduling Return Codes, the specfic ones for the Scheduling API return codes, the possible Return Codes from this API are:

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)