On This Page:

Related Pages:

The sp:GetChangedWorkItemsRequest API method can be used to obtain the details of changed work items (jobs and standard activities).

Description

The sp:GetChangedWorkItemsRequest API method will return a particular set of work items’ attributes (job or standard activity) if any of the work item’s attributes have changed since a previous call. The operation works for a single FRU for the whole memory horizon.

If the option JeopOnly is set, work items will be returned only if one of a configurable set of jeopardy conditions has changed. The jeopardy conditions that are to be monitored are configured by the FRU parameter GetChangedJobs: Jeopardy Conditions in the API section of the Scheduling Unit Settings page in ServiceManager (the database name is: gcj_jeop_check_states).

In this context, the change could be:

one or more of the configured jeopardy conditions for that work item has changed;
the configured conditions include “overdue” (P) and/or “Missed appointment - Late” (M) and the job is in jeopardy because it is overdue or late and the amount by which it’s overdue or late has changed; or
the configured conditions include “early” (Before Contract Earliest (B) or Missed Appointment (Me)) and the job is early and the amount by which it’s early has changed.

Changes are determined by time-stamp comparison. On the first call, the time-stamp should not be supplied so that all of the work items are returned along with a new server-generated time. This new time-stamp is then supplied to the next call so that the changes made since the previous call can be determined by the server, and only work items that have changed since that previous time-stamp are then returned.

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:GetChangedWorkItemsRequest>`
	`<FRUID>?</FRUID>`		`RUID`	The identifier of the FRU from which the jobs are required.
	`<timeStampIn>?</timeStampIn>`		`timeStamp`	A time stamp that is sent to indicate the time from which changes should be determined. It’s usually the time stamp returned from ServiceOptimizer in the previous call (TimeStampOut). This an opaque value that the caller should not interpret. To get all of the jobs in an FRU for the whole memory horizon, or, if `JeopOnly` is set, all of the jobs in any of the configured set of jeopardy conditions (see 4.3), this field should not be supplied.
	`<options>`
		`<JeopOnly>?</JeopOnly>`	`Boolean`	If `JeopOnly` is set, the call will return only work items whose one or more of the configured set of jeopardy conditions has changed since the last call. This includes: where a work item was in jeopardy states X (e.g. unscheduled) at the previous call and is no longer in jeopardy at all; or where a work item wasn’t in jeopardy and now is in jeopardy states X; or where work item was in jeopardy states X and is now in different jeopardy states Y; or where overdue (P) and/or late (M) is in the set of configured jeopardy conditions, and a job was overdue or late by a certain amount and now is overdue or late by a different amount; or where early (B or Me) is in the set of configured jeopardy conditions and a job was early and is now early by a different amount.
	`</options>`
`</sp:GetChangedWorkItemsRequest>`

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:GetChangedWorkItemsResponse>`
	`<timeStampOut>?</timeStampOut>`			`timeStamp`	`TimeStampOut` will normally be the time of this call to the Integration ServiceOptimizer Get Changed Work Items SOAP API (unless the supplied array is too small) and `TimeStampIn` will usually be the `TimeStampOut` returned from the previous call.
	`<workItem>`
		`<workItemID>?</workItemID>`		`WorkItemID`	The identifier of the work item.
		`<workItemType>?</workItemType>`		`WorkItemType`	Identifies whether a job or a standard activity.
		`<isFixed>?</isFixed>`		`Boolean`
		`<jobJeopardy>`
				`JeopStates`	All of the jeopardy states for the work item, irrespective of whether they are in the configured set or not.
		`</jobJeopardy>`
		`<attr>`			This element is not returned for an unresourced job.
			`<empID>?</empID>`	`EmpID`	The identifier of the operative that the job is allocated to.
			`<start>?</start>`	`spDateTime`	The date and time that the operative is scheduled to start travelling to the job.
			`<arrival>?</arrival>`	`spDateTime`	The date and time that the operative is scheduled to arrive at the job.
			`<finish>?</finish>`	`spDateTime`	The date and time that the operative is scheduled to finish the working part of the job, i.e. excluding travel home if there is any.
			`<disStatus>?</disStatus>`	`DisStatus`	The current dispatch status of the job, i.e. `Tentative`, `Earmarked`, `Contacted`, `Started (Travelling)`, `Logged On` , `Logged Off` or `Cleared`.
			`<overdue>?</overdue>`	`int`	Irrespective of whether overdue (P) or late appointment (M) or early (B or Me) is a configured jeopardy condition for this call, this is the amount by which the job is either: late if it’s an appointment (i.e. the time after its appointment latest), or overdue if it’s not an appointment (i.e. the time after its contract latest, taking its service hours into account), or early i.e. the time before its appointment earliest if it’s an appointment or before its contract earliest, taking service hours into account, if it’s not. If it’s scheduled but isn’t overdue or late or early, `overdue` is 0.
		`</attr>`
	`</workItem>`
`</sp:GetChangedWorkItemsResponse>`

Note: There is no guarantee that a changed work item is returned only once for each change.

Note: Because a work item is returned if any of its attributes have changed (unless JeopOnly is set), not just a change to those attributes returned, there will be circumstances when a work item is returned for which there has been no change apparent in the attributes returned.

Note: If a job is cancelled (via the Integration ServiceOptimizer Cancel Job SOAP API), or a standard activity removed, nothing will be reported about it thereafter, since it will have been removed from ServiceOptimizer. It’s assumed that the same system that called the Integration ServiceOptimizer Cancel Job SOAP API will be calling the Integration ServiceOptimizer Get Changed Work Items SOAP API and will therefore know not to expect anything to be reported about the job after cancellation.

All of the fields to do with dates and times are local to what is specified in the tz_GCJAPI database parameter. These can be set such that dates and times are local to the timezone of the region where the work item is located, local to the timezone of the responsibility unit which contains the work item, local to the employee that the work item is allocated to, 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_OPTIONS_INVALID (80)
SP_FRUID_INVALID (278)
SP_MAX_INVALID (281)
SP_TIMESTAMP_INVALID (504)

SP_MAX_INVALID (281) is returned if the supplied value of max is 0.