Documentation — BottleneckIQ

This page covers what BottleneckIQ is, how to install it, and how to read the dashboard. Detailed how-to pages are linked at the bottom.

What it does

BottleneckIQ reads your Jira issue changelogs and computes:

Flow metrics — average / P50 / P90 time spent in each workflow status, throughput, WIP averages.
Bottleneck detection — identifies the workflow stage most likely slowing your team down right now, scored on three signals (time, WIP, throughput) and explained in one sentence.
Trends — current window vs. prior window comparisons surfaced as "improving" / "worsening" / "stable."
Charts — WIP Aging (which tickets are stuck right now), Cumulative Flow Diagram (how work is piling up over time), Cycle Time Scatter (which completed tickets took longer than usual).
Alerts — rules that fire when a configured threshold is breached.

Everything is computed deterministically from Jira's changelog. The same data always produces the same metrics. AI is used only to translate already-computed signals into one-sentence explanations — it never affects the numbers.

Where the plugin lives in Jira

BottleneckIQ surfaces in two places inside Jira:

Project dashboard — a jira:projectPage module in the left-nav of each individual Jira project under "Apps." Click it from a project's nav to see that project's flow analytics. Each project gets its own scoped page.
Issue panel — a jira:issuePanel module surfacing per-issue time-per-status data directly on the Jira issue view. By current Atlassian platform behavior, the panel needs a per-issue Apps button click to become visible; project admins can pre-enable it project-wide using a documented workaround. See Using the BottleneckIQ issue panel → for full setup guidance.

First-time install

A Jira admin installs the plugin once for the whole site. After install:

Open any project in Jira.
Click "Apps" in the left-nav (or "Apps" → "BottleneckIQ" depending on your nav layout).
The dashboard loads. On a fresh install it shows "Loading flow intelligence…" and then either populated data or an empty state.

Initial backfill

The first time you open BottleneckIQ on a project, the dashboard will be empty — webhooks only capture changes from the install moment forward, so historical issues need a one-time pull. Click Settings → Historical backfill → Start to paginate through every issue your install can read.

While the backfill runs, the Settings tab shows live progress. The dashboard populates as batches complete; you can leave the page open. Hard cap: 50,000 issues per run; sites larger than that should email us for an extension.

After backfill completes, webhooks keep the dashboard fresh going forward.

How sync works

The dashboard is automatically kept in sync via webhooks. When you change a Jira issue's status, assignee, or any tracked field, the dashboard reflects it within ~30 seconds without manual intervention. A daily reconciliation pass catches anything webhooks may have missed.

A "Last sync: 5m ago" indicator at the top of the dashboard shows when the most recent ingest happened. If a change is taking longer than expected to reflect, email support with the issue key and we'll dig into the sync logs.

What you see on the dashboard

The page is organized into tabs:

Overview — top-level cards: bottleneck of the week, current vs. prior comparison, alert summary.
Flow — average / P50 / P90 time-in-status table, plus the WIP Aging chart and CFD.
Cycle Time — scatter of completed issues with cycle-time outliers highlighted.
Alerts — list of configured alert rules and their fire history.
Settings — historical backfill controls, AI explanation toggle, sprint field configuration, alert rule editor, external-blocking statuses (mark Blocked / Waiting for Customer statuses so they stop driving bottleneck attribution), and work schedule (timezone + working days + work hours + holidays — when set, every duration computation honors working hours instead of wall-clock).

An Export CSV button on the dashboard top bar emits one row per (issue, status slice) with external_blocking and is_terminal markers, for per-stage analysis in your own spreadsheet.

Windows and comparisons

Every metric is computed over a configurable window: 7 days, 30 days, 90 days, month-to-date, quarter-to-date, or "current sprint" if your project uses sprints. The Overview cards show current-window vs. prior-window deltas so you can see whether things are improving, worsening, or stable.

Alerts

Alerts fire when a condition you configure is met. Five rule types:

Stuck in status — a ticket sits in a status longer than your threshold.
Cycle time exceeded — a ticket's total time from created to done (or now, if still open) crosses your threshold.
No activity — an in-flight ticket has had no status change, comment, or field update for your threshold period.
Trend worsening / improving — a metric (cycle time, throughput, WIP) shifts beyond your percentage threshold versus the prior window.
WIP limit breach — active WIP in a status exceeds the limit you set for it.

Each alert deduplicates: a per-rule cooldown means the same condition won't notify you repeatedly.

Delivery. Alerts surface in the Overview tab and can be pushed to email, Slack, and Microsoft Teams. Set destinations in Settings → Alert Destinations, then choose which destinations each rule uses (or set tenant-wide defaults). Slack and Teams connect via an incoming webhook URL you paste — about a minute of setup:

When a work schedule is active, alert thresholds are interpreted in working hours, not calendar hours — a cycle_time > 7d rule under a Mon–Fri 9–5 schedule fires after ~7 working days (about 11 calendar days), not 7 calendar days.

Privacy and security

BottleneckIQ reads only issue metadata, status changelogs, and two custom fields (Story Points and Sprint). It does not read descriptions, comments, attachments, or worklogs. All data lives in AWS US East 1, encrypted at rest. Uninstalling the app deletes your data within minutes.

Full details: Privacy Policy · Security Disclosure · Terms of Service