Redline Burndown Gadget User Guide

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
      • For Time-Based burndowns, you can also select your preferred time unit (Days or Hours) for display. This affects how time values are shown in the chart and table. The system uses a standard conversion of 8 hours = 1 day.
    • JQL Query: Define the filter for the issues to include in the burndown.
    • Start Date: The date from which the chart should start.
    • End Date (Optional): Sets a minimum end date for the chart display. This is particularly useful when:
      • You want to ensure the chart extends to a specific future date (like a planned release date)
      • You’re using the Predict End Date feature and need to extend the chart beyond the automatic 50% extension limit
    • 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/Hours: 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. For time-based burndowns, the budget can be entered in either days or hours depending on your selected time unit, and will be automatically converted if you switch between units (using 8 hours = 1 day).
    • 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”.
    • Enable Debug Mode for Troubleshooting: This will log additional information to the browser console to help troubleshoot issues. Make sure to disable this when you’re done troubleshooting. Support may request that you enable this and provide some logging from the console.
    • Clear Cache: This will clear the cached data for the gadget. This is useful if you’ve made changes to the configuration and want to force the gadget to refresh the data. NOTE: the next refresh will create new cache.
  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.
  • Open JQL Query: Click on the filter icon to open your primary JQL query in Jira’s issue navigator in a new tab.
  • 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.
  • Time Unit Toggle: only for time-based burndowns switch between displaying time in days (8hrs/day) or hours using the time unit toggle button in the chart toolbar. This toggle affects only the display and doesn’t change your saved configuration.
  • Clear Cache: 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 Analyze Burndown Changes section:

  1. The table is minimized by default to provide more space for the chart.
  2. Click the “Show” button next to the “Analyze Burndown Changes” heading to expand the table.
  3. Click “Hide” to collapse the table when you’re done analyzing changes.
  4. Use the dropdown to select different burndown data sets.
  5. 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.
  6. Click on an issue key to open it in Jira.
  7. Download all series data as a CSV file by clicking on the download icon.
  8. Sort the table by clicking on column headers.
  9. Use the date filters to focus on specific time periods.
  10. 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”.
  • In the configuration panel, you can click on the JQL query field’s “Open in Jira” button to view the results of your query in Jira’s issue navigator.
  • For time-based burndowns, toggle between days and hours using the time unit button in the chart toolbar to view your data in the most appropriate unit.
  • Collapse the Analyze Burndown Changes table when you want to focus on the chart visualization.

7. Administrator Functions

Clearing the Site-Wide Cache

Jira administrators can clear the site-wide cache for the Red Line Burndown gadget, which affects all instances of the gadget across all dashboards:

  1. Navigate to the Jira Administration Settings page (gear in the top right corner).
  2. Go to Apps.
  3. Find the “Red Line Burndown” app in the list on the left sidebar and click on it.
  4. Click the “Clear Red Line Burndown Sitewide Cache” button.
  5. A confirmation message will appear at the bottom of the page when the cache clearing process is complete.

This operation:

  • Clears all cached burndown data across all dashboard gadget instances for all users
  • Forces a refresh of dashboard data on the next load of each gadget
  • Does NOT delete any user configuration data

Manually Running Weekly Cleanup Task

Administrators can also manually trigger the weekly cleanup task:

  1. Navigate to the Jira Administration Settings page (gear in the top right corner).
  2. Go to Apps.
  3. Find the “Red Line Burndown” app in the list on the left sidebar and click on it.
  4. Click the “Run Weekly Cleanup Task” button.
  5. This task removes unused data from the cache for burndowns that haven’t been accessed in 30 days and other transient per request data.
  6. The task runs automatically every week, but can be manually triggered if needed.
  7. This operation does NOT delete any user configuration data.
  8. The task runs in the background, and you may leave the page after initiating it.

8. 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.
  • If you’re experiencing issues with cached data, you can:
    • Clear the gadget instance cache using the trash icon in the chart toolbar.
    • For more persistent issues, contact your Jira administrator to clear the site-wide cache (see below).

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

10 Version History / Release Notes

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

v2.12 (June 14, 2025)

New Features:

  • End Date Configuration: Added optional End Date field to configuration panel. This allows you to set a minimum end date for the chart display, which is particularly useful when using the Predict End Date feature to extend the chart range beyond the automatic 50% extension limit.

