Flow Metrics Reports and Insights - User Guide

Use your browser's on-page find, or scroll, to navigate the sections of this guide: Introduction, What is Flow Metrics?, Installation, Getting Started, Dashboard Gadgets, Dashboard Overview, Metrics Explained, Configuring Your Data Source, Chart Types and Visualizations, Workflow Configuration, Advanced Features, Exporting Data, Performance Optimization, Troubleshooting, Frequently Asked Questions, and Best Practices.

Introduction

Flow Metrics Charts for Jira Cloud is an Atlassian Forge application designed to help teams visualize and analyze their workflow performance. By tracking key metrics like lead time, cycle time, and throughput, teams can identify bottlenecks, improve predictability, and optimize their delivery process.

Key Benefits

• Data-Driven Decision Making: Make informed decisions based on real metrics from your Jira workflow

• Identify Bottlenecks: Quickly spot where work is getting stuck in your process

• Improve Predictability: Understand your team's capacity and delivery patterns

• Visual Analytics: Beautiful, interactive charts that make complex data easy to understand

• Flexible Configuration: Works with any workflow, issue type, or project structure

• High Performance: Optimized to handle 10,000+ issues without slowdowns

Who Should Use This App?

• Scrum Masters & Agile Coaches: Monitor team velocity and identify process improvements

• Project Managers: Track project health and provide data-driven status updates

• Development Teams: Understand your workflow and optimize delivery

• Product Owners: Gain insights into feature delivery timelines

• Executive Leadership: Get high-level visibility into team performance

What is Flow Metrics?

Flow metrics are measurements that help teams understand how work moves through their system. Unlike traditional metrics that focus on outputs (like story points completed), flow metrics focus on outcomes and the efficiency of your process.

Core Flow Metrics

Lead Time

Definition: The total time from when work is requested (issue created) until it's completed (issue resolved) or the current time for in-progress work.

What it measures: The complete customer experience - how long someone waits from requesting a feature to receiving it. For in-progress issues, it shows how long work has been aging in the system.

Why it matters: Shorter lead times mean faster value delivery to customers. Consistent lead times improve predictability. Tracking in-progress lead time helps identify work that's been stuck too long.

Example:

• A resolved story: Created January 1st, resolved January 15th → Lead time = 14 days

• An in-progress story: Created January 1st, still open today (January 20th) → Lead time = 19 days (aging)

Cycle Time

Definition: The time work spends in active development (from "in progress" to "done").

What it measures: How long it actually takes your team to do the work, excluding wait time.

Why it matters: Helps identify process inefficiencies and blockers. Lower cycle time means your team is working more efficiently.

Example: A story enters "In Progress" on January 5th and moves to "Done" on January 12th. Cycle time = 7 days.

How it's calculated:

• Only completed issues (statusCategory = "done") are included in cycle time calculations

• Cycle time measures time spent in "indeterminate" statusCategory (in-progress statuses)

• The app automatically detects status transitions from your issue changelogs

• Issues without proper status transitions will not show cycle time data (to avoid showing "0")

Throughput

Definition: The number of work items completed in a given time period (typically per week or month).

What it measures: Your team's delivery capacity and pace.

Why it matters: Helps with capacity planning and forecasting. Consistent throughput indicates a stable, predictable process.

Example: Your team completes 15 stories in Week 1, 18 in Week 2, and 16 in Week 3. Average throughput = 16.3 stories/week.

Work Distribution

Definition: The breakdown of work types (e.g., features, bugs, technical debt, Stories, Enablers, Maintenance) completed over time.

What it measures: Where your team's capacity is being allocated across different types of work.

Why it matters: Ensures balanced investment across different work types and prevents technical debt accumulation.

Work distribution can be displayed as percentages for each time period, mapped from Jira labels/components to custom categories, measured by issue count or story points, and viewed by day, week, or month.

System Stability (Process Predictability)

Definition: Measures the consistency and reliability of your team's delivery process by tracking throughput variance over time using a 3-month rolling calculation.

What it measures: How predictable and stable your team's output is. Lower variance indicates higher process stability and predictability.

How it works: The app calculates completed issues per month for the past 12 months, then for each month (starting from month 3) computes a 3-month rolling variance (coefficient of variation = standard deviation ÷ average), displayed as a line chart.

Interpretation:

• Low Variance (<15%): High stability - process is predictable and consistent

• Moderate Variance (15-30%): Some predictability with occasional variation

• High Variance (>30%): Low stability - process is unpredictable, investigate causes

Coming Soon

The following metrics are currently in development and will be added in a future release: Flow Load (Cumulative Flow Diagram), Time in Status, and Planning Accuracy.

