5.4.0

A pass-through API to ServiceScheduling (when configured) which allows the ServiceScheduling's "Get Changed Work Items" API to be called.

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.

In this context, the ServiceScheduling "Get Changed Work Items" API is the sp:GetChangedWorkItemsRequest API.

On this page:

Related pages:

Resource URL Summary

Pass Through Call to ServiceScheduling's "Get Changed Work Items" API

PUT /up/v5/rest/scheduling/GetChangedWorkItems

HTTP Headers

This API uses the standard ServiceBroker HTTP Headers.

API Specifics

Pass Through Call to ServiceScheduling's "Get Changed Work Items" API

This RESTified API will perform a pass-through call to the ServiceScheduling sub-system's "Get Changed Work Items" API (when configured).

URL

PUT /up/v5/rest/scheduling/GetChangedWorkItems

HTTP Request Body

This request requires a JSON object supplied in the HTTP request body, which defines the parameters that will be passed through to the ServiceScheduling "Get Changed Work Items" APi.

GetChangedWorkItems Object Format

Get Changed Work Items JSON

{
    "FRU": "FRU Id",
    "OffsetId": "timeStampIn",
    "Options": {
        "JeopOnly": false
    }
}

GetChangedWorkItems Object Properties

Property	Type	Length	Description	Req?	Mapping Field: Service Scheduling
`FRU`	`string`	SS: 8	Pass through parameter to the ServiceScheduling UpdateJobStartTime API.	Yes	`FRUID`
`OffsetId`	string		Pass through parameter to the ServiceScheduling UpdateJobStartTime API.	No	`timeStampIn`
`Options`	object		Pass through parameter to the ServiceScheduling UpdateJobStartTime API.	Yes	see GetChangedWorkItem Options Objects

HTTP Response

Success

On success, a JSON-formatted version of the ServiceScheduling "Get Changed Work Items" API response will be returned.

{
    "Success": true,
    "Code": "0",
    "Message": "",
    "Payload": {
        "result": {
            "type": "OK",
            "code": "0"
        },
        "OffsetId": "timeStampOut",
        "WorkItems": [
            {WorkItem CDM}
        ]
    }
}

Error

On error, a JSON-formatted version of the ServiceScheduling "Get Changed Work Items" API response will be returned.

{
    "Success": false,
    "Code": 9,
    "Payload": {
        "returnCode": {
            "type": "Error",
            "code": "SCH Error Code"
        }
    }
}

Please Note:

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 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 Cancel Job SOAP API will be calling the 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, and the ServiceScheduling Error codes, individual API calls from this API are:

Click here to expand...

SP_OK (0)
SP_OPTIONS_INVALID (80)
SP_FRUID_INVALID (278)
SP_MAX_INVALID (281)
SP_TIMESTAMP_INVALID (504)

ServiceBroker 5

GetChangedWorkItems RESTified API

Analytics