Status

colour	Green
title	5.4.0

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

borderColor	grey
bgColor	whitesmoke
borderStyle	solid

On this page:

Table of Contents

maxLevel	2

Related pages:

Resource URL Summary

Panel

borderColor	grey
bgColor	whitesmoke
borderStyle	solid

Pass Through Call to ServiceScheduling's "DVForceFixJobRequest" API

PUT /up/v5/rest/scheduling/ForceFixJob

Include Page

	_Default HTTP Headers
	_Default HTTP Headers

No

Panel

borderColor	#D3D3D3

Pass Through Call to ServiceScheduling's "DVForceFixJobRequest" API

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

URL

Panel

borderColor	grey
bgColor	whitesmoke
borderStyle	solid

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

ForceFixJob Object Format

Code Block

language	js
title	ForceFixJob JSON
collapse	true

{
	"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:
ServiceScheduling

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

does not exist in the ServicePower database.

Yes

SS Field:

jobID

Yes

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.

SS Field Mapping: empID

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

SS Field Mapping:

expectedStart

Yes

Property Type Description

AllowShuffle

boolean

Allow the scheduler to shuffle other items to fit this item in. (0x100000)

SS Field: options.AllowShuffle

IgnAll

boolean

All the overrides are applied.

SS Field: options.IgnAll

IgnOverlapJobs

boolean

If new position for the job overlaps existing jobs, this will be ignored. (0x4000)

SS Field: options.IgnOverlapJobs

IgnOverlapStdActs

boolean

If new position for the job overlaps existing standard activities, this will be ignored. (0x8000)

SS Field: options.IgnOverlapStdActs

IgnEmpReqs

boolean

If the job has Mandatory/Preferred employees other than EmpID, or EmpID is one of the excluded employees, this will be ignored. (0x80)

SS Field: options.IgnEmpReqs

IgnLK

boolean

If EmpID does not have any local knowledge for the region of the job, this will be ignored. (0x400)

SS Field: options.IgnLK

IgnContract

boolean

If a new position for the job is outside its required contract hours (SLA only), this will be ignored. (0x10000)

SS Field: options.IgnContract

IgnSkill

boolean

If EmpID does not have all the required skills, at the required level, for the job, this will be ignored. (0x800)

SS Field: options.IgnSkill

IgnStatus

boolean

If the job currently has status other than SPDS_Tentative, this will be ignored. (0x20000)

SS Field: options.IgnStatus

IgnSpares

boolean

If the job requires spares that EmpID does not have, this will be ignored (0x40000)

SS Field: options.IgnSpares

IgnMaxOvertime

boolean

If the new job position would take EmpID over his defined maximum allowed over time, this will be ignored (0x80000)

SS Field: options.AllowSIgnMaxOvertimehuffle

IgnAppointment

boolean

If a new position for the job is outside the period Earliest time to Latest time (appoinments only), this will be ignored (0x200000)

SS Field: options.AllowIgnAppointmentShuffle

IgnServiceHours

boolean

If new position for the job is outside the defined Service Hours,including the Grace Period (SLAonly), this will be ignored. (0x400000)

SS Field: options.IgnServiceHours

IgnAccessHours

boolean

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)

SS Field: options.IgnAccessHours

IgnCapacity

boolean

Any capacity constraints on the day in question will be ignored. (0x8)

SS Field: options.IgnCapacity

IgnSched

boolean

If EmpID is marked as unschedulable this will be ignored (0x100)

SS Field: options.IgnSched

IgnShift

boolean

If EmpID is not on shift at the time of the job this will be ignored. (0x200)

SS Field: options.IgnShift


Options						object		A set of options which specify which constraints normally applied when moving jobs should be ignored for this fn.

These are optional parameters.

No	see ForceFixJob.Options.Objections

HTTP Response

Success

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

Code Block

language	js

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

Error

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

Code Block

language	js

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

Return Codes

In addition to the Standard 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)

Version	Old Version 3	New Version 4
Changes made by	Jason Andrew	Jason Andrew
Saved on	Jul 26, 2023	Aug 07, 2023

Versions Compared

Key

Resource URL Summary

API Specifics

Pass Through Call to ServiceScheduling's "DVForceFixJobRequest" API

URL

HTTP Request Body

ForceFixJob Object Format

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

HTTP Response

Success

Return Codes

Content Comparison

Versions Compared

Key

Resource URL Summary

API Specifics

Pass Through Call to ServiceScheduling's "DVForceFixJobRequest" API

URL

HTTP Request Body

ForceFixJob Object Format

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

HTTP Response

Success

Return Codes