Installation

Prerequisites

• Jira Cloud instance with administrator access

• Jira Software, Jira Service Management, or Jira Core (all supported)

• Valid Atlassian account

Installation Steps

1. Navigate to Atlassian Marketplace: In your Jira instance, click Apps → Find new apps, and search for "Flow Metrics Charts for Jira Cloud".

2. Install the App: Click Try it free or Buy now, review the permissions requested, and click Get it now to confirm.

3. Verify Installation: Go to any Jira project and look for Flow Metrics in the left sidebar. If visible, installation is successful.

Required Permissions

The app requires read access to project data, board data, issue details, and filters, plus app storage to save your configuration preferences. The app operates in read-only mode and does not modify any Jira data.

Getting Started

Accessing Flow Metrics

Open any Jira project and click Flow Metrics in the left sidebar. On first use the app automatically detects your project and displays default metrics based on all issues in the project. You can customize the data source and metrics (see Configuring Your Data Source).

Quick Overview Tour

When you first open Flow Metrics, you'll see a metric selector (tabs to switch between metrics, with tooltips explaining each), a data source selector, the main chart area, a statistics panel (min, max, average), and action buttons to export data, configure charts, and analyze breakdowns.

Your First Analysis

1. Select the Lead Time metric (usually selected by default).

2. Review the chart — each bar represents average lead time for a time period.

3. Check the statistics (min, max, average).

4. Identify trends — are lead times increasing, decreasing, or stable?

Dashboard Gadgets

Overview

Flow Metrics Charts provides dedicated dashboard gadgets, one for each available metric type. Each gadget can be configured independently with its own data source, allowing you to display multiple metrics side-by-side on your Jira dashboard.

Available Gadgets

1. Lead Time Gadget - Track time from issue creation to completion

2. Cycle Time Gadget - Measure time spent in active development

3. Throughput Gadget - Monitor issues completed per time period

4. Work Distribution Gadget - Visualize distribution of work types (always a stacked bar chart)

5. System Stability Gadget - Track process predictability through throughput variance

Coming Soon: Flow Load (Cumulative Flow Diagram), Time in Status, and Planning Accuracy gadgets are in development.

Adding Gadgets to a Dashboard

1. Go to any Jira dashboard and click Add gadget.

2. Search for "Flow Metrics", select the specific metric gadget you want, and click Add.

3. Click Configure on the gadget, select a data source type (Project, Saved Filter, Board, or Custom JQL), choose the specific source, and click Save.

4. The gadget loads and displays metrics for your selected source, refreshing automatically.

Multiple Instances

You can add multiple instances of the same gadget type with different data sources — for example, comparing lead time across three projects, or tracking throughput for two teams. Each gadget instance has independent configuration; changes to one don't affect others.

Dashboard Gadget vs Project Page

Dashboard gadgets can be configured with any data source, allow multiple instances, show a single focused metric each, refresh automatically, and export CSV. The project page auto-detects the current project, offers full interactivity (metric switching, breakdowns, exports) and advanced configuration, but shows only the current project.

Dashboard Overview

The main interface includes a metric selection bar (Lead Time, Cycle Time, Throughput, System Stability, Work Distribution), a data source configuration button, the chart display area, a statistics panel (minimum, maximum, average), an action toolbar (Export CSV, Breakdown Analysis, Chart Configuration, Workflow Configuration), and an authentication mode toggle.

Authentication Mode Toggle

Switch between As App (uses app permissions, default, faster — cached separately) and As User (uses your personal permissions, sees only what you can see — cached separately). Each mode caches its data separately, so you can compare what is accessible with different permissions.

Metrics Explained

Understanding Metric Units

Time-based metrics (Lead Time, Cycle Time) are measured in days; count-based metrics (Throughput, Work Distribution) are measured in issues. Units appear in the statistics boxes, below each chart, in gadget displays, and in detailed data tables.

Lead Time Analysis

Use lead time to understand the complete customer experience from request to delivery. The X-axis shows time periods, the Y-axis shows average lead time in days. Increasing lead time suggests growing complexity or bottlenecks; high variability suggests some issues take much longer; stable and low is the optimal state.

Cycle Time Analysis

Use cycle time to understand actual work efficiency, excluding wait time. Configure which statuses count as "in progress" via Configure Workflow. Long cycle time with short lead time means work waits before starting; cycle time ≈ lead time means work starts immediately when requested.

Throughput Analysis

Use throughput for capacity planning and forecasting. To forecast: calculate average throughput over recent periods, count items in your backlog, and divide backlog size by average throughput. For example, 100 backlog items ÷ 20 items/week = 5 weeks.

