Query for burndown data
This topic explains the how to use the burndown data in a report in Agility.
What
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?
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 burndown data. While there are other approaches, query.v1 is the only approach that returns results efficiently in a single request.
Getting Started
- Have an HTTP Client.
- Obtain an API token.
from
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 from is Scope. This means the primary query is about Scope assets.
from: Scope
For a sprint burndown, the from is Timebox. This means the primary query is about Timebox assets.
from: Timebox
For the purpose of this example, we follow the Timebox burndown.
select
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 Name.
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 select.
from: Timebox
select:
- Name
- Workitems.ToDo.@Sum
where
If our query does not have a where or filter parameter, the results will include every Timebox. Let's look at some options for reducing the result set.
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 State.Code of 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.
asof
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.
view sourceprint
from: Timebox
select:
- Name
- Workitems.ToDo.@Sum
where:
State.Code: ACTV
asof: 2013-09-04
Multiple Queries
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.