Change Work Item Status SOAP API
- Matthew Wren
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:
Web Service | Type | Description | Req? | Val? | |||
|
|
|
|
| |||
|
|
| Single item defining the work item to be changed. |
|
| ||
|
| The identifier of the job or standard activity whose status is to be changed. |
|
| |||
|
| Identifies whether this is an update to a job or standard activity. |
|
| |||
|
| The value to which the status of this work item is to be set. |
|
| |||
|
| 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
The employee who is assumed to have provided all the spares is the one to whom the |  | |||||
<spareID>?</spareID> | SpareID | The identifier for the spare used by the Error Error If a spare is passed that was not booked for the job then error |  | | |||
<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 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 | | ||||
</spareStock> | |||||||
|
|
|
|
|
| ||
|
|
|
|
| |||
- 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: