Integration ServiceOptimizer Change Work Item Status SOAP API
- Andrew Hill (Deactivated)
- Matthew Wren (Unlicensed)
- Debbie Roycroft (Deactivated)
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:
Web Service | Type | Description | Req? | Val? | ||
|
|
|
|
| ||
|
|
|
|
|
| |
|
|
| is 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 |
|
| |
|
|
| is the value the status of this work item is to be set to. SP_INVALID_STATUS (45)will be returned if the WorkItem is a standard activity that cannot be dispatched. |
|
| |
|
|
| is 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 |
|
| |
|
|
|
|
|
| |
|
|
|
|
| ||
The value of the dateTime timestamp is local to what is specified in the tz_CJS database parameter.
This can be set such that dateTime is local to the timezone of the region where the job is located, local to the timezone of the responsibility unit which contains the job, local to the employee that the job is allocated to, local to a specified or default timezone or in GMT with or without daylight saving (BST).
NOTE: There are circumstances where this call will cause the work item tospDateTime span the time when a break may be taken by the operative, so the time recorded may be different from the time expected.
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:
Note 1: The work item’s 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.
Note 2: ChangeWorkItemStatusRequest never has any effect on the Start time or Arrival time of an all-day job. The job’s Finish time is adjusted, but only when the new status is LoggedOff or Cleared.
Note 3: Work item dispatch status values are not allowed to go ‘backwards’ (e.g. the change LoggedOff back to LoggedOn is not allowed).
Note 4: 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, not SP_UNRESOURCED_JOB (148).
Note 5: ChangeWorkItemStatusRequest operates only on jobs and standard activities that start within the memory horizon.
Note 6: A call to ChangeWorkItemStatusRequest with NewStatus set to Earmarked will dispatch an Earmarked message if CJS: Dispatch Earmarked Jobs is set.
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.
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.
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.
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 job’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.)
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: