API Query for a Backlog

When I use the application user interface, I can select a project and see a backlog. I would like to export this information so I can review the backlog with my stakeholders. How can I get to a backlog through the API?

How?

This endpoint was introduced in 13.2, Summer 2013. Please view the About Digital.aiAgility information from the help icon in the menu bar to see if you are on this release or later.

The following uses the query.v1 endpoint to obtain backlog data. While there are other approaches, query.v1 is easy to write and returns JSON which is easy to parse.

Getting Started

• Have an HTTP Client.
• Obtain an API token.

from

The asset type for items in the backlog is PrimaryWorkitem. This supertype includes Story, Defect, and TestSet. So we use this asset type as the from parameter. This means the primary query is about PrimaryWorkitem assets.

from: PrimaryWorkitem

select

If our query only has a from parameter, we get a default set of attributes. This default set does not include the custom fields so we need to use select parameters to specify what we want. Most attribute definitions can be found by a query to meta.v1. To see the attributes available for PrimaryWorkitem, perform the following query.

<Server Base URI>/meta.v1/PrimaryWorkitem?xsl=api.xsl

The result will resemble the following, except with many more attributes.

PrimaryWorkitem derives from Workitem
* Name : Text
* Scope : Relation to Scope — reciprocal of Workitems
Description : LongText
Number: Text

Simple Attribute: Name and Number

We can use any of the attributes directly in the select. Let's add Name and Number. This also where we would include any custom fields that we want.

from: PrimaryWorkitem
select:
  - Name
  - Number

Complex Attribute: Project Name

We can also construct a complex attribute using the attribute definition syntax. The name of the parent project can be obtained with Scope.Name. Let's add that to the select.

from: PrimaryWorkitem
select:
  - Name
  - Number
  - Scope.Name

where

If our query does not have a where or filter parameter, the results will include every PrimaryWorkitem. Let's look at some options for reducing the result set.

note

where narrows which assets match, but it does not limit how many come back. A backlog for a large project is still a large result set. Use page as well. See page below.

Simple Match: Scope

We might want every PrimaryWorkitem where the Scope.Name is a specific project.

from: PrimaryWorkitem
select:
  - Name
  - Number
  - Scope.Name
where:
  Scope.Name: CallCenter

Tree Match: ParentAndUp

Alternatively, we might want every PrimaryWorkitem where the project or any of the parents match a specific project name. For example, you might want to see the full backlog for CallCenter, when it has items in subprojects for Release 1.0 and Release 2.0. The ParentAndUp attribute returns a collection of all the ancestors of the current asset. The following checks to see if any of those projects match on the Name attribute.

from: PrimaryWorkitem
select:
  - Name
  - Number
  - Scope.Name
where:
  ParentAndUp.Name: CallCenter

Page

Agility applies no default page size. A query with no page returns every asset that matched, however many that is, in a single response. On a mature instance a backlog export can run to tens of thousands of assets.

Always include a page parameter. It takes a named mapping of size and start:

from: PrimaryWorkitem
select:
  - Name
  - Number
  - Scope.Name
where:
  Scope.Name: CallCenter
page:
  size: 100
  start: 0

start counts assets to skip, so it advances by size per page rather than by one. To walk the whole backlog, request successive pages until you receive fewer results than size:

page: { size: 100, start: 0 }     ->  assets 1-100
page: { size: 100, start: 100 }   ->  assets 101-200
page: { size: 100, start: 200 }   ->  assets 201-300

Two parameters are worth adding alongside it:

• Add a sort so that paging is stable. Paging is applied after sorting. Without a sort, the underlying order is not guaranteed between requests, so assets can repeat or be skipped across page boundaries even though each individual response looks correct.
• Add needTotal: true so that you know how many pages to expect. Without it, the returned total is -1, which means "not computed" rather than "no results".

from: PrimaryWorkitem
select:
  - Name
  - Number
  - Scope.Name
where:
  Scope.Name: CallCenter
sort:
  - +Number
page:
  size: 100
  start: 0
needTotal: true

Selecting only the attributes you need matters for the same reason. Omitting select does not return a minimal asset: it returns a default attribute set for the type, on every asset in the result.

Execute the Query

To execute the query, submit an HTTP POST with the query as the body to query.v1.

Query Deleted Backlog Items

To include deleted backlog items in your query results, add the deleted parameter with a value of true:

from: PrimaryWorkitem
select:
  - Name
  - Number
  - Scope.Name
where:
  Scope.Name: CallCenter
page:
  size: 100
  start: 0
deleted: true

Or in JSON format:

{
  "from": "PrimaryWorkitem",
  "select": ["Name", "Number", "Scope.Name"],
  "where": {
    "Scope.Name": "CallCenter"
  },
  "page": { "size": 100, "start": 0 },
  "deleted": true
}

Without the deleted: true parameter, deleted assets are automatically excluded from query results. This provides a consistent method to retrieve deleted work items across all REST API endpoints.

Related concepts

Sample code