On This Page:

Related Pages:

The sp:JeopReportRequest API method can be used to either:

obtain jobs and standard activities that are currently in jeopardy; or
a day by day breakdown of jobs and standard activities that were/are in jeopardy

either for one or more specific FRUs or teams, or for all FRUs/teams in the system.

Description

The sp:JeopReportRequest API method allows the the following to be obtained:

jobs and standard activities that are currently in breach of the customer’s rules (e.g. running late or breaking customer promise); or
a day by day breakdown of jobs and standard activities that either were (at the time), or currently are, in jeopardy.

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>`			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`). Examples include: `EST5EDT,M4.1.0,M10.5.0` `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>`
	`<allJeopardyStatus>?</allJeopardyStatus>`		`boolean`	If `true`, the day by day breakdown of jobs and standard activities that in jeopardy is returned, instead of the current snapshot view. (See the response body for more details.) Default value is `false`.
	`<startDate>?</startDate>`		`spDate`	The inclusive start date of the date range for which "in jeopardy" statistics should be returned. Required field when `allJeopardyStatus` is `true`.
	`<endDate>?</endDate>`		`spDate`	The inclusive end date of the date range for which "in jeopardy" statistics should be returned. Required field when `allJeopardyStatus` is `true`.
`</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>`							One or more `jobJeopardy` structures will be present, with each describing the details of a job or standard activity that is in jeopardy. The `jobJeopardy` structure is only returned when the `allJeopardyStatus` field in the API call is `false` (or not supplied). When `allJeopardyStatus` has been set to `true`, only the `jeopardyList` structure will be returned.
		`<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 is defined to be in the `OD(Early)` column of the Jeopardy Report on the Gantt.
		`<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>`					`TeamID`	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>`
	`<jeopardyList>`							One or more `jeopardyList` structures will be present, with each describing the day by day breakdown of jobs and standard activities in jeopardy, broken down by FRU, team, day, and jeopardy type. The `jeopardyList` structure is only returned when the `allJeopardyStatus` field in the API call is `true`. When `allJeopardyStatus` has been set to `false`, (or not supplied) only the `jobJeopardy` structure will be returned.
		`<FRU>?</FRU>`					`RUID`	The ID of the FRU to which the parent `jeopardyList` structure relates to.
		`<jeopardyListPerTeam>`						One or more `jeopardyListPerTeam` structures will be present, with each describing the statistics for the team in the FRU.
			`<teamId>?</teamId>`				`TeamID`	The ID of the team to which the parent `jeopardyListPerTeam` structure relates to.
			`<jeopardyListPerDay>`					One or more `jeopardyListPerDay` structures will be present, with each describing the statistics for the relevant date.
				`<date>?</date>`			`spDate`	The date for which the parent `JobStatPerDate` structure relates to.
				`<workItemList>`				One or more `workItemList` structures will be present, with each describing the statistics for the job or standard activity.
					`<workItem>`
						`<workItemID>?</workItemID>`	`WorkItemID`	The identifier of the job or standard activity in jeopardy. An unresourced `workItemID` is returned if: Unresourced Job Contract Latest ≥ Start Date AND Unresourced Job Contract Latest ≤ End Date
						`<jeopStates>?</jeopStates>`	`int`	A bitwise OR operation of all of the Jeopardy State 1 reasons which apply to the work item.
						`<jeopStates2>?</jeopStates2>`	`int`	A bitwise OR operation of all of the Jeopardy State 2 reasons which apply to the work item.
					`</workItem>`
				`</workItemList>`
			`</jeopardyListPerDay>`
		`</jeopardyListPerTeam>`
	`</jeopardyList>`
`</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_END_NOT_GE_START_DATE (19)
SP_OUTSIDE_HORIZON (53)
SP_START_DATE_INVALID (55)
SP_END_DATE_INVALID (56)
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)
SP_DATE_NOT_SUPPLIED (638)
SP_DUPLICATE_FRUID (811)
SP_NOT_ALL_FRU_RESPOND (813)
SP_DUPLICATE_TEAMID (814)