On This Page:

Related Pages:

The sp:GetJobsRequest API method call can be used to get the jobs for employees.

Description

The sp:GetJobsRequest API method returns the list of jobs for a given employee on a given date. If they are resourced, they are returned in order of their ExpectedStart.

The sp:GetJobsRequest API method can also be used to obtain a list of unresourced jobs for a responsibility unit. An unresourced non-appointment will only be returned if its contract earliest falls on or before the supplied DispatchDate. There is no defined order that unresourced jobs are returned in.

The information returned is grouped together in several structures within a larger structure. It’s not expected that all of the information returned will be used by the caller, but all available information which might possibly be useful can be returned. Some fields may be null, either because they were not specified when the job was booked, or because they are only applicable to either appointments, SLA work or because the job is unresourced.

Definition

The definition of this API is:

Click here to expand...

Web Service		Type	Description	Req?	Val?
`<sp:GetJobsRequest>`
	`<EmpID>?</EmpID>`	`EmpID`	is the identifier of the employee whose list of jobs is to be extracted; Mandatory if RespUnit not supplied. Otherwise optional
	`<DispatchDate>?</DispatchDate>`	`spDate`	is the date on which the jobs are to be carried out
	`<RespUnit>?</RespUnit>`	`RUID`	is the FRU for which unresourced jobs are to be extracted. If EmpID is supplied as well as RespUnit, EmpID is ignored. Mandatory if EmpID and Dispatch Date not supplied. Otherwise optional
	`<PrevJob>?</PrevJob>`	`JobID`	No longer in use
	`<JobCount>?</JobCount>`	`int`	is the number of jobs which should be returned in each batch. Omit if all
	`<JobInfoCount>?</JobInfoCount>`	`int`	Not used
	`<DispatchInfoCount>?</DispatchInfoCount>`	`int`	A non-zero value should be supplied if Dispatch info is wanted
	`<AuditInfoCount>?</AuditInfoCount>`	`int`	A non-zero value should be supplied if Audit info is wanted
	`<CustomerInfoCount>?</CustomerInfoCount>`	`int`	A non-zero value should be supplied if Customer info is wanted
	`<SparesInfoCount>?</SparesInfoCount>`	`int`	A non-zero value should be supplied if Spares info is wanted
