Versions Compared

Version Old Version 12 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.0.0

The Changed Items REST API provides an on-demand, pull-based mechanism for being notified when changes to Work Items occur, as a result of changes in integrated Sub-systems.  

That is, the API can be polled at appropriate intervals, to request the details of changes that have occurred to Work Items, since the last time the API was called.

Info

ServiceBroker also supports push-based notifications for informing integrated system of changes to Work Items. Push-based notifications can be enabled via a BNS object for the relevant tenant via the REST Tenant Configuration.



Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

On this page:

Table of Contents
maxLevel2

Related pages:


Resource URL Summary

Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

Retrieve the details of changed Work Items

GET /up/v5/bns/win?rowver=${rowver}&limit=${limit}

Include Page
_Default HTTP Headers
_Default HTTP Headers

API Specific Parameters

ParameterTypeRequired?Description

${rowver}

integer

>= 0

No

ServiceBroker keeps a record of all updates to Work Items that it is informed about, and assigns each update notification it receives a unique ${rowver} integer value, as a series of ascending integers.

In the context of the API, the ${rowver} value instructs the API to return data after the value specified.

Thus:

  • The first time the API is called, ${rowver} should be set to 0 to return the first collection of changed Work Items. The API result includes a new ${rowver} value to be used the next time the API is called.
  • Subsequent calls to the API should use the ${rowver} value from the previous API call, so that only new changes to Work Items will be seen.

This means that integrating systems which poll for changes to Work Items using the API will need to save the appropriate ${rowver} value to be used in the next call to the API.

If a ${rowver} value is not supplied, then the API will return the ${limit} most recent changed Work Items.

${limit}

integer

> 0

No

When supplied, ${limit} specifies the maximum number of changed Work Items to be returned by the API call.

If not supplied, the default value is 10.

${wid}stringNo(aka WorkItem Id) When supplied, only updates with the matching WorkItem.Id (e.g. Job Id) to be returned by the API call. 


Note

ServiceBroker will only store updates to Work Items for the number of days defined by the WorkItemNotifyTTL value for the relevant tenant configuration; after the configured number of days, the updates are automatically purged from ServiceBroker, and are no longer accessible via this API. See the REST Tenant Configuration for further details.



API Specifics


Panel
borderColor#D3D3D3

Retrieve the details of changed Work Items

This REST API will return the details of the Work Items that have changed since the last time the API was called, based on the rowver value (if supplied), up to limit Work Items (if supplied).

URL

Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

GET /up/v5/bns/win?rowver=${rowver}&limit=${limit}

HTTP Request Body

This request does not require a request body. 

HTTP Response

Success

On success, an HTTP response code of 200 will be returned, and the response body will contain a JSON object, consisting of:

  • A rowver field, containing the ${rowver} value to be used in the next call to the API.
  • A row field, containing an array of Work Item Notification Objects.

For example:

Include Page
_Changed Items API Response Object Format
_Changed Items API Response Object Format

Error

Include Page
_Default Response
_Default Response