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.

If any filterUser value supplied is invalid, then the SP_USERID_DOES_NOT_EXIST (703) error will be returned.
If any filterUser value supplied is valid, but the user is not enabled, then the SP_USER_NOT_VALID (808) error will be returned.
If any filterUser value is duplicated in the filterUserList, then the SP_FILTER_USER_DUPLICATE (809) error will be returned.
If the filterUserList structure is supplied but ignored, then the SP_OK_FILTERLIST_IGNORED (810) warning will be returned.

<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_trail` `sp100_audit` `sp108_audit` `sp111_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)

Browser not supported