Work Distribution Analysis

Use work distribution to understand where team capacity is allocated. Colors/segments represent different work types. Too many bugs may signal quality issues; too little technical-debt work means debt is accumulating; a balanced distribution indicates a healthy mix.

Configuring Your Data Source

The app supports five data source types: Project (default), Board, Filter, User (assignee or reporter), and Custom JQL.

Authentication Mode in Data Source Configuration

When you open Configure Data Source, an Authentication Mode toggle lets you choose App Auth (application-level permissions, default) or User Auth (your personal permissions). The available projects, boards, and filters reload to reflect the selected mode. When you save with a different mode, the app reloads metrics with fresh data using the new permission context.

Project Source (Default)

Analyzes all issues in the current project. Best for analyzing entire project performance. Configure: open Configure Data Source, select Project, choose a project, and click Save.

Board Source

Analyzes issues visible on a specific Jira board. Best for team board or sprint analysis. Only boards you have permission to view will appear.

Filter Source

Analyzes issues matching a saved Jira filter. Best for complex filtering, reuse, or cross-project analysis. Create filters in Jira first (Issues → View all filters → Create filter), then select them in Flow Metrics.

User Source

Analyzes issues assigned to or reported by a specific user. Choose Assignee (work they're responsible for) or Reporter (work they requested).

Custom JQL Source

Analyzes issues matching a custom JQL query. Enter your query, click Validate JQL to check syntax, then Save. Example queries:

JQL resources: JQL Official Documentation and JQL Functions Reference.

Chart Types and Visualizations

To customize how data is displayed, click Configure Chart, select a chart type, optionally customize colors, and click Save.

Available Chart Types

• Bar Chart — best for lead time, cycle time, and throughput by period; the default for most time-series metrics.

• Line Chart — best for throughput trends and velocity over time, when trend direction matters more than absolute values.

• Stacked Bar Chart — best for flow distribution and work-type breakdown. Automatically selected and locked for Work Distribution to ensure accurate visualization.

• Stacked Column Chart — an alternative view of flow distribution, good for many categories.

• Cumulative Flow Chart — best for flow load (CFD) and WIP analysis.

For supported metrics you can customize series colors via Configure Chart. The default palette uses Atlassian's color scheme.

Workflow Configuration

For cycle time metrics, you need to define workflow boundaries so the app knows which stages count as "in progress" versus "done".

Configuring Workflow Boundaries

Click Configure Workflow. The app loads all statuses used in your selected data source. Define Start Statuses (e.g., "In Progress", "In Development", "In Review") and End Statuses (e.g., "Done", "Closed", "Released"). Multiple statuses can be selected for each.

Example Workflow Configurations

Best Practices

Be consistent across time periods for meaningful comparisons, exclude waiting states, include all active work (code review, testing), document your configuration, and review it regularly as your workflow evolves.

Configuring Work Distribution

Work Distribution shows how your team's capacity is allocated across different work types, and is always displayed as a 100% stacked bar chart. Select Work Distribution from the metrics menu, then click Configure Work Types (only visible for this metric).

Configuration Options

• Measurement Type: Issue count (default) or story points.

• Time Period: Daily, weekly, or monthly (default).

• Display Format: Always shown as a percentage (0–100%) for stacked visualization.

• Issue Type Selection: Filter which issue types to include (default: all).

• Label Selection: Filter which labels to include; issues with at least one selected label are included (default: all). The UI shows the first 20 labels but all are used for filtering.

• Work Type Mapping: Map labels/components to custom categories, one mapping per line as label=WorkType.

Example mapping:

When both issue types and labels are selected, issues are filtered by issue type first, then by labels (must have at least one selected label). Issues without a matching label go into an "Other" category; when no mappings are configured, issues are grouped by issue type.

Advanced Features

Time Granularity Selection

All charts and gadgets support configurable time granularity, letting you view metrics at different time scales.

Available Granularity Options

• Auto — automatically selects the best granularity based on your data span (hour for ≤2 days, days for 3–7 days, weeks for 8–60 days, months for >60 days).

• Hours — bucketed by hour. Best for short-term analysis, incident response, same-day tracking.

• Days — bucketed by day. Best for weekly sprints and daily standup metrics.

• Weeks — bucketed by ISO week. Best for sprint analysis and monthly planning.

• Months — bucketed by month. Best for quarterly reviews and long-term trends.

How to Change Granularity

In dashboard gadgets and on the project page, use the Granularity selector above the chart and click your preferred option (Auto/Hours/Days/Weeks/Months). The chart updates without a page refresh. Granularity is supported for Lead Time, Cycle Time, Throughput, System Stability, and Work Distribution. (Flow Load, Time in Status, and Planning Accuracy are coming soon.)

AI-Powered Insights (Rovo Integration)

Flow Metrics Charts integrates with Atlassian Rovo to provide automatic intelligent analysis of your metrics. When Rovo is enabled in your Jira instance, the app activates AI analysis each time metrics data loads, highlighting trends, anomalies, and noteworthy patterns, and suggesting actionable improvements. Rovo must be enabled on your Jira Cloud instance (contact your Jira administrator); no manual setup is needed.

Breakdown Analysis

Breakdown analysis segments your metrics by attribute: No Breakdown (default), By Epic, By Version, or By Label. Select a metric, click a breakdown button, and the chart updates to a consolidated bar chart showing all groups side-by-side (up to 10 in the chart view), with a detailed statistics section below listing all groups. Click "View Issues →" on any group to drill down into individual issues.

Multi-Project Analysis

Analyze multiple projects simultaneously by creating a Jira filter spanning several projects, or by entering multi-project Custom JQL such as:

Jira Service Management (JSM) Support

The app fully supports JSM projects, including service desk issue types, JSM-specific statuses, and SLA tracking integration. When configuring cycle time for JSM, include statuses like "Waiting for support", "In Progress", and "Escalated", and exclude "Waiting for customer" (not in your control).

Auto-Granularity Detection

When you select Auto granularity, the app analyzes your date range and chooses month granularity for multi-year or long single-year ranges (>60 days), week granularity for medium ranges (8–60 days), or day granularity for short ranges (≤7 days). Auto-granularity applies to throughput; lead time and cycle time are always grouped by month. You can override it by selecting a specific granularity.

Exporting Data

CSV Export

Export your metrics data for external analysis, reporting, or archival. From the project page or a dashboard gadget, configure your data source, select a metric and granularity, wait for it to load, and click Export CSV. The file downloads automatically and matches the granularity you selected.

Example export formats:

Exported data is useful for executive reporting, advanced analysis in tools like Excel or BI platforms, compliance and auditing, and custom dashboards.

Performance Optimization

Jira Expressions API

The app uses the Jira Expressions API to perform calculations server-side, which reduces data transfer dramatically, speeds up metric calculations, and handles 10,000+ issues without slowdown. If the API is unavailable (rare), the app automatically falls back to traditional methods without user intervention.

Performance Tips

Start with specific data sources (board, filter) rather than an entire project; use JQL to limit date ranges for historical analysis; leverage caching (the app caches recently computed metrics, so switching between metrics is fast); and narrow your data source if loading is consistently slow.

Scaling Limits

The app is tested for standard use (up to 2,000 issues, instant loading), large projects (2,000–10,000 issues, 5–15 second initial load), and enterprise scale (10,000+ issues, 15–30 second initial load). For projects with more than 3,000 issues, the app fetches the 3,000 most recently resolved issues and displays them in chronological order, ensuring you see recent trends. To analyze older data, use JQL filters with custom date ranges.

Troubleshooting

"No data available" message

When the app finds issues but cannot calculate metrics, it displays diagnostic information explaining why — for example, how many issues were found, how many had valid data, the specific reasons issues were excluded (unresolved, missing fields, outside date range), and suggested alternative metrics or actions.

Common scenarios:

• Lead Time — No resolved issues: Issues lack resolution dates. Wait for issues to complete, or use Throughput instead.

• Cycle Time — No workflow history: Issues lack changelog data or workflow transitions. Configure workflow steps and confirm issues have moved through statuses, or use Lead Time.

• Throughput — Issues outside date range: All resolved issues fall outside the selected range. Expand the date range or filter for more recent issues.

If diagnostic messages don't resolve your issue, verify in Jira that issues have the required fields (resolution date, workflow history), try a different metric, or contact support@divim.io.

Charts not loading or showing errors

Possible causes include network connectivity issues, temporary Jira API unavailability, browser compatibility, or permission issues with the selected data source. Try refreshing the page, using a supported browser (Chrome, Firefox, Edge), verifying you have permission to access the data source, and contacting your Jira administrator if permission issues persist.

Slow performance

For very large data sources, complex JQL, or high latency: narrow your data source using filters or date ranges, prefer project or board sources over custom JQL where possible, wait for the initial load to complete (subsequent loads are cached), and try "As App" authentication mode for better performance.

Incorrect cycle time calculations

Cycle time only calculates for completed issues (statusCategory = "done") that have proper status transitions in their changelog. Verify you have completed issues, review and update your workflow configuration to match your actual workflow, and confirm status names match exactly (case-sensitive). If cycle time shows "0", check that issues transitioned through "in progress" statuses before completion and that status history is available.

CSV export not working

If export fails, check for a browser popup blocker, allow popups from your Jira instance, verify download settings, try a smaller data source, or try a different browser.

Getting Help

If you continue to experience issues, verify the app's permissions are granted (Jira Settings → Apps → Manage apps), check your browser's developer console for error messages, and contact support@divim.io with your Jira edition, browser, error messages, and steps to reproduce. Screenshots are helpful.

Frequently Asked Questions

Q: Does this app modify my Jira data?
A: No, the app operates in read-only mode. It only reads issue data for analysis and does not create, update, or delete any Jira issues or configurations.

Q: How often is data refreshed?
A: Data is fetched in real-time when you load or refresh the dashboard. You can manually refresh by reloading the page or switching data sources.

Q: Can I use this with Jira Service Management (JSM)?
A: Yes — the app fully supports JSM projects and includes features designed for service desk workflows.

Q: Does this work with Jira Data Center or Server?
A: No, this app is designed specifically for Jira Cloud. It uses Forge and Cloud-specific APIs that aren't available in Data Center or Server.

Q: What happens to my configuration if I uninstall the app?
A: Your configuration is stored in app-specific storage and will be lost if you uninstall. Export any important data before uninstalling.

Q: Why do my lead times not match what I calculated manually?
A: Ensure you're comparing the same time periods and issue sets. Lead time is calculated from created date to resolved date.

Q: Can I analyze issues that are still in progress?
A: Lead time includes both completed and in-progress issues (showing aging); cycle time only includes completed issues. WIP visualization (Flow Load) is coming soon.

Q: Who can see my team's metrics?
A: Anyone with access to the Jira project and the Flow Metrics page. Data visibility follows Jira's permission model.

Q: Is my data sent to external servers?
A: No, all computation happens within Atlassian's infrastructure. Data never leaves your Jira Cloud instance or Atlassian's Forge platform.

Q: What browsers are supported?
A: Modern versions of Chrome, Firefox, Safari, and Edge. Internet Explorer is not supported.

Q: How do I clear cached data or reset the app?
A: The app includes debug tools at the bottom of the project page to clear cached metrics/configuration and synced issue data. Note: these actions permanently delete the cached data, after which you'll need to re-sync and reconfigure.

Coming Soon: Planning Accuracy is in development. Related FAQs will be added when the feature is released.

Best Practices

For Teams Just Starting with Flow Metrics

Start simple (begin with lead time, use project as the data source, observe trends for 4–6 weeks before changing your process). Establish baselines and set improvement goals. Focus on consistency before speed. Don't obsess over individual issues — flow metrics are about patterns, not single data points.

For Scrum Teams

Track metrics by sprint using the board source, include flow charts in retrospectives, and use average throughput to guide realistic sprint commitments. A typical workflow configuration is Start: "In Progress", "In Review"; End: "Done".

For Kanban Teams

Focus on flow, monitoring lead time as the primary metric and using Work Distribution to understand the mix of work and set WIP limits. A typical configuration is Start: first "doing" column; End: "Done" or "Released".

For Service Desk Teams (JSM)

Track SLA compliance using lead time, separate incident types via breakdown analysis, and account for customer wait time by excluding "Waiting for Customer" from cycle time while including "Waiting for Support".

For Managers and Leaders

Use metrics for trends, not individual evaluation; compare your team against its own past rather than other teams; share context alongside metrics; and balance speed with quality.

Continuous Improvement Cycle

Measure (establish baselines), analyze (review trends and form hypotheses), improve (implement one or two changes), review (compare against baseline), and repeat. Small, incremental changes compound over time.

Glossary

Atlassian Forge: Serverless platform for building Jira Cloud apps. CFD: Cumulative Flow Diagram. Cycle Time: Time work spends in active development statuses. JQL: Jira Query Language. JSM: Jira Service Management. Lead Time: Total time from work request to completion. Throughput: Number of items completed in a time period. WIP: Work In Progress.

Additional Resources

Atlassian Resources

• Jira Cloud Documentation

• JQL Reference Guide

• Atlassian Community

Flow Metrics Learning

• Atlassian Agile Coach — Metrics

• Actionable Agile Metrics by Daniel Vacanti

Support and Feedback

For support, feature requests, and bug reports, contact support@divim.io. When reporting a bug, please include your Jira edition, browser, error messages, and steps to reproduce. We welcome feedback on how the app helps your team.

Version Information

Last Updated: March 2026
Compatibility: Jira Cloud (all editions)

Thank you for using Flow Metrics Charts for Jira Cloud!