Tuesday, July 15, 2014

Creating Burn Down Charts for Pivotal Tracker

This post will step through the process of using Just the Facts to subscribe to Pivotal Tracker project metrics and to graph those metrics in a burn down chart.

While Pivotal does have built-in charting capabilities, these canned charts have some limitations; for example, you can only chart a Burn Down for a single Release.

Begin by navigating to your Pivotal project page showing your list of current stories:
Viewing a Pivotal Project
Click the Just the Facts browser extension () in the browser toolbar to activate it.  You will be presented with a dialog to choose the facts you want to track for this project.
Subscribe to Pivotal Tracker Facts
In this case, we'll choose "Accepted and Total Points."  We'll also select "Unstarted Points" and "Started Points."   This will give us the basic information we'll need for a burndown chart.

After clicking "Subscribe,"  you'll be prompted to provide your API token.  This token allows Just the Facts to make secure calls to the Pivotal Tracker APIs on your behalf.
Provide Pivotal Tracker API Token
You can click the "Where is this?" link to view your settings page containing your token:
Pivotal Tracker Profile Page
Scroll down to reach the "API Token" section, copy the token value and paste it into the field on Just the Facts, then click "Subscribe to Pivotal Tracker".

This will create your fact subscriptions and display their current values:
Pivotal Tracker Fact Subscriptions
We now have all the raw facts we need.  However, for purposes of our burndown we actually want to chart the total count of unfinished story points, which is actually the sum of two of the facts - both the started and unstarted stories.

We will create a new, calculated fact for this story count.  Begin by selecting the "Started Story Points" and "Unstarted Story Points" facts, then clicking the Combine () button:
Creating a Combined Fact
 Since we are summing these two facts, we'll leave the dropdown with its default "Add to" value selected.  We'll name the new fact "Unfinished Story Points" and click the "Save" button to create it.
Naming a Combined Fact
We can then view our newly created fact in our dashboard:
Newly Created Combined Fact
There is actually one more calculated fact we'll need:  a count of the Finished Story Points, which we can obtain by subtracting the Unfinished Points we just created from the Total Points.

Begin by selecting "Total Story Points" and "Unfinished Story Points" and clicking Combine again:
Creating Another Combined Fact
This time, select the "Subtract" item from the drop down and name the new fact "Finished Story Points":
Combined Fact Using Subtraction
And now we can see both our newly created combined facts:
Both Combined Facts
As a side note, over time your dashboard will become more crowded with facts from multiple sources, combined facts, and so forth.  This is when the Filter drop down comes in; you can use it to filter the visible facts on a variety of dimensions, including not only the source of the fact but also metadata such as the project name:
The Filter Dropdown
There's one additional data point we'd like to include in our graph; a trendline of progress that shows when we are likely to be completed.  We create a trendline like any other Combined Fact.  First, we'll select the base fact, which in this case is the "Unfinished Story Points" count that we want to trend.  We'll then click the "Combine" button again:
Creating a Projected Fact
We'll choose the "Projection" radio button to indicate that we will project future values based on the present values.  We'll name this combined fact "Projected Remaining Story Points" then click "Save".
Naming a Projected Fact
Now we're ready to choose the facts we want to chart in our burn down.  The remaining screen shots will show several days worth of collected data to make it clearer exactly how our story point counts have changed over time.
We'll choose the facts to chart and click the Chart () button:

Selecting Cats to Chart
This will display a line graph with the past week's values for all four selected facts:
 Default Graph
We can then click the "Save" button to give the chart a title and easily view it any time in the future:
Title for New Chart
The chart will be created with default colors and appearance for each of its facts.  We can click on the Edit button ( ) to bring up a dialog to modify the chart details:

Edit Chart Details
In this case, we will assign specific colors, stack the finished and unfinished story counts one on top of the other, and display values for the unfinished story points, giving us a final chart that looks like this:
Formatted Burndown Chart
Note that the trendline automatically extends out to the future.  This allows us to use the date picker labeled "End Date" to go out in time another two weeks to see the projected completion date for the current stories:
Projected Burndown