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?
This endpoint was introduced in 13.2, Summer 2013. Please check Support Center -> About to see if you are on this release or later.
The asset type for items in the backlog is
PrimaryWorkitem. This supertype includes
TestSet. So we use this asset type as the
from parameter. This means the primary query is about
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
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
from: PrimaryWorkitem select: - Name - Number - Scope.Name
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
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.