Panel

On This Page:

Table of Contents

Related Pages:

Panel
The `sp:GetJobRequest` API method can be used to obtain the details of a job.

...

Web Service		Type	Description	Req?	Val?
`<sp:GetJobRequest>`
	`<jobID>?</jobID>`	`JobID`	The identifier of the job whose details are to be returned.
	`<sparesInfo>?</sparesInfo>`	`Boolean`	Indicates whether the job spares information will be returned or not. By default the value for `sparesInfo` is treated as `false` and no job spares information is returned.
	<`timeZoneInfo`>?</`timeZoneInfo`>	`Boolean`	Will return timezone in the ISO-8601 format. By default the value for `timeZoneInfo` is treated as `false` and the date/time fields will return in the non-ISO format.
	`<empInfo>?</empInfo>`	`Boolean`	Indicates whether the name details of the employee allocated to the job will be returned or not. By default the value for `empInfo` is treated as `false` and no name details of the employee allocated to the job are returned.
	`<VirtualWorkDLInfo>?</VirtualWorkDLInfo>`	`Boolean`	When set to `true`, Virtual Work Dynamic Location information will be included in the response. By default the value for `VirtualWorkDLInfo` is treated as `false` and Virtual Work Dynamic Location information will not be included in the response.
`</sp:GetJobRequest>`

...

The API returns a non-standard return structure.

Expand

Web Service					Type	Description	Req?	Val?
`<sp:GetJobResponse>`
	`<jobDetails>`
		`<jobType>?</jobType>`			`JobTypeID`	As specified when the job was booked.
		`<earliest>?</earliest>`			`spDateTime`	Either: The earliest date and time at which an appointment can be started; or The Contract Earliest for an SLA.
		`<latest>?</latest>`			`spDateTime`	Either: The latest date and time at which an appointment can be started (or completed if the job is Call to Fix); or The Contract Latest for an SLA
		`<ReqEmpType>?</ReqEmpType>`			`int`	Present for reasons of backwards compatibility – please ignore.
		`<listReqEmps>`
			`<reqEmp>`
				`<EmpID>?</EmpID>`	`EmpID`	Identifier of an employee who is either preferred or mandated (by the user) for the task, or who must not be assigned to the task.
				`<ReqEmpType>?</ReqEmpType>`	`EmpMPX`	See Mandatory/Preferred/Excluded Employees (MPX).
			</reqEmp>
		`</listReqEmps>`
		`<customer>`				Customer information. Structure is optional as data may not be available in the Optimizer tables.
			`<custID>?</custID>`		`CustID`	The customer ID.
			`<custName>?</custName>`		`CustName`	The customer name.
			`<custAddress>?</custAddress>`		`CustAddress<4>`	The customer address.
			`<contactName>?</contactName>`		`ContactName`	The customer contact name.
			`<phoneNum>?</phoneNum>`		`PhoneNum<2>`	The customer phone number.
		`</customer>`
		`<actNotes>?</actNotes>`			`ActNotes`	Free text description. For a job, this is constructed from the 4 description fields supplied when the job was booked, separated by newline characters.
		`<moreNotes>?</moreNotes>`			`string`	An optional extra description that can be supplied when the job is booked.
		`<isAllDayJob>?</isAllDayJob>`				Not used – JobStatus field value = 8 will be returned for AllDayJob.
		`<postcode>?</postcode>`			`Postcode`	Postcode of the employee's location at the time the job is completed.
		`<region>?</region>`			`unsigned int`	The identifier of the region in which the job takes place.
		`<expectedStart>?</expectedStart>`				The date and time at which the job is expected to start. For a job that spans more than one operative day, this is the start of the first part job. This field is always `NULL` for an unresourced job.
		`<expectedEnd>?</expectedEnd>`				The date and time at which the job is expected to end. A `NULL` value indicates that the job continues indefinitely. For a job that spans more than one operative day, this is the end of the last part job. This field is always `NULL` for an unresourced job.
		`<travel>?</travel>`			`unsigned int`	The amount of travel time, in seconds, which is included in the job duration. This is used only for faults and appointments. For a job that spans more than one operative day, this is the travel to the first part job. This field is always `NULL` for an unresourced job.
		`<rttTo>?</rttTo>`			`int`	The amount of expected Real Time Traffic travel time in seconds. Only returned if the RTT value has been set up in the job - so may not be returned even if RTT is enabled.
		`<BreakTime>?</BreakTime>`			`int`	The number of minutes (if any) allowed for any breaks in the duration between `expectedStart` and `expectedEnd`; undefined if the job is unresourced.
		`<scheduledEmp>?</scheduledEmp>`			`EmpId`	The identifier of the employee undertaking the job. if the Job is unresourced, this parameter is not returned at all.
		`<scheduledEmpDetail>`				The name details of the employee undertaking the job. Only returned when the `empInfo` parameter in the API call is set to `true`, and when the job is resourced.
			`<empName>?</empName>`		`string`	The full name of the employee undertaking the job.
			`<empSurname>?</empSurname>`		`string`	The surname of the employee undertaking the job.
			`<shiftStart>?</shiftStart>`		`spDateTime`	The date and time of the start of the assigned employee's shift in which the job is to be undertaken.
			`<shiftEnd>?</shiftEnd>`		`spDateTime`	The date and time of the end of the assigned employee's shift in which the job is to be undertaken. Note that the date may be the day after the `shiftStart` day, in the event that the employee's shift runs over midnight.
		`</scheduledEmpDetail>`
		`<priority>?</priority>`			`int`	The job priority which affects the cost of the Job's being late against its SLA end date-time.
		`<disStatus>?</disStatus>`			`DisStatus`	The current dispatch status of the job.
		<disStatus>?</disStatusCancelled>			DisStatusCancelled	Displays canceled status for canceled dispatched jobs.
		`<jobStatus>?</jobStatus>`			`int`	The job status of the job. Valid values are: 0 - Normal 1 - Reserved 4 - Cleared 8 - All Day Job 9 - Reserved
		`<fixedStatus>?</fixedStatus>`			`boolean`	Indicates whether the job has been fixed on the schedule.
		`<FRU>?</FRU>`			`RUID`	Responsibility Unit to which the job belongs.
		`<fruDescription>?</fruDescription>`			`string`	The textual description of the FRU as set up in the ServicePower database.

