On This Page:

Related Pages:

The sp:JeopReportRequest API method can be used to obtain jobs and standard activities that are jeopardy.

Description

The sp:JeopReportRequest API method allows a customer jobs and standard activities that are in breach of the customer’s rules (e.g. running late or breaking customer promise).

The API method returns a snapshot of the current set of work items (jobs and standard activities) in jeopardy for a given subset of scheduling units/teams at the time of the call.

Users of the API may want to only consider a work item in jeopardy when the clock time is past the appointment or contract latest for the work item concerned. (This allows systems integrating with the API to avoid informing customer that an appointment has been missed, when there is still a chance that its commitment could be made.) The options field in the sp:JeopReportRequest API method accept values which will enable jeopardy to be suppressed in these circumstances.

Jeopardy tolerances are taken into account when reporting jeopardy conditions through calls to sp:JeopReportRequest.

Order of Jobs Returned

Jobs will be returned in the following order:

Jobs are grouped by FRU (if more than 1 FRU or teams from more than 1 FRU specified);
Unresourced jobs for the FRU will be returned first; and
Resourced jobs are then grouped by team within the FRU.

Marked Jobs

It is possible for the Gantt user to mark the jobs as having been ‘dealt with’. This does not stop API calls being made for these jobs, and there is no indication on the API call made that the job has been marked.

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:JeopReportRequest>`
	`<FRUs>?</FRUs>`		`RUID`	A list of Final Responsibility Units (FRUs) for which work items in jeopardy are to be reported to the connected client. FRUs are separated by the ‘;’ character If `teams` (below) is empty and `FRUs` is empty then all FRUs (and teams) are reported. Either `FRUs` or `teams` can be specified, but not both.
	`<teams>?</teams>`			A list of teams for which work items in jeopardy are to be reported to the connected client. Teams are separated by the ‘;’ character. If `FRUs` (above) is empty and `teams` is empty then all teams (and FRUs) are reported. Either `teams` or `FRUs` can be specified, but not both. Since an unresourced job is not associated with a team, unresourced jobs will not be returned if a list of teams is supplied.
	`<APITimeZone>?</APITimeZone>`			Specifies the timezone which the times (`LatestAccess`, `ExpectedStart`, `ExpectedArrival`, `LatestEarliest` and `StateDue`) returned by `sp:JeopReportRequest` are to be local to. It must be a POSIX timezone string (in sp056), for example: EST5EDT,M4.1.0,M10.5.0 or IST-5.30 If not supplied, the database parameter `tz_jeop_api` will be used.
	`<statesToReport>`			See the "Jeopardy States" for the optional boolean values which can be passed in as part of the `statesToReport` structure. When one or more jeopardy states are set, the results of the call will be restricted to the subset of work items in jeopardy that match the conditions specified. When no jeopardy states are set, then no filtering is applied and all available work items in jeopardy will be returned. The `jeop_check_states` database parameter controls which types of jeopardy states are returned by the API. Only those Jeopardy States set via the `jeop_check_states` database parameter to be jeopardy states "in use" can ever be returned by the API, regardless of the value of the `StatesToReport` parameter passed into the API call.
			`JeopStates`
	`</statesToReport>`
	`<options>`			If any other options, other than those shown below, are specified, `SP_OPTIONS_INVALID (80)` will be returned.
		`<unresApptMissed>?</unresApptMissed>`	`boolean`	If true, an unresourced work item will only be reported as being in jeopardy if the Appointment Latest time has now passed.
		`<unresContractMissed>?</unresContractMissed>`	`boolean`	If true, an unresourced work item will only be reported as being in jeopardy if the Contract Latest time has now passed.
		`<apptMissed>?</apptMissed>`	`boolean`	If true, a resourced work item will only be reported as being in jeopardy if the Appointment Latest time has now passed.
		`<contractMissed>?</contractMissed>`	`boolean`	If true, a resourced work item will only be reported as being in jeopardy if the Contract Latest time has now passed.
	`</options>`
`</sp:JeopReportRequest>`

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:JeopReportResponse>`
	`<jobJeopardy>`
		`<workItemID>?</workItemID>`	`WorkItemID`	The identifier of the job or standard activity in jeopardy
		`<workItemType>?</workItemType>`		Identifies whether it is a job or activity that is being reported
		`<jeopStates>`
			`JeopStates`	The set of "Jeopardy States" that note the reason(s) for the job or standard activity being in jeopardy.
		`</jeopStates>`
		`<currEmpID>?</currEmpID>`	`EmpID`	The employee currently assigned to do the job or standard activity. Empty if a job and it is unresourced
		`<latestAccess>?</latestAccess>`		If a job and is not an appointment, this contains the latest date & time at which access is possible (if there is such thing – there may be an Access Hours pattern that has no end date) - for the job’s ETF if call-to-fix, otherwise its ETA. This corresponds to what’s in the ‘Latest Access’ control on the Gantt Job Details dialog and may be NULL if the job’s last Access Hours pattern has no end date. If the job is an appointment, it contains the Appointment Latest.
		`<expectedStart>?</expectedStart>`	`Time`	The time at which the employee is expected to start travelling to the work item. Empty if a job and is unresourced.
		`<expectedArrival>?</expectedArrival>`	`Time`	The time at which the employee is expected to start working on the work item. Empty if a job and is unresourced.
		`<latestEarliest>?</latestEarliest>`	`spDateTime`	If a job and is an appointment, `LatestEarliest` will contain the Appointment Latest date & time if the jeopardy condition is “Missed Appointment – Late” or the Appointment Earliest date & time if it’s “Missed Appointment – Early”. If the job isn’t an appointment, `LatestEarliest` will contain the Contract Latest date time if the job is “Overdue – Past Contract Latest” or the Contract Earliest date & time if it’s “Early – Before Contract Earliest”.
		`<overdue>?</overdue>`	`int`	The value (in minutes) of what defined to be in the “OD(Early)” column of the Jeopardy Report on the Gantt (see [2], ch 8 – “OD(Early) Column”).
		`<stateDue>?</stateDue>`	`Time`	For the late dispatch states (late earmarked etc.), the time at which the work item was due to enter the reported state e.g. for late earmarked, it’s the time at which the work item should have been earmarked. Empty if not in a late dispatch state.
		`<FRU>?</FRU>`	`RUID`	The FRU the work item is assigned to.
		`<team>?</team>`		The team of the allocated operative. Empty if a job and is unresourced.
		`<priority>?</priority>`	`int`	The work item's priority. Omitted if no value.
		`<importance>?</importance>`	`int`	The work item's importance. Omitted if no value.
	`</jobJeopardy>`
`</sp:JeopReportResponse>`

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_OPTIONS_INVALID (80)
SP_INVALID_TIME_ZONE_LOCATION (144)
SP_TEAMID_INVALID (200)
SP_FRUID_INVALID (278)
SP_FRUS_AND_TEAMS_BOTH_SUPPLIED (316)
SP_JEOPARDY_FINISHED (319)
SP_JEOPARDY_REPORT_INCOMPLETE (320)

ServiceScheduling 10

Integration ServiceOptimizer Jeopardy Report SOAP API

Analytics

Description

Order of Jobs Returned

Marked Jobs

Definition

Return Structure

Return Codes