Bug Fixes:

  • Time-based Burndowns ONLY: Fixed multiple minor issues affecting time-based calculations:
    • Fixed bug where remaining estimates could become negative during burndown calculations, ensuring values never go below zero
    • In rare instances, Jira’s API does not return the remainingEstimateSeconds field in the timetracking data for an issue. This would result in the ‘Analyze Burndown Changes’ feature showing 0 for the ‘Current Remaining Estimate’ column. This has been fixed by using our calculated remaining estimate value in these cases.
    • Fixed bug where time spent logged on the creation date was not included in the burndown calculations.
    • NOTE: If you are using time-based calculations, you should clear the site cache using these instructions.
  • Tooltip Improvements:
    • When in hours mode, fixed bug in chart tooltips shown when clicking on a row in the ‘Analyze Burndown Changes’ table showed values displayed in days instead of hours.
    • Add the ‘# of Days to Predict End Date’ to the Predicted End Date series tooltip.

v2.11 (May 28, 2025)

Bug Fixes:

  • Time-based Burndowns ONLY: Fixed bug where the remaining estimate computed by the burndown for a small subset of issues did not match the remaining estimate for Jira. In the prior versions, the original estimate was used to set the initial remaining estimate; however if the user changed the original estimate after initially setting it and did not update the remaining estimate to match, then the burndown would compute an inconsistent initial remaining estimate for the burndown — meaning the final remaining estimate for that issue may not match the current remaining estimate field’s value. This has been fixed by using the current remaining estimate as the initial remaining estimate and then adding the sum of the deltas (from the issue history) to the remaining estimate to get the original remaining estimate. This guarantees that the initial remaining estimate matches the current remaining estimate and preserves the integrity of the changelog especially when dealing with direct changes to the remaining estimate when, for example, scope increases or decreases and the time spent is not changed.
    • NOTE: If you are using time-based calculations, you should clear the site cache using these instructions.

v2.10 (May 25, 2025)

New Features

  • Time Unit Configuration: Added a new configuration option to select the time unit (days or hours) for time-based burndowns.
  • Added debug mode for troubleshooting. This can be enabled in the configuration page.

Bug Fixes

  • Fixed bugs in text colors for theming support that affected both light and dark mode

v2.9 (May 24, 2025)

New Features

  • Enhanced JQL Navigation:
    • On the burndown chart toolbar, added button to open primary JQL query results.
    • In the Configure page, added buttons to open JQL query results for the primary JQL query and each additional JQL query. NOTE: the additional JQL queries are ANDed with the primary JQL query to create a subset of issues for that Additional Burndown, which is exactly how the burndowns are calculated for these secondary data series.
  • UI Improvements: Analyze burndown changes table is now hidden by default to simplify the user interface. To expand it, hit the Show button next to the “Analyze Burndown Changes” heading. To collapse it, hit the Hide button.
  • Time Unit Toggle: In time-based burndowns, use the clock icon in the chart toolbar to switch the Y-axis between days and hours

Bug Fixes

  • Time-based mode only – Fixed issue where time-based changelog was being overwritten when
    • multiple change histories occurred on the same date, and
    • a subsequent issue did not have any change history that just had an original estimate without any history affecting the worklog.
    • NOTE: If you are using time-based calculations, you should clear the site cache using these instructions.
  • Story Point mode only – Fixed issue where the number of unestimated story points tasks was not being computed properly (checking against null instead of 0, as 0 is technically an estimate)

v2.8 (May 14, 2025)

Bug Fixes:

  • Fix error message

v2.7 (April 20, 2025)

Bug Fixes:

  • Upgrade forge libraries to address an error that was occassionally happening:
FetchError: request to https://stargate/forge/entities/graphql failed, reason: socket hang up
at ClientRequest.<anonymous> (webpack://jira-dashboard-gadget-custom-ui/node_modules/node-fetch/lib/index.mjs:1495:1)
at ClientRequest.emit (node:events:530:35)
at emitErrorEvent (node:_http_client:101:11)
at TLSSocket.socketCloseListener (node:_http_client:477:7)
at TLSSocket.emit (node:events:530:35)\n    at node:net:343:12
at TCP.done (node:_tls_wrap:648:7)

v2.6 (April 2, 2025)

Bug Fixes:

  • Move asApp calls to get status map into async processing
  • Fixed some frontend error handling & messages
  • Eliminate scroll bars on the Analyze Burndown Changes table

v2.5 (March 1, 2025)

Features:

  • 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

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

v2.4 (January 17, 2025)

Initial release