Get Dispatchable Jobs and Activities SOAP API
- Matthew Wren
The sp:DispRequest API method can be used to obtain jobs, breaks and standard activities that are available for dispatching.
Description
After the dispatch queue has been initialised via the Initialize Dispatch Queue SOAP API, each job, break or standard activity can be collected from the queue in turn.
If Initialize Dispatch Queue SOAP API was called by the client with DispatchMode set to RealTime, the sp:DispRequest API method call will block (i.e. wait consuming no CPU) until the next job, break or standard activity is ready to be earmarked and dispatched. It will only return when the next dispatch request is available, or the connection to the server is broken, e.g. by the server shutting down.
If there is a value set in the ServiceOptimizer database for disp_request_timeout, and there are no jobs, breaks or standard activities to return after that time has elapsed since the last call to sp:DispRequest, it will return SP_OK_DISPATCH_REQUEST_TIMEOUT (588). If another call to sp:DispRequest isn’t made within disp_inactivity_timeout, the connection will be closed by ServiceOptimizer. This feature is useful when there are firewalls between client and server; it keeps some traffic passing between them that will prevent firewalls from timing out and then no longer routing. ServiceOptimizer can also detect and close timed-out connections so that a renewed connection can be made for the same FRU/Team/Employee.
This API is called with no data and all the relevant data is returned as the response to the call. On return, it will contain the earmark information for a standard activity, job or a break. Breaks will be scheduled, and therefore dispatched, separately to jobs except where this is not possible. Break and standard activity dispatch follows the same rules as for Jobs unless otherwise stated.
‘At least once’ delivery of real-time messages (earmark, re-earmark and unearmark) will be guaranteed (up to their expiry time – see disp_expiry_time below), but not ‘at most once’, i.e. delivery is guaranteed, but dispatch clients must take steps to ignore duplicates because the state of message delivery can’t be determined in all circumstances.
There can either be a single real-time dispatch client that receives all of the dispatch messages for all FRUs (the simplest way), or there can be one dispatch client per FRU, or, for batch dispatch only, there can be one client per team or employee. However, each message will be dispatched to no more than one dispatch client (though it is possible that a Job earmarked in a batch will subsequently be re-earmarked or unearmarked in real time). As only one dispatch client is notified, only a single response (acceptance or rejection) is expected from that client. Notifying multiple clients and handling multiple responses must be done outside ServiceOptimizer.
A dispatch client’s response to each dispatch message can be either to accept it or to reject it; a missing response (two calls of sp:DispRequest with no intervening Confirm Dispatched Job SOAP API call for the first) is assumed to be a rejection. If it is rejected, the message will be dispatched again every disp_retry_time minutes (as long as the job has not been cancelled or re-booked) until it’s accepted or until the expected_end of the job is more than disp_expiry_time (minutes) in the past. In addition, the job will be reported as being in jeopardy, with a jeopardy type of “Dispatch Fail”.
There is another ‘expiry’ time (disp_earmark_postponement_time) defined for where moving a Job on the Gantt should ideally dispatch two messages together, but after this time will allow them to be dispatched independently (see [1]).
Normally dispatch messages will be delivered to clients in the order in which they are generated (FIFO). This is not guaranteed, however, and will obviously not be the case where dispatch messages are rejected and so are dispatched again.
Note that the SOAP implementation of the dispatch interface is limited to 100 requests. After 100 requests a client will be required to log back in to receive any further dispatch messages.
Definition
The definition of this API is:
Web Service | Type | Description | Req? | Val? | |||
|
|
|
|
| |||
Return Structure
The API returns a non-standard return structure.
The values of the DateTime, ETS, ETA and ETF fields are local to what is specified in the tz_disp_api database parameter unless APITimeZone was supplied in the previous call to DispInitRequest see Initialize Dispatch Queue SOAP API.
tz_disp_api can be configured to be local to the customer (i.e. to the region where the job is located), local to a supplied or default time zone, to the responsibility unit containing the job, to the employee, to the ServiceOptimizer or SMS server, or in GMT, with or without daylight saving (BST).
The value BreakStart is local to tz_disp_api unless APITimeZone was supplied in Initialize Dispatch Queue SOAP API. The exception is where the specified timezone is local to Customer in which case BreakStart is local to the Employee.
If tz_disp_api is set to be RU-local and the employee (EmpID) is posted at the time this job is scheduled to begin to an IRU that has a timezone, then DateTime, ETS, ETA, and ETF will be local to that IRU’s timezone.
Both EarmarkType and JobEarmarkInfo are populated only if SP_OK (0) is returned.
Return Codes
In addition to the Standard Return Codes, the possible Return Codes from this API are:
SP_OK (0)SP_DISP_BATCH_FINISHED (163)SP_DISP_INIT_EXPECTED (262)SP_OK_DISPATCH_REQUEST_TIMEOUT (588)