On This Page:

Related Pages:

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?
`<sp:DispRequest/>`

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:DispRequestResponse>`
	`<jobInfo>`
		`<jobID>?</jobID>`		`JobID`	ID of earmarked job or standard activity. If a break is being dispatched without a job or SA this value is set to -1.
		`<earmarkType>?</earmarkType>`		`DispEarmarkTypes`	On return, indicates whether this request is an earmark, an unearmark or a re-earmark and whether the item is a job/break, or a standard activity. If the value is `UnEarmark`, only the following fields have valid values: `JobID`, `ReEarmark` (`SP_False`), `DateTime`, `EmpID`, `JobCountTentative`, `BookLoc`, `BookLocName`, and `Postcode`. In addition, if configured, the value of `None` may be returned to indicate that the job has changed jeopardy state.
		`<reEarmark>?</reEarmark>`		`boolean`	Indicates that this item’s ETA has changed, but not its `EmpID`.
		`<dateEarmarked>?</dateEarmarked>`		`spDateTime`	Time the work item was earmarked.
		`<empID>?</empID>`		`EmpID`	Employee it was earmarked to.
		`<ETS>?</ETS>`		`spDateTime`	The time the employee should start. This field is not used for stand-alone break dispatching.
		`<ETA>?</ETA>`			The time the employee should arrive. This field is not used for stand-alone break dispatching.
		`<ETF>?</ETF>`			The time the employee should finish. This field is not used for stand-alone break dispatching.
		`<jobCountTentative>?</jobCountTentative>`		`int`	The number of jobs tentatively allocated to this `EmpID`. The `jobCountTentative` field is a count of jobs that have been allocated to this employee (`EmpID`), but which they do not know about yet. Its value depends on the value of the database parameter `disp_job_count_tentative_days`. If `disp_job_count_tentative_days` not present or has the value 0, then `jobCountTentative` is the number of jobs, not including this one being earmarked, that are currently allocated to this `EmpID`, while the employee is posted to the FRU containing this job, between now and the end of the Reactive Working Period (TWP – measured over operative days), whose status is `Tentative` or is `Earmarked` but which hasn’t yet been successfully dispatched. If `disp_job_count_tentative_days` is non-zero, then `jobCountTentative` only returns the number of jobs for that number of days instead of for the Reactive Working Period. For example, if `disp_job_count_tentative_days` is 1, then `jobCountTentative` returns the number of remaining jobs for today. A `jobCountTentative` value is only returned when dispatch is being done in real-time mode. If it’s running in batch mode, then `jobCountTentative` will be set to -1. This field is not used for either standard activity or stand-alone break dispatching. Alternatively, when the `earmarkType` value is set to `None`, indicating that the `jobInfo` represents a job that has changed jeopardy state, then `jobCountTentative` will be set to the Jeopardy State Type 1 value that, combined with the Jeopardy State Type 2 value returned in the `totalBreakTime` field, represents the jeopardy state that the job is now in. When the `earmarkType` value is set to `None` and `jobCountTentative` and `totalBreakTime` are both 0, then this indicates that the job has changed jeopardy state so that is is no longer in jeopardy.
		`<totalBreakTime>?</totalBreakTime>`		`unsigned int`	The sum of all durations of included breaks. If breaks have been scheduled to be taken during the job or standard activity, then `totalBreakTime` gives the sum of all break durations and `ScheduledBreaks` provides the list of those breaks, otherwise, it is null. Alternatively, when the `earmarkType` value is set to `None`, indicating that the `jobInfo` represents a job that has changed jeopardy state, then `totalBreakTime` will be set to the Jeopardy State Type 2 value that, combined with the Jeopardy State Type 1 value returned in the `jobCountTentative` field, represents the jeopardy state that the job is now in. When the `earmarkType` value is set to `None` and `jobCountTentative` and `totalBreakTime` are both 0, then this indicates that the job has changed jeopardy state so that is is no longer in jeopardy.
		`<breaks>`
			`<BreakName>?</BreakName>`	`BreakName`	The name of the break (see §2.3)
			`<BreakType>?</BreakType>`	`BreakType`	The type of break. If the `BreakType` is `Default` the break is as defined in the base shift definition. If the `BreakType` is `Overridden` the break has been overridden by a shift override. If the `BreakType` is `Fixed` the break has been fixed in place via either the Gantt or the FixBreakTimesRequest web service
			`<BreakStart>?</BreakStart>`	`Time`	The time the break is scheduled to start.
			`<BreakDuration>?</BreakDuration>`	`unsigned int`	The amount of time allowed in the schedule for this break.
		`</breaks>`
		`<bookLoc>?</bookLoc>`		`BookLocID`	The booking location ID. It has the value supplied when the job was booked using the Book Appointment SOAP API or the Book Non-Appointment Job SOAP API. This field is not used for stand-alone break dispatching.
		`<bookLocName>?</bookLocName>`		`BookLocName`	Any info associated, e.g. IP add/port, Q name. This field is not used for stand-alone break dispatching.
		`<postcode>?</postcode>`		`Postcode`	Job or standard activity Location. This field is not used for stand-alone break dispatching.
		`<teamID>?</teamID>`			The team that `EmpID` is posted to.
		`<IRUID>?</IRUID>`		`RUID`	The IRU that the team is in.
	`</jobInfo>`
`</sp:DispRequestResponse>`

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)

Browser not supported