Visual Progress Tracker for Jira — Documentation

Complete Setup Guide

1. Overview

Visual Progress Tracker adds color-coded progress bars directly to your Jira issues. Choose from three field types to match how your team tracks work:

• Manual Progress Bar — Drag a slider to set any percentage (0–100%).
• Status-Based Progress — Automatically maps workflow statuses to percentages.
• Subtask Progress — Automatically calculates completion from resolved subtasks.

All three types display a colored bar that shifts from red to yellow to green as progress increases — giving your team instant, at-a-glance visibility.

2. Installation

3. Adding Progress Bar Fields

After installation, you need to add the progress bar fields to your Jira projects.

4. Field Type 1: Manual Progress Bar

The Manual Progress Bar lets users set the progress percentage by hand. This is ideal for tasks where completion is subjective or estimated.

How it Works

1. Open any Jira issue that has the manual progress bar field.
2. You will see a colored progress bar with a drag slider.
3. Drag the slider left or right to set the percentage (0–100%).
4. The value saves automatically.

Use Cases

• Design work, content creation, or other tasks with subjective milestones.
• Teams that want simple, quick progress tracking without automation.
• Combining with other estimation methods (story points, hours).

5. Field Type 2: Status-Based Progress

The Status Progress Bar automatically calculates a percentage based on the issue's current workflow status. You configure which status maps to which percentage.

How it Works

1. Open the Admin Settings page (Apps → Visual Progress Tracker).
2. In the Status Mapping section, you'll see your workflow statuses listed.
3. Assign a percentage to each status (e.g., "To Do" = 0%, "In Progress" = 50%, "Done" = 100%).
4. Click Save.
5. Now every issue with the Status progress bar field will automatically show the mapped percentage.

Use Cases

• Teams with well-defined workflows where status = progress.
• Sprint tracking — instantly see where every issue stands.
• Reporting dashboards that need automated, consistent data.

6. Field Type 3: Subtask Progress

The Subtask Progress Bar automatically calculates the percentage of resolved child issues (subtasks). No configuration needed — it works out of the box.

How it Works

1. Add the Subtask progress bar field to a parent issue that has subtasks.
2. The bar automatically shows: (resolved subtasks / total subtasks) × 100%.
3. When you open the issue, the bar recalculates automatically and shows the latest progress.

Example

A story has 4 subtasks. 2 are resolved, 2 are open → the bar shows 50% in yellow. When all 4 are done → 100% in green.

Expanding Subtask Details

Click the Details button on the issue view to expand a breakdown of all child issues, showing each one's individual progress and status. Click Hide to collapse.

Use Cases

• Epic or story tracking with subtask breakdowns.
• QA checklists — split testing tasks into subtasks and watch progress fill up.
• Onboarding or setup tasks with multiple steps.

7. Viewing Progress in List View

All three field types are visible as columns in Jira list view, giving you a project-wide overview of progress across all issues.

8. Admin Settings

Access the settings page from Apps → Visual Progress Tracker in the top navigation bar.

Color Thresholds

Customize when progress bars switch colors. Default values:

• Red — 0% to 33%
• Yellow — 34% to 66%
• Green — 67% to 100%

Adjust these thresholds to match your team's expectations. For example, set the green threshold to 80% if you only want bars to turn green near completion.

Status Mapping

Map each Jira workflow status to a percentage. This drives the Status-Based Progress field. Click Save after making changes.

Field Sync (Recalculate)

Use the Recalculate All Fields button to bulk-update all Status and Subtask progress fields across all projects. This is useful after changing status mappings or when first setting up the app.

To keep resource usage low, recalculation is limited to once every 7 days. When the button is on cooldown, the page shows the date when the next run will be available.

9. Dashboard Gadget

The Progress Tracker Overview dashboard gadget shows a table of all issues in a selected project with their progress values — perfect for team leads and stakeholders.

Refreshing the Data

Dashboard data is cached for up to 5 minutes to keep things fast. The gadget header shows how long ago the data was loaded (e.g. "5 min ago"). Click the Refresh button in the gadget header to fetch the latest data immediately.

10. What's Included

Every feature is available to all users — no feature gates, no upgrade prompts. Free for teams up to 10 users.

11. FAQ & Troubleshooting

The progress bar shows 0% even though the issue has a status mapped.

Click Recalculate All Fields in the Admin Settings to sync all fields. This is needed after you first set up status mappings or change them.

I only see the manual field type — where are the others?

Each field type must be added separately as a custom field. Go to Jira Settings → Issues → Custom fields → Create custom field and search for "Progress Bar" to see all three types.

Can I use multiple field types on the same issue?

Yes! You can add all three fields to the same issue. For example, use the Manual bar for overall progress and the Subtask bar to track child issue completion side-by-side.

Do progress bars update automatically?

Status and Subtask fields recalculate automatically every time you open an issue, so you always see the latest value. Manual fields only update when a user moves the slider.

The Status or Subtask field shows a number input during issue creation — can I edit it?

No — these fields are read-only during creation. They display "—" (Status) or "Auto-calculated after creation" (Subtasks) to indicate the value will be set automatically once the issue is saved. There is nothing to enter manually.

The Recalculate button is greyed out or shows a future date.

Recalculation is limited to once every 7 days to keep resource usage low. The admin page shows the exact date when the next run becomes available. Individual issue fields recalculate automatically every time you open them, so a manual recalculation is rarely needed.

I changed the color thresholds but the bars still show old colors.

Make sure you clicked Save in the Admin Settings. Then refresh the issue page. The new thresholds apply immediately to all fields.

The dashboard gadget shows data that seems out of date.

Dashboard data is cached for up to 5 minutes. Click the Refresh button in the gadget header to load the latest data immediately.

I added the field to a new project but existing issues show "—".

Status and Subtask fields calculate their values when you open an issue. Existing issues that haven't been viewed yet will show "—" until someone opens them. To immediately populate all issues, use the Recalculate All Fields button in Admin Settings.

Are progress values available for JQL search?

Yes. Every time someone opens an issue, the computed progress value is saved to Jira's database and becomes available for JQL queries, REST API, and list view columns. Issues that haven't been viewed since their last status change may show a slightly older value in JQL results.

Where is my data stored?

All configuration data is stored in Atlassian Forge Storage within your Jira Cloud instance. No data is sent to external servers. The app runs entirely on Atlassian infrastructure (Runs on Atlassian).

How do I uninstall?

Go to Jira Settings → Apps → Manage apps, find Visual Progress Tracker, and click Uninstall. This removes all app configuration data. Custom field values remain in Jira until you delete the custom fields.

12. Support