On This Page:

Related Pages:

The sp:DispInitRequest API method can be used to initialize the dispatch queue.

Description

The dispatch queue must be initialized in order for Work Items to be collected from it via the Get Dispatchable Jobs and Activities SOAP API.

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:DispInitRequest>`
	`<FRUs>?</FRUs>`		`FRUID`	A Final Responsibility Units (FRU) for which jobs are to be dispatched to the connected client. To dispatch jobs for multiple FRUs, supply the `FRUs` parameter multiple times, once for each `FRUID`. If the `FRUs`, `teams` and `EmpID` parameters are not supplied, then all FRUs and teams are included. For real-time `mode` dispatch, only `FRUs` can be specified. For batch `mode` dispatch, either `FRUs` or `teams` or `EmpID` can be specified, but not any combination of them.
	`<teams>?</teams>`		TeamID	A teams for which jobs are to be dispatched to the connected client (batch `mode` only). To dispatch jobs for multiple teams, supply the `teams` parameter multiple times, once for each `TeamID`. If you do not want to specify teams do not supply the parameter.
	`<empID>?</empID>`		`EmpID`	The ID of a single operative to be dispatched (batch `mode` only).
	`<timezone>?</timezone>`		`string`	Specifies the timezone which the times (DateTime, ETS, ETA, ETF, BreakStart) returned by DispatchRequest are to be local to. It must be a POSIX timezone string that appears in the sp-56 table in the database, for example: `EST5EDT,M4.1.0,M10.5.0` or `IST-5.30` If not supplied, the database parameter `tz_disp_api` will be used. If timezone is specified to be local to customer then BreakStart will be local to the Employee.
	`<mode>?</mode>`		`DispMode`	Specifies whether real-time dispatch of jobs is required, or whether a batch run is required. In batch mode, dispatch completes one scan and then exits. For batch mode only, the `batchInfo` parameter must be populated.
	`<batchInfo>`			Determines which jobs are candidates for dispatch. If `mode` is set to real-time, this parameter is ignored.
		`<jobsMax>?</jobsMax>`	`int`	The maximum number of jobs to be dispatched, per operative. This specifies the number of jobs per operative, within the time range specified, that are considered for dispatch, the jobs being considered in chronological order. Thus, for example, if `jobsMax` were set to 2, the first 2 jobs starting within the time range specified would be considered for dispatch: if both were already at status Earmarked or above, then neither would actually be dispatched. If `jobsMax` is omitted then there is no limit to the number of jobs to be dispatched per operative. If Earmark Same-site Jobs Together is true, `jobsMax` will be ignored jobs so that jobs in a same-site group may be dispatched together. Standard activities ARE included in the count for `jobsMax`. Breaks are not included in the count for `jobsMax`.
		`<rangeType>?</rangeType>`	`DispRangeType`	Determines how the `rangeStart` and `rangeEnd` parameter are interpreted. If `rangeType` is set to `Jobs`, then all jobs that start between `rangeStart` and `rangeEnd` are candidates for dispatch. If `rangeType` is set to `Shifts`, then all jobs that start on an operative day that contains a shift that starts between `rangeStart` and `rangeEnd` are candidates for dispatch. If an operative day does not contain a shift, then jobs on that day are not dispatched. If the shift start has been overridden, then it is the new shift start that must be between `rangeStart` and `rangeEnd`. Applies to both Jobs and Standard activities.
		`<rangeStart>?</rangeStart>`	`spDateTime`	If `rangeStart` is not supplied, ServiceOptimizer will use a default value of start-of-day today.
		`<rangeEnd>?</rangeEnd>`	`spDateTime`	If `rangeEnd` is not supplied, ServiceOptimizer will use a default value of end-of-day on `rangeStart` (which may have defaulted to today).
	`</batchInfo>`
`</sp:DispInitRequest>`

If FRUs have been specified, rangeStart and rangeEnd are treated as being local to that FRU.

If teams have been specified, and the team’s IRU has a timezone, then rangeStart and rangeEnd are treated as being local to that IRU. If teams have been specified, and the team’s IRU does not have a timezone, then rangeStart and rangeEnd are treated as being local to the timezone of that IRU’s containing FRU.

If neither FRUs nor teams nor EmpID have been specified (i.e. dispatch all FRUs), then rangeStart and rangeEnd are treated as being local to each FRU.

If EmpID has been specified, then rangeStart and rangeEnd will be assumed to be local to that employee’s time zone if they have one. If they have not, rangeStart and rangeEnd will be assumed to be local to the employee’s Team’s IRU or FRU.

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_EMPID_INVALID (5)
SP_OUTSIDE_HORIZON (53)
SP_UNITTYPE_INVALID (77)
SP_INVALID_TIME_ZONE_LOCATION (144)
SP_DISPATCHING_ALREADY (161)
SP_EMP_NOT_POSTED (178)
SP_TEAMID_INVALID (200)
SP_FRUID_INVALID (278)
SP_DISPATCH_MODE_INVALID (361)
SP_JOBS_MAX_INVALID (362)
SP_RANGE_TYPE_INVALID (363)
SP_RANGE_START_GT_END (364)
SP_RANGE_START_INVALID (365)
SP_RANGE_END_INVALID (366)
SP_FRU_TEAM_EMP_COMBINATION_INVALID (367)
SP_BATCHINFO_NULL (368)
SP_DST_TIME_INVALID (379)
SP_EMPID_NOT_ALLOWED (503)

Browser not supported