Redline Burndown Gadget User Guide

Table of Contents

  1. Introduction
  2. Adding the Gadget to Your Dashboard
  3. Configuring the Gadget
  4. Understanding the Burndown Chart
  5. Using the Changelog Table
  6. Tips
  7. Troubleshooting

1. Introduction

The Redline Burndown Gadget is a powerful tool for tracking project progress and estimating completion dates. It provides a visual representation of work completed over time, helping teams to monitor their progress and identify potential delays or issues.

2. Adding the Gadget to Your Dashboard

  1. Navigate to your Jira dashboard.
  2. Click on “Add gadget” or “Edit dashboard” (depending on your Jira version).
  3. Search for “Crimsalytics Red Line Burndown” in the gadget directory.
  4. Click “Add” to add the gadget to your dashboard.

3. Configuring the Gadget

After adding the gadget, you’ll need to configure it:

  1. Click on the gear icon in the gadget header to open the configuration panel.
  2. Set the following required fields:
    • NOTE: Items in the Configuration pane with an “*” are required.
    • Burndown Type: Choose between “Story Points” or “Time-Based” burndown.
      • Story Points: Jira’s built-in Story Point field is actually a custom field with the name Story Points. This is used to track progress based on story point estimates. If necessary, you can override the default field by setting the name of the custom Story Point Field (e.g., “customfield_10041”). See below for further details on overriding this field. An error message will appear if the field is not found.
      • Time-Based: Uses Jira’s built-in time tracking fields (Original Estimate, Remaining Estimate, and Time Spent) to calculate progress.
      • When using Time-Based, you need to make sure that you either set the remaining estimate to the proper value (usually 0) when the status is changed to a “Done” state or you need to configure Jira to automatically set the remaining estimate to 0 when the status is changed to a “Done” state. Here’s a link to an Atlassian article on how to configure this: https://confluence.atlassian.com/jirakb/set-remaining-estimate-to-0-on-post-function-304579031.html
    • JQL Query: Define the filter for the issues to include in the burndown.
    • Start Date: The date from which the chart should start.
    • Chart Time Zone: Select the time zone for all date calculations and displays in the chart. Defaults to your browser’s time zone. The selected time zone is shown in the chart subtitle for clarity.
  3. Optional configurations:
    • Additional Burndown Charts: Add extra burndowns based on specific criteria. This feature allows you to create and compare multiple burndown charts within the same gadget. Each additional burndown can have its own JQL query, enabling you to track different subsets of issues or teams.To add an additional burndown:
      1. Click in the first empty row in the Additional Burndown Charts section.
      2. Provide a name for the new burndown (e.g., “Team A Burndown” or “High Priority Issues” or “Added Scope” or “Bugs”).
      3. Enter a JQL query to define which issues should be included in this burndown. NOTE: this filter will be ANDed with the primary JQL query to create a subset of issues for this burndown.
      4. The burndown will automatically pick a line style for the burndown to distinguish it from all the other burndowns.
      Benefits of using Additional Burndown Charts:
      • Compare progress across different teams or components of your project.
      • Track high-priority issues separately from the overall project burndown.
      • Analyze how different categories of issues (e.g., bugs vs. features) are progressing.
      • Create a burndown for a specific epic or feature set within a larger project to understand how that’s contributing to the overall project.
      You can add up to 5 additional burndowns, allowing for comprehensive tracking and comparison of various aspects of your project.
    • Plan Anchor Date: Set a date to anchor your plan (date when your plan will be set or is set). This date is used to determine “The Red Line” (Resource Model burndown line).
    • Budget in Story Points or Days: The total budget for the project, which is used for planning purposes when trying to determine which issues to include in the burndown’s scope.
    • Discovered Work %: The percentage of additional work expected to be discovered during the burndown’s scope. The Resource Model is anchored at the Plan Anchor Date and then shifted up/down by this percentage.
    • The Utilization Error %: The expected percentage of error in resource utilization estimates, which is used to draw error bars around the resource model and is determined based on the Primary Burndown on the Plan Anchor Date. These error bars are anchored on the Plan Anchor date.
    • Days to Predict End Date: The number of days to predict the end date based on current progress. The prediction is only completed for the Primary Burndown and uses a least squares fit method to predict the end date.
    • Resource Model: Define available resources over time. The Resource Model allows you to specify how your team’s capacity changes throughout the project, which helps in creating more accurate burndown projections. The model differs slightly depending on whether you’re using a time-based or story point-based burndown.Story Point-Based Burndowns:
      • Resources are defined in terms of the number of FTEs and their velocity (story points per week).
      • For each entry in the Resource Model, you specify:
        1. Start Date: When this resource allocation begins.
        2. Number of Resources: The number of FTEs working on the project.
        3. Weekly Velocity: The number of story points this team can complete per week.
      • Example: “From August 15, we have 5 FTEs with a velocity of 30 story points per week”
      Time-Based Burndowns:
      • Resources are defined in terms of Full-Time Equivalents (FTEs) and their utilization rate.
      • For each entry in the Resource Model, you specify:
        1. Start Date: When this resource allocation begins.
        2. Number of Resources: The number of FTEs working on the project.
        3. Utilization Rate: The percentage of time these resources are dedicated to the project (e.g., 80% if they’re also working on other projects). NOTE: our experience suggests that 60% is a good utilization rate assumption.
      • Example: “From July 1, we have 3 FTEs at 80% utilization”
      In both cases, you can add multiple entries to reflect changes in your team’s capacity over time. This could include:
      • Team members joining or leaving the project
      • Changes in team velocity as they become more familiar with the project
      • Planned time off or reduced capacity during holidays
      The Resource Model is used to calculate the ideal burndown line — aka “The Red Line” — helping you visualize whether your project is on track based on your team’s capacity.
    • Story Point Field (to override the Story Points field and only applicable to Story Points burndowns): The custom field ID for story points (e.g., “customfield_10041”) and it’s highly likely that your Story Point field has a different custom field ID. To find the custom field ID, go to Settings->Issues->Custom Fields and find the field with the name Story Points, then click on the field. In the dialog that appears, click Edit details. The custom field ID is the last number in the URL formatted as a number — e.g., 10041. When overriding the field, the field name must be formatted as a string — e.g., “customfield_10041”.
  4. Click “Save” to apply your configuration.

