We ran out of Mice...

 

Query for burndown data

Last modified 09:54, 27 Mar 2014

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 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.

Getting Started

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 whereSince 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.

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.

 

Page statistics
4633 view(s) and 17 edit(s)
Social share
Share this page?

Tags

This page has no classifications.

Comments

You must to post a comment.

Attachments

 
Agile Made Easier