5.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.

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.

On this page:

Related pages:

Resource URL Summary

Retrieve the details of changed Work Items

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

HTTP Headers

This API uses the standard ServiceBroker HTTP Headers.

API Specific Parameters

Parameter Type Required? 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} string No (aka WorkItem Id) When supplied, only updates with the matching WorkItem.Id (e.g. Job Id) to be returned by the API call.

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

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

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:

JSON Format

{
    "rowver": 12345,
    "rows": [
		{
			// Work Item Notification Object
		},
		{
			// Work Item Notification Object
		},
		...
    ]
}

Error

Otherwise, on error, the API will:

Return an HTTP response code of 400, if the request was invalid;
Return an HTTP response code of 401, if the request was not authorized; or
Return an HTTP response code of 500, if something else went wrong.

Both HTTP 400 and 500 responses will contain a REST Integration Standard Response Object with appropriate values for the Code and/or Message fields, describing the error, in the response body.

ServiceBroker 5

REST Notification Changed Items

Analytics