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.
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
In order to execute the query, submit an HTTP POST with the query as the body to query.v1.