Skip to main content
System StatusContact Support
VersionOne Community

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 check Support Center -> About 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

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.

  • Was this article helpful?