Versions Compared

Version Old Version 9 New Version Current
Changes made by

Jason Andrew

Jason Andrew

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Status
colourGreen
title5.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:

  1. one or more of the configured jeopardy conditions for that work item has changed;
  2. 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
  3. 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.

Info

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



Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

On this page:

Table of Contents
maxLevel2

Related pages:


Resource URL Summary

Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

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

PUT /up/v5/rest/scheduling/GetChangedWorkItems

Include Page
_Default HTTP Headers
_Default HTTP Headers

API Specifics


Panel
borderColor#D3D3D3

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

Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

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

Code Block
languagejs
titleGet Changed Work Items JSON
collapsetrue
{
    "FRU": "FRU Id",
    "OffsetId": "timeStampIn",
    "Options": {
        "JeopOnly": false
    }
}

GetChangedWorkItems Object Properties

PropertyTypeLengthDescriptionReq?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.

Code Block
languagejs
{
    "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.

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


Info
titlePlease 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:

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