How to page in Rally WS API if TotalResultCount is above maximum limit of 2000

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

Whenever the TotalResultCount is above the maximum pagesize limit, which is currently set to 2000 in WS API, we need to page manually by specifying start parameter. Start parameter indicates index: the position of items in the collection.

A user hits this endpoint:

https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>/projects?&pagesize=2000&fetch=<OBJECT_OID>

gets TotalResults count above 2000. Only the first page of results is returned.

 

Resolution

Whenever the TotalResultCount is above the maximum pagesize limit, which is currently set to 200 in WSAPI, we need to page manually by specifying start parameter. Start parameter indicates index: the position of items in the collection. So if we want to go beyond item #200, we need to use start=201


https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>/projects?&pagesize=200&fetch=<OBJECT_OID>&start=201


To get to the third page start has to be updated:

https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>/projects?&pagesize=200&fetch=<OBJECT_OID>&start=402

Manual paging in a custom code is not necessary when using our API Toolkits.

Links to those toolkits are available on "For Developers" page in the Help in CA Agile Central REST API Toolkits section.
The same is true for? javascript AppSDK2.
The syntax is different for different toolkits/languages but the idea is the same:

• ?set limit to either Infinity (for those toolkits that allow it, e.g. AppSDK2) or to a number that is comfortably larger than the total result count you expect.
• ?there should be no reason to set pagesize. As long as the limit is set to the number greater than the maxpagesize allowed by WS API (200) the toolkits will page automatically with the pagesize 200.

Code examples with automatic paging where limit is set:
Java

QueryRequest defectRequest = new QueryRequest("Defect");
defectRequest.setLimit(10000);

C#

Request request = new Request("HierarchicalRequirement");
request.Limit = 10000;

Ruby

query.type = :testcase
query.limit = 10000

Manual paging in a custom code is necessary when CA Agile Central API Toolkits are not used.?
When hitting the endpoints directly, there is no automatic paging, and paging has to be done manually since there is no automatic paging built-in to WS API.

To verify the number of results returned by the endpoint you may also run a query directly in WS API interactive document.
Below is a screenshot illustrating the same example. Here a user selected "Project" in the Object Model on the left and then clicked on Query without supplying a Query String. This assumes that the user is logged in to Rally in another tab of the same browser window. Make sure that you are logged in to CA Agile Central to the same workspace (as the one you want to query) in another tab of the same browser window

A further comment on the need to issue a query in the context of the intended workspace: scroll down to the bottom of the Object Model on the left and click on Workspace object. Now click on "Query" button. WS API queries are scoped to a workspace, so you will get only one result, similar to the result shown below. Make sure that the Workspace name in the _refObjectName is the one that you are interested in:

{

• QueryResult:?{

  • _rallyAPIMajor:?"2",
  • _rallyAPIMinor:?"0",
  • Errors: [ ],
  • Warnings: [ ],
  • TotalResultCount:?1,
  • StartIndex:?1,
  • PageSize:?20,
  • Results:?[

    • {

      • _rallyAPIMajor:?"2",
      • _rallyAPIMinor:?"0",
      • _ref:?"https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>",
      • _refObjectUUID:?"<OBJECT_UUID>",
      • _refObjectName:?"NMDS",
      • _type:?"Workspace"

      }

    ]

  }

}