...

Image Added

<timeZone>?</timeZone> string An offset from UTC time Image Added

<SparesInfo>

List of spares information. Only returned when the sparesInfo parameter in the API call is set to true in the request.

<ReqSpares>

The IDs and quantities of the spares needed for this job. The ID of the spares that are actually allocated are the first in the list, followed by the substitutes if there were any. If there are no spares associated with the job then the ReqSpares structure will not be returned.

<SpareID>?<SpareID>

SpareID

<Quantity>?<Quantity>

int

</ReqSpares>

<ForceGo>?<ForceGo>

boolean

Indicates whether the job has been forced to the employee as they don't have the required spares for the job. This may have been set on the initial job booking, or by a subsequent move on the Gantt.

<Source>?</Source>

SpareSource

Indicates for a job requiring spares, whether the job is in the intray, or the spares were available from the van, or the spares were sourced externally either because the job was booked with spareIgnVanStock or SpareForceGo. For a job with no spares this will be set to None.

</SparesInfo>

<cancelDate>?</cancelDate> spDateTime If the job has been cancelled, the date and time when the job was cancelled.

<cancelReason>

<cancelReasonId>?</cancelReasonId> cancelReasonId If the job has been cancelled, the cancellation reason ID given when the job was cancelled.

<cancelDescription>?</cancelDescription>

cancelReasonDesc

If the job has been cancelled, the free-form text reason for cancellation given when the job was cancelled (if supplied).

</cancelReason>

<vwdlLocationType>?</vwdlLocationType> EmpLocType Returned only when the VirtualWorkDLInfo parameter is set to true in the API request. When the job is a Virtual Work Dynamic Location job, then vwdlLocationType indicates the dynamic location selected for the job.

</jobDetails>

</sp:GetJobResponse>

The main structure in the GetJobResponse declaration, JobDetails, contains the most ‘important’ information (mostly that generated by ServiceOptimizer) about the job to be dispatched.

...

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

SP_OK (0)
SP_JOBID_INVALID (1)

...

Versions Compared

Old Version 1

New Version Current

Key

Return Codes

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Return Codes