I would like to consolidate burndown data into a reporting table so I can create a number of different burndowns in a single executive report. How can I get to burndown data 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 following uses the query.v1 endpoint to obtain burndown data. While there are other approaches, query.v1 is the only approach that returns results efficiently in a single request.
- Have an HTTP Client.
- Obtain an API token.
An agile team may use burndown reports in a number of ways. The team may produce a burndown to show progress on a project or releases. More commonly, the team uses a sprint burndown as a way to show progression as they complete work within the timebox. Each of these burndowns has a different
from parameter with a corresponding asset type.
For a project or release burndown, the
Scope. This means the primary query is about
For a sprint burndown, the
Timebox. This means the primary query is about
For the purpose of this example, we follow the
If our query only has a
from parameter, we get a default set of attributes. This default set does not include the burndown data 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
Timebox, perform the following query.
<Server Base URI>/meta.v1/Timebox?xsl=api.xsl
The result will resemble the following, except with many more attributes.
Timebox derives from BaseAsset * BeginDate : Date * EndDate : Date * Name : Text Description : LongText Schedule : Relation to Schedule — reciprocal of Timeboxes Actuals : Multi-Relation to Actual — reciprocal of Timebox Days : Numeric Duration : Duration Workitems : Multi-Relation to Workitem — reciprocal of Timebox
Simple Attribute: Name
We can use any of the attributes directly in the
select. Let's add
from: Timebox select: - Name
Complex Attribute: Burndown Data
We can also construct a complex attribute using the attribute definition syntax. The burndown data we want is taken from the
Workitems in the
Timebox. It is the sum of all the
ToDo values on the
Workitems. Let's add that to the
from: Timebox select: - Name - Workitems.ToDo.@Sum
Unique Match: ID
If we know the OID Token for a specific
Timebox, we can use it in the
where to make sure we get a single asset in the result set.
from: Timebox select: - Name - Workitems.ToDo.@Sum where: ID: 'Timebox:1566'
Simple Match: State
Alternatively, we might want multiple burndowns for every active
Timebox. We know the work is not burning down for future sprints and we know the work is down in closed sprints, so the only interesting sprints are active. Let's use the
ACTV in the
where. Since our goal is to consolidate multiple burndowns, we will use this for the rest of the example.
from: Timebox select: - Name - Workitems.ToDo.@Sum where: State.Code: ACTV
The effectiveness of this query depends on the discipline of the team to close timeboxes when they are complete. If the team skips review at the end of a timebox, then the system may have many active timeboxes that are no longer used by the team.
So far, our query only provides the data for right now. That won't be much good for burndown because we need to compare values from each day. We can use the
asof parameter to make an historical query that provides the results from a specific point in time.
from: Timebox select: - Name - Workitems.ToDo.@Sum where: State.Code: ACTV asof: 2013-09-04
So far, similar steps can be taken to consturct a query for rest-1.v1 or using the JSON format. However, this last step for multiple queries in a single request can only be done with YAML.
The above still only returns a single value, so we need to combine multiple queries in a single request.
from: Timebox select: - Name - Workitems.ToDo.@Sum where: State.Code: ACTV asof: 2013-09-03 --- from: Timebox select: - Name - Workitems.ToDo.@Sum where: State.Code: ACTV asof: 2013-09-04
In order to execute the query, submit an HTTP POST with the query as the body to query.v1.