Description

The sp:GetJobRequest API method returns job details for a given job identifier.

Definition

The definition of this API is:

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.
	`<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>`

Return Structure

The API returns a non-standard return structure.

Click here to 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 Integration ServiceOptimizer Common API Concepts Mandatory Preferred Excluded Employees.
			</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.
		`<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.
		<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.

All of the fields to do with dates and times are local to what is specified in the tz_GJAPI database parameter for resourced jobs and local to what is specified in the tz_GJAPIUnres database parameter for unresourced jobs. These can be set such that dates and times are local to the timezone of the responsibility unit which contains the job, local to the employee that the job is allocated to (if it’s resourced), local to a specified or default timezone, or in GMT with or without daylight saving (BST).

Return Codes

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

SP_OK (0)
SP_JOBID_INVALID (1)

ServiceScheduling 13.3

Integration ServiceOptimizer Get Job SOAP API

Description

Definition

Return Structure

Return Codes