On This Page:

Related Pages:

The sp:ChangeWorkItemStatusRequest API method can be used to change the dispatch status of a work item (a job or standard activity).

Description

When changing the dispatch status for a job or standard activity (work item), if fru_fj_auto_on is set in the ServiceOptimizer database, a search will be made to find a job that could be done after this work item if the operative has a suitable gap in their schedule.

If the search is successful, the found job will be allocated to start either {now} or immediately after this work item, whichever is later.

There are a number of other database values, all beginning with “fru_fj_auto_” that control how this option works.

Definition

The definition of this API is:

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:ChangeWorkItemStatusRequest>`
	`<workItemStatusChange>`				Single item defining the work item to be changed.
		`<workItemID>?</workItemID>`		`WorkItemID`	The identifier of the job or standard activity whose status is to be changed.
		`<workItemType>?</workItemType>`		`WorkItemType`	Identifies whether this is an update to a job or standard activity.
		`<newStatus>?</newStatus>`		`DisStatus`	The value to which the status of this work item is to be set. `SP_INVALID_STATUS (45)` will be returned if the `WorkItem` is a standard activity that cannot be dispatched.
		`<dateTime>?</dateTime>`		`spDateTime`	The date and time at which this status change is to be recorded as having happened. The default value is the current system date and time.
		`<spareStock>`			An optional list of spares (one per spare type) used by the `WorkItem`. If the `SpareIgnVanStock` flag is set on the job, all spares passed are ignored. Spares used by the work item may only be supplied if the job status being changed to `Cleared` or `LoggedOff`. The error code `SP_INVALID_PARAM (35)` will be returned if spares are passed for other status changes. A maximum of 30 spare types are permitted. If a spare is required by the job but is not provided in this list, then it will be assumed that zero of the required spares were used. The employee who is assumed to have provided all the spares is the one to whom the `WorkItem` was allocated.
			`<spareID>?</spareID>`	`SpareID`	The identifier for the spare used by the `WorkItem`. Error `SP_SPAREID_INVALID (111)` will be returned if it is not a known spare. Error `SP_SPAREID_DUPLICATED (578)` will be returned if a `spareID` is passed more than once. If a spare is passed that was not booked for the job then error `SP_JOB_SPARE_NOT_BOOKED (804)` will be returned.
			`<quantity>?</quantity>`	`int`	The number of spares used by the job. The maximum quantity of a spare type permitted to be used by a job is 99. Error `SP_QUANTITY_INVALID (112)` will be returned if `quantity` is greater than 99. If a greater quantity of a spare type is used on the job than was booked, the source will remain the same - even if more were used than were specified as being stored in the Van. It is assumed they were acquired somehow and were in the van. All spares are assumed to have been acquired somehow and in the van so the source will always become Van Stock even if they were initially External Stock - unless the `SpareIgnVanStock` flag is set on the job, in which case all spares remain marked as External.
		`</spareStock>`
	`</workItemStatusChange>`
`</sp:ChangeWorkItemStatusRequest>`

Work item dispatch status values are not allowed to go ‘backwards’ (e.g. changing from LoggedOff back to LoggedOn is not allowed).
This API call operates only on jobs and standard activities that start within the memory horizon.

TimeZones

The value of the dateTime timestamp time zone is controlled by what is specified in the tz_CJS database parameter.
This can be set such that: dateTime is:

local to the time zone of the region where the job is located or
local to the time zone of the responsibility unit which contains the job or
local to the employee to whom the job is allocated or
in a specified or default time zone or
in GMT with or without daylight saving (BST).

A call to this API with NewStatus set to Earmarked will dispatch an Earmarked message if CJS: Dispatch Earmarked Jobs is set.
There are circumstances where this call will cause the work item spDateTime duration to span the time when a break may be taken by the operative, so the time recorded may be different from the time expected.

Status Change Effects on Job Times

Adjustments to a work item’s Start time, Arrival time and Finish time depend on both the current dispatch status and the new status passed to ChangeWorkItemStatusRequest:

Definitions

For the work item:

the Start time is when the dispatch status becomes Travelling,
the Arrival time is when its status becomes LoggedOn and
the Finish time is when its status becomes LoggedOff or Cleared.

For Standard Activities with TravelMode NoTravel, the status Travelling is invalid and SP_INVALID_STATUS (45) is returned

All Day & Unallocated Jobs

This API call has no effect on the Start time or Arrival time of an all-day job. The all-day job’s Finish time is adjusted, as specified below, when the new status is LoggedOff or Cleared.

The dispatch status of an unallocated job is undefined. However, the status of an unallocated job can be set to Cleared, and SP_OK (0) will be returned - error SP_UNRESOURCED_JOB (148) will be returned for a change to any other status.

Current status: Tentative, Earmarked or Contacted

New status: Travelling - (valid for Standard activities only if TravelMode != NoTravel)

The work item’s Start time is adjusted to be the time now (or the supplied DateTime parameter).
The Arrival and Finish times are adjusted by the same amount of adjustment.

New status: LoggedOn -

The work item’s Start time and Arrival time are both adjusted to be the time now (or the supplied DateTime parameter), i.e. the travel time is set to zero. (This behaviour may change in a future release.)
The Finish time is adjusted by the same amount as the Arrival time.

New status: LoggedOff or Cleared - (aka “phone cleared”):

The work item’s Finish time will be adjusted to be the time now (or the supplied DateTime parameter), unless that time is earlier than the work item’s Start time, in which case the Finish time will be made the same as the Start time.
- In this particular case, if the work item is a job it will also be marked as effectively cancelled (though not removed from the database) so that the Gantt will not display it or take account of it in job shuffling or overlap adjustment, and the optimizer will ignore it and not treat it as a fixed activity.
If the Arrival time is after the Finish time, it will be made the same as the Finish time.

Current status: Travelling

New status: LoggedOn -

The work item’s Arrival time is adjusted to be the time now (or the supplied DateTime parameter), unless that time is earlier than the work item’s Start time, in which case the Arrival time is set to be the same as the Start time.
The Finish time is adjusted by the same amount.
The work item’s Start time remains unchanged.
The work item's estimated TravelTo time is updated with the actual travel time.

New status: LoggedOff or Cleared -

The work item’s Finish time is adjusted to be the time now (or the supplied DateTime parameter), unless that time is earlier than the work item’s Start time, in which case the Finish time is set to be the same as the Start time.
If the Arrival time is after the Finish time, it will be made the same as the Finish time.
The work item’s Start time remains unchanged.
The work item's estimated TravelTo time is updated with the actual travel time.

Current status: LoggedOn

New status: LoggedOff or Cleared -

The work item’s Finish time is adjusted to be the time now (or the supplied DateTime parameter), unless that time is earlier than the work item’s Arrival time, in which case the Finish time will be made the same as the Arrival time.
The work item’s Start and Arrival times remain unchanged.
Note: If the status is changed from LoggedOff to Cleared, the Start, Arrival and Finish times remain unchanged.

Status Effects on Real Time Traffic (RTT) data

These effects will only take place if RTT is enabled with postcode_rtt_lookup.

Current status: Tentative

The work item's RTT Travel Time, RTT Route ID and RTT Travel Home are not set up - and any job with RTT fields setup going to Tentative or Unallocated will have all the fields unset.

Current status: Earmarked or Contacted

The work item's RTT Travel and RTT Route ID fields will now be eligible for update when the time comes in postcode_rtt_update_lead seconds before the item's start travel time (unless the RTT request fails).

Current status: Travelling

The work item's RTT fields are frozen while it is in this status.

Current status: LoggedOn

The work item's RTT Travel Time will be updated to the actual time taken to travel to the location. In this case, the estimated TravelTo time will not be changed.

Current status: LoggedOff or Cleared

The work item's RTT Travel Home will be set up if it is the last job in the op-day (unless the RTT request fails).
The RTT Travel Home will not be updated if the work item moved from LoggedOff to Cleared.

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:

Click here to expand...

SP_OK (0)
SP_JOBID_INVALID (1)
SP_DURATION_INVALID (12)
SP_DATE_INVALID (14)
SP_TIME_INVALID (29)
SP_END_NOT_GT_START_TIME (31)
SP_INVALID_STATUS (45)
SP_OUTSIDE_HORIZON (53)
SP_STATUS_BACKWARDS (85)
SP_STATUS_NO_CHANGE (86)
SP_UNRESOURCED_JOB (148)
SP_TRAVEL_INVALID (154)
SP_OUTSIDE_FRU_POSTING (264)
SP_OK_WITH_OVERLAPS (373)
SP_DST_TIME_INVALID (379)
SP_TRAVELLING_TOO_EARLY (380)
SP_TRAVELLING_TOO_LATE (381)
SP_LOGGEDON_TOO_EARLY (382)
SP_LOGGEDON_TOO_LATE (383)
SP_LOGGEDOFF_TOO_LATE (384)
SP_CLEARED_TOO_LATE (385)
SP_ADJ_WOULD_SPAN_DAYS (577)
SP_WORKITEMTYPE_INVALID (671)
```
SP_JOB_SPARE_NOT_BOOKED (804)
```

Browser not supported