`</sp:GetJobsRequest>`

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 (see [1]). 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 Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service					Type	Description	Req?	Val?
`<sp:GetJobsResponse>`
	`<PrevJob>?</PrevJob>`				`JobID`	The last job from the previous batch (if applicable)
	`<JobCount>?</JobCount>`				`int`	The number of jobs returned
						<!--Zero or more repetitions:-->
	`<JobInfo>`					List of JobInfo structures.
		`<Version>?</Version>`			`int`
		`<JobID>?</JobID>`			`JobID`	is the caller’s identifier of the job, as specified when the job was booked
		`<JobType>?</JobType>`			`JobTypeID`	as specified when the job was booked
		`<EstimatedDuration>?</EstimatedDuration>`			`int`	for a non-all-day job, is the Actual Duration of the job if it’s known (i.e. the job has been logged on or cleared), or, if not, the Scheduled Duration. For an all-day job, EstimatedDuration returns the same values, except if the job is in the in-tray, in which case 0 is returned since all-day jobs in the in-tray have no Scheduled Duration
		`<StartDate>?</StartDate>`			`spDate`	is the date of the ExpectedStart time (next)
		`<ExpectedStart>?</ExpectedStart>`			`Time`	is the scheduled time to start travelling to this job; null if job is unresourced
		`<EndDate>?</EndDate>`			`spDate`	is the date of the ExpectedEnd time (next)
		`<ExpectedEnd>?</ExpectedEnd>`			`Time`	is the scheduled time this job should finish; null if job is unresourced
		`<EmpID>?</EmpID>`			`EmpID`	is the identifier of the employee scheduled to do this job; null if job is unresourced
		`<TravelTime>?</TravelTime>`			`unsigned int`	is the expected journey time in minutes from the location of the previous job or activity to this job; undefined if the job is unresourced
		`<RttTo>?</RttTo>`			`int`	is the expected Real Time Traffic journey time in minutes from the location of the previous job or activity to this job; 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`	is the number of minutes (if any) allowed for any breaks in the duration between ExpectedStart and ExpectedEnd; undefined if the job is unresourced
	`</JobInfo>`
	`<DispatchInfo>`					List.
		`<Priority>?</Priority>`			`int`	as specified when the job was booked
		`<ExtraDuration>?</ExtraDuration>`			`int`	as specified when the job was booked
		`<Skills>?</Skills>`				from job type plus extra skills from web service call when the job was booked
		`<BookLoc>?</BookLoc>`			`BookLocID`	is the identifier of the server that booked this job, if that was specified when the job was booked
		`<Forced>?</Forced>`			`Boolean`	0 – not forced, 1 – forced
		`<ContractStart>?</ContractStart>`			`spDateTime`	as specified when the job was created
		`<ContractEnd>?</ContractEnd>`			`spDateTime`	as specified when the job was created
		`<AccessEarliest1>?</AccessEarliest1>`			`spDateTime`	are the first three Access Hours periods on DispatchDate (resourced non-appointment), or the Appointment Earliest & Latest (in AccessEarliest/Latest1) (appointment). If the job is unresourced, the first 3 pairs of Access Hours that overlap DispatchDate will be returned.
		`<AccessLatest1>?</AccessLatest1>`			`spDateTime`	“
		`<AccessEarliest2>?</AccessEarliest2>`			`spDateTime`	“
		`<AccessLatest2>?</AccessLatest2>`			`spDateTime`	“
		`<AccessEarliest3>?</AccessEarliest3>`			`spDateTime`	“
		`<AccessLatest3>?</AccessLatest3>`			`spDateTime`	“
		`<IsCallToFix>?</IsCallToFix>`			`Boolean`	as specified when the job was created, i.e. whether the job is call-to-fix or not
		`<CrewSize>?</CrewSize>`			`int`	the number of individuals required to have been assigned to the crew which will do this job
		`<ReqEmpType>?</ReqEmpType>`			`int`	Present for reasons of backwards compatibility – please ignore.
		`<listReqEmps>`				as specified when the job was booked: up to 10 employees who are the only ones permitted, or are preferred, or are not permitted to do this job
			`<reqEmp>`
				`<EmpId>?</EmpId>`	`EmpID`
				`<ReqEmpType>?</ReqEmpType>`		See Integration ServiceOptimizer Common API Concepts Mandatory Preferred Excluded Employees
			`</reqEmp>`
		`</listReqEmps>`
		`<PickupSize>?</PickupSize>`			`int`	is the amount of space occupied by equipment loaded onto the operative’s vehicle as part of this job.
		`<DeliverySize>?</DeliverySize>`			`int`	is the amount of space occupied by equipment removed from the operative’s vehicle as part of this job.
	`</DispatchInfo>`
	`<AuditInfo>`					List.
		`<Creation>?</Creation>`			`spDateTime`	date and time of the job’s creation
		`<Update>?</Update>`			`spDateTime`	date and time the job’s status was last updated
		`<Scheduled>?</Scheduled>`			`spDateTime`	date and time the job was assigned to the employee by the automatic scheduler
		`<Dispatched>?</Dispatched>`			`spDateTime`	date and time the details of the job were communicated to external systems
		`<JobStatus>?</JobStatus>`			`int`	2 is returned if the job is on hold. 8 is returned for an all day job. 4 is returned if the job was cleared (Cleared) before it was started (Travelling) (aka ‘phone cleared’).
		`<JeopardyStatus>?</JeopardyStatus>`				See section 4.3.1 for the declarations of different jeopardy states
		`<JeopardyStatus2>?</JeopardyStatus2>`				See section 4.3.2
		`<ScheduleStatus>?</ScheduleStatus>`				indicates whether the job was manually or automatically scheduled
		`<Postcode>?</Postcode>`			`Postcode`	of the job’s location
	`</AuditInfo>`
	`<Customer>`
						if specified when the job was booked (See section 4.4.3)
	`</Customer>`
	`<SparesInfo>`					List. Is returned if <SparesInfoCount> 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>`
`</sp:GetJobsResponse>`

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 (see [1]). 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:

Click here to expand...

SP_OK (0)
SP_JOBID_INVALID (1)
SP_EMPID_INVALID (5)
SP_DATE_INVALID (14)
SP_UNIT_INVALID (28)
SP_OUTSIDE_HORIZON (53)
SP_EMP_NOT_POSTED (178)
SP_EMPID_DOES_NOT_EXIST (231)
SP_UNIT_NOT_SUPPLIED (261)

Browser not supported