4. Understanding the Burndown Chart

The burndown chart displays:

  • Primary Burndown (green lines): The burndown of the remaining story points or effort based on your Primary JQL query.
  • Additional Burndowns (dashed green lines): If you’ve added additional burndowns, they’ll appear as dashed lines.
  • Story Points Complete or Time Spent depending on Burndown Type (blue lines): The story points completed or time spent on issues based on your Primary JQL query.
  • Estimate Accuracy (yellow lines): The accuracy of your initial estimates over time and is tracked starting at the Plan Anchor date.
    • For Story Points, this is any increase in the story points after the Plan Anchor date.
    • For Time-Based, this is the sum of the remaining estimate (green burndowns) and the time spent (blue burndowns). The way to think about this is that if this line is has an increasing slope, that means the project’s scope is increasing at a faster rate than the time spent, which means work is being discovered or scope is being added to the project. And the opposite holds as well — if the line is decreasing, the project’s scope is decreasing at a faster rate than the time spent.
  • Resource Model: The ideal progress based on your resource model. When your Primary Burndown is not tracking to “The Red Line” (Resource Model), your project is likely off track.
  • Plan Anchor: date when the plan is set or will be set. This date is used to determine “The Red Line” (Resource Model burndown line) and is labeled with the text “Plan Anchor”. The “Max Scope” line is also labeled, which is the maximum scope of the project based on the Resource Model and discovered work percentage.

Key features:

  • Hover over data points to see detailed information.
  • Use the zoom and pan features to focus on specific date ranges.
    • Zoom on the chart by clicking and dragging. The zoom will only occur in the x-axis.
    • To zoom the Y axis, move your mouse over the Y axis labels and scroll the mouse wheel.
  • The “Reset Zoom” button returns the chart to its full date range.
  • To pan the chart, hold down the CTRL (or CMD on Macs) key and click and drag the mouse.
  • Show/hide all buttons to toggle the visibility of all data sets.
  • Download the chart as a PNG image by clicking on the picture icon.
  • Download all series data as a CSV file by clicking on the download icon.
  • Beta only feature: Clear the data cached in Atlassian’s cloud for this specific dashboard gadget’s instance, which is shared by all users for this instance of the gadget. An instance is defined as a specific gadget on a specific dashboard. NOTE: the next refresh will create new cache.

5. Using the Changelog Table

Below the chart, you’ll find the Changelog Table:

  1. Use the dropdown to select different burndown data sets.
  2. The table shows changes in story points or time estimates for each issue. NOTE: these are the aggregate changes on that date for each issue.
  3. Click on an issue key to open it in Jira.
  4. Download all series data as a CSV file by clicking on the download icon.
  5. Sort the table by clicking on column headers.
  6. Use the date filters to focus on specific time periods.
  7. Click the synchronize filter button to update the table’s date range filter to match the chart’s current x-axis view.

6. Tips

  • Change the name of the gadget by clicking on the text Red Line Burndown at the top of the gadget’s display. This can be used as a chart title to explain the data presented in the chart.
  • Once the burndown is configured the way you want, you can easily duplicate the configuration by clicking on the 3 dots in the upper right hand corner of the gadget and then clicking on “Duplicate”.

7. Troubleshooting

  • If the chart doesn’t load, check your JQL query and ensure it returns results.
  • For performance issues, try narrowing your date range or simplifying your JQL query.
  • If data seems incorrect, verify your story point field and start date in the configuration.
  • Please contact us via our support page if you frequently see the message. Internal Atlassian Jira Storage Rate Limit exceeded. Automatically throttling usage on the backend. Please wait. NOTE: refreshing will make the issue worse. If this is happening frequently, please contact Crimsalytics support.

8. Support

If you encounter any issues, we may ask you to share the gadget’s configuration with a screenshot. Additionally we may ask you to check your webbrowser’s console for any errors.

For additional support, please contact your Jira administrator or Crimsalytics for support for The Red Line Burndown Gadget support team.

9. Version History

Atlassian controls the version numbers. Our first release was version 2.4.

v2.5 (March 1, 2025)

  • Bug Fixes
    • Simplified and improved story points completed calculation (blue series) including only taking credit for completed points when the status changes to done. If the status moves back out of a done status, those points are removed from the points spent (blue series).
    • Enhanced weekly velocity tooltip (purple series) to show 0.1 increment support
    • Fixed CSV changelog export
  • Admin & Maintenance
    • Replaced App Configure page with Settings->Apps->sidebar admin page (Crimsalytics Red Line Burndown Admin)
      • Added button to run weekly maintenance tasks
      • Added button to clear site-wide cache
    • Implemented automatic weekly scheduled Forge Storage cleanup task
  • Infrastructure
    • Improved mechanism for writing larger blocks of data to Forge Storage for caching burndown results with improved strategy for rate limits
    • Improved cache clearing

v2.4 (January 17, 2025)

Initial release