On This Page:
Related Pages:
The sp:JobHistoryRequest API method can be used to obtain the details of a job's history.
Description
The sp:JobHistoryRequest API method allows the details of changes made to a given job over time to be obtained. The API offers a number of different options to filter the change details that are returned.
Definition
The definition of this API is:
Click here to expand...
Web Service | Type | Description | Req? | Val? |
<sp:JobHistoryRequest>
|
| | | |
| <jobId>?</jobId> | JobID
| The identifier of the job for which the job history is required. The error SP_JOBID_INVALID (1) will be returned if the supplied JobID does not exist in the ServicePower database. | 
|
|
| | <options>?</options> | HistoryOptions | An optional field which can be used to restrict the type of changes returned. When set to All: - As per
HistoryOptions, system and manual history changes will be returned. - Any supplied
filterUserList values in the API call will be ignored. - Results will be filtered by any supplied
filterActionList values in the API call.
When set to Manual: - As per
HistoryOptions, only manual history changes will be returned. - Results will be filtered by any supplied
filterUserList values in the API call. - Results will be filtered by any supplied
filterActionList values in the API call.
When set to System: - As per
HistoryOptions, only system history changes will be returned. - Any supplied
filterUserList values in the API call will be ignored. - Results will be filtered by any supplied
filterActionList values in the API call.
When not supplied, the options field will use a default value of All - however, in this situation, the inclusion of any supplied filter options via the filterUserList and filterActionList structures will result in the SP_NO_OPTIONS_SET (807) error being returned. | | |
| | <filterUserList> | | An optional structure containing one or more filterUser values. When supplied (and not ignored, depending on the value supplied for the options parameter), the job history changes returned will be filtered to only those changes performed by the user(s) that match the value(s) supplied. | | |
| | | <filterUser>?</filterUser> | string(1-50) | A string matching an entry from the SP088_USERS_UNITS table, representing a user. | | |
| | </filterUserList> | | | | |
| | <filterActionList> | | An optional structure containing one or more filterAction values. When supplied (and not ignored, depending on the value supplied for the options parameter), the job history changes returned will be filtered to only those changes that match the action value(s) supplied. - If any
filterAction value supplied is invalid, then the SP_FILTER_ACTION_DOES_NOT_EXIST (805) error will be returned.- An invalid value means:
- A value supplied does not match one of the valid values listed below;
- The
options field has been set to Manual, but a value supplied corresponds to a SP598_SYSTEM_ACTIONS table action; or - The
options field has been set to System, but a value supplied corresponds to a SP501_GANTT_ACTIONS table action.
- If any
filterAction value is duplicated in the filterActionList, then the SP_FILTER_ACTION_DUPLICATE (806) error will be returned. - If the
filterActionList structure is supplied but ignored, then the SP_OK_FILTERLIST_IGNORED (810) warning will be returned.
| | |
| | | <filterAction>?</filterAction> | string(1-255) | A string matching an entry from either the SP501_GANTT_ACTIONS table or the SP598_SYSTEM_ACTIONS table, representing a type of change to the job (i.e. action). Valid values are: SP501_GANTT_ACTIONS Table Action | Description |
|---|
Call.Confirm
| The job's confirmed state was changed. | FJ.Alloc | The job was allocated via the ServiceGANTT "Find Job" function. | FJ.Move | The job was moved via the ServiceGANTT "Move Job" function. | Job.Alloc | The job was allocated. | Job.Book | The job was booked to the "intray". | Job.ChAccess | The job's Access Hours were changed. | Job.ChAttrib | The job's attributes were changed. | Job.ChFixed | The job's Fixed Status was changed. | Job.ChStatus | The job's Dispatch Status was changed. | Job.Dealloc | The job was Deallocated. | Job.Move | The job was moved. | Job.Resize | The job was resized. | Job.RestoreAHP | The job's Access Hours Pattern was restored. | SP598_SYSTEM_ACTIONS Table Action | Description | act.move | The job was moved. | BookAppt | The job was booked from an external system. | BookApptExecute | The job was booked from an external system. | BookDependencyGroupFromSlots | The job was booked as a group of dependent jobs. | BookJobFromSlot | The job was booked as an SLA job from an external system. | BookJobFromSlotExecute | The job was booked as an SLA job from an external system. | CancelAppt | The job was cancelled from an external system. | CancelDependencyGroup | The job's dependency group was cancelled. | ChangeJobArrivalTime | The job's Arrival Time was changed. | ChangeJobDateTimes | The job's Date Time was changed. | ChangeJobFinishTime | The job's Finish Time was changed. | ChangeJobPriority | The job's Priority was changed. | ChangeJobStartTime | The job's Start Date was changed. | ChangeJobStatus | The job's Status was changed from an external system. | DBTidy | The job was changed by the DBTidy process. | DeleteJob | The job was deleted. | DeleteJobExecute | The job was deleted. | FindNextJob | The system action recorded when the job was allocated via the ServiceGANTT "Find Job" function. | GetSlotForBookJobWithReassign | The job was moved to make space for an SLA job. | job.alloc | The job was allocated. | job.book | The job was booked to the "intray". | job.chaccess | The job's Access Hours were changed. | job.chappt | The job's Appointment Hours were changed. | job.chattrib | The job's attributes were changed. | job.chstatus | The job's Dispatch Status was changed. | job.dealloc | The job was Deallocated. | job.gnjexecute | The system action recorded when the job was moved via the ServiceGANTT "Move Job" function. | job.restoreahp | The job's Access Hours Pattern was restored. | JobForceFix | The job was moved and fixed. | main | The job was changed during FRU initialization tidy up. | OfferApptsWithReassign | The job was moved to make space for an appointment. | ru.overlaps | The job was moved to fix a schedule overlap issue. | SetJobCleared | The job was marked as cleared by an external system. | UpdateJob | The job details were changed by an external system. |
| | |
| | </filterActionList> | | | | |
</sp:JobHistoryRequest> | | | | |
Return Structure
The API returns a non-standard return structure.
Click here to expand...
Web Service | Type | Description | Req? | Val? |
<sp:JobHistoryResponse>
|
| | | |
| | <result>
| | A structure containing details of the success or failure of the API call. | | |
| | | <type>?</type> | ReturnCodeType | The type of return code, indicating if the result is success, success with a warning, or failure. | | |
| | | <code>?</code> | int | The Return Code number, representing the result of the API call. | | |
| | | <errNote>?</errNote> | string | Optional note about any error(s). |  | |
| | </result> | | | | |
| | <auditStatus> | | A optional structure describing the level of job history auditing that is currently enabled in ServiceScheduling. - This structure is only returned when the API call does not return an error Return Code.
| | |
| | | <ganttAuditing>?</ganttAuditing> | AuditStatus | Indicates if job history auditing of changes made via ServiceGANTT is enabled or not enabled. | | |
| | | <systemAuditing>?</systemAuditing> | AuditStatus | Indicates if job history auditing of changes made via the API and/or ServiceOptimizer system is enabled, not enabled, or partially enabled. | | |
| | | <auditSetup> | | An optional structure, which may be returned multiple times, providing further details on the level of API and/or ServiceOptimizer system job history auditing, when this is only partially enabled. - This structure is only returned when the
systemAuditing value above is PARTIAL.
| | |
| | | | <auditName>?</auditName> | string | The name of the relevant SP083_SYSTEM_PARAMETERS table entry that the auditUsage structure is providing details on. One of: gantt_audit_trailsp100_auditsp108_auditsp111_audit
| | |
| | | | <auditStatusValue>?</auditStatusValue> | AuditStatus | Indicates if job history auditing via the relevant parameter defined by the auditName value in the auditUsage structure is enabled or not enabled. | | |
| | | </auditSetup> | | | | |
| | </auditStatus> | | | | |
| | <transaction> | | An optional structure, which may be returned multiple times, containing the details of the relevant job history records, given the API call input values. - This structure is only returned when the API call does not return an error Return Code.
- This structure is only returned if there any relevant job history records to be returned.
| | |
| | | <timestamp>?</timestamp> | timestamp | The date and time of the job history record. Times are in the time zone of the database server (SYSDATE) with no conversion applied. | | |
| | | <sequence>?</sequence> | | A sequence number, where multiple records are recorded for the same transaction. | | |
| | | <transaction>?</transaction> | | The job history transaction number. | | |
| | | <action>?</action> | string(1-20) | Either: A string matching an entry from the SP501_GANTT_ACTIONS table, representing a type of change made by a user (i.e. see details in the description of the filterAction input field); or A string matching an entry from the SP598_SYSTEMS_ACTIONS table, representing a change made by the ServiceOptimizer system.
| | |
| | | <user>?</user> | string(1-50) | The username of the user who performed the change to the job, if relevant. | | |
| | | <field> | | An optional structure, which may be returned multiple times, containing the details of fields changed as part of the overall change to the job being described in the transaction structure. - This structure is only returned if one or more field values were changed as part of the
transaction.
| | |
| | | | <name>?</name> | | The name of the job field that was changed as part of the transaction. | | |
| | | | <old_value>?</old_value> | | The value of the field prior to the change. | | |
| | | | <new_value>?</new_value> | | The new value of the field as set by the change performed. | | |
| | | </field> | | | | |
| | </transaction> | | | | |
</sp:JobHistoryResponse> | | | | |
Return Codes
In addition to the Standard Return Codes, the possible Return Codes from this API are:
Click here to expand...
SP_JOBID_INVALID (1)SP_USERID_DOES_NOT_EXIST (703)SP_FILTER_ACTION_DOES_NOT_EXIST (805)SP_FILTER_ACTION_DUPLICATE (806)SP_NO_OPTIONS_SET (807)SP_USER_NOT_VALID (808)SP_FILTER_USER_DUPLICATE (809)SP_OK_FILTERLIST_IGNORED (810)
