Agile Central - Queries: Query Revisions in WS API

Document ID : KB000057612
Last Modified Date : 14/02/2018
Show Technical Document Details


A user wants to create a query that returns defects where State was changed from Open to Fixed.


We may start in the WS API interactive document to test a simple query on the Revision object using the Description field.
The Description field on Revision object captures the description of the change, and it is generated by CA Agile Central.
Since the Description is auto-generated, it is useful to try to make a change to an artifact in the UI and check the revision history for know what string is generated.
For example, any state change triggers creation of a new revision object with a Description that contains the words "STATE changed".
Notice the supported Query Expression Operators?? ?=, !=, >, <, >=, <=, contains, !contains.

In this example we start with a query string Description contains "STATE Changed" :

User-added image

Here is a fragment of the returned JSON:
User-added image

Notice the TotalResultCount. Since it exceeds max page size of 200 you we will need to page using start index in order to get to the results beyond the first 200. Since default page size is 20, both pagesize and start query parameters have to be used to go to the results on the second page, starting with element 201. Here is a query URL: contains "STATE Changed")&fetch=true&pagesize=200&start=201

To test the same query URL in your workspace, replace placeholder 12345 with a valid ObjectID of your workspace in /workspace/12345 query parameter.

In this example one of the returned revisions is related to a change in the ScheduleState, and not State. Even though we were interested in changes in State values, contains operator is broad enough to include both, and this may not be what we want.

If we are interested only in a particular type of state transition, e.g. from Open to Fixed, we can use a? more narrow query with equals operator: = "STATE changed from [Open] to [Fixed]")&fetch=true&pagesize=200

Here is a fragment of a returned JSON. Notice that now the TotalResultCount is much lower, 23:

User-added image

Per WS API object model, it is possible to traverse from an artifact (e.g. user story or defect) to a RevisionHistory and further to Revisions collection and individual revisions, but it is not possible to traverse the same path in the opposite direction. Artifact object in the WS API (from which stories and defects inherit) has an attribute RevisionHistory, but RevisionHistory or it's collection of revisions does not have a reference pointing back at the artifact they belong to. This has implications when writing custom code where Artifact data and attributes on revisions have to be stitched together.
Revision history in WS API has four attributes: Description, RevisionHistory(which is a reference to the parent RevisionHistory object), RevisionNumber and User(which is the author of the revision).
Neither Revision object, nor the RevisionHistory object that contains it has an attribute that points to the actual artifact (e.g. user story or defect) the revision belongs too.

Unfortunately the size of data when getting revision history can be very large and it is generally suggested to make more narrow calls when querying RevisionHistory. For example, you may limit the revisions indirectly by filtering artifacts for which RevisionHistory is fetched, or you may limit Revisions by CreationDate.
Please Update This Required Field