On This Page:
Related Pages:
The sp:GetJobRequest
API method can be used to obtain the details of a job.
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 extracted. | 
| 
|
| <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. |  | |
</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
| The earliest date and time at which an appointment can be started OR The ContractEarliest for an SLA. | | |
| | <latest>?</latest>
| spDateTime
| 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>
| int
| 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. | 
| 
|
| | </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>
|
| 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>
|
| 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>
|
| 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. | | |
| | <scheduledEmp>?</scheduledEmp>
|
| 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 . | | |
| | | <empName>?</empName> | String | The full name of the employee undertaking the job. | | |
| | | <empSurname>?</empSurname> | String | The surname of the employee undertaking the job. | | |
| | </scheduledEmpDetail> | | | | |
| | <priority>?</priority>
|
| 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>
| | Job Status 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
| Is the textual description of the fru as set up in the ServicePower database. | | |
| | <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 | | |
| </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 (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:
SP_OK (0)
SP_JOBID_INVALID (1)