Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 3 Next »

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)

On this page:

Related pages:

Resource URL Summary


Pass Through Call to ServiceScheduling's "DVForceFixJobRequest" API

PUT /up/v5/rest/scheduling/ForceFixJob

HTTP Headers

This API uses the standard ServiceBroker HTTP Headers.


API Specifics


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

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 

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?

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.

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

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"

SS Field Mapping: expectedStart

Yes

Optionsobject

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

These are optional parameters.

PropertyTypeDescription
AllowShuffleboolean

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

SS Field: options.AllowShuffle

IgnAllboolean

All the overrides are applied.

SS Field: options.IgnAll

IgnOverlapJobsboolean

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

SS Field: options.IgnOverlapJobs

IgnOverlapStdActsboolean

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

SS Field: options.IgnOverlapStdActs

IgnEmpReqsboolean

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

IgnLKboolean

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

SS Field: options.IgnLK

IgnContractboolean

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

SS Field: options.IgnContract

IgnSkillboolean

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

IgnStatusboolean

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

SS Field: options.IgnStatus

IgnSparesboolean

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

SS Field: options.IgnSpares

IgnMaxOvertimeboolean

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

SS Field: options.AllowSIgnMaxOvertimehuffle

IgnAppointmentboolean

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

IgnServiceHoursboolean

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

IgnAccessHoursboolean

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

IgnCapacityboolean

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

SS Field: options.IgnCapacity

IgnSchedboolean

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

SS Field: options.IgnSched

IgnShiftboolean

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

SS Field: options.IgnShift

No

HTTP Response

Success

On success, a JSON-formatted version of the ServiceScheduling "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 ServiceScheduling "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, 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)





  • No labels