n8n-nodes-jira-reports

An n8n community node for read-only Jira Cloud data: fetch issues for one or more projects with a field picker, or generate one of 20 enterprise-grade analytics reports (executive dashboards, velocity, burndown, SLA compliance, aging, workload, and more) as JSON, Markdown, HTML, CSV-ready JSON, or a deterministic executive/AI-style summary.

This node does not create or update Jira issues. It is read-only.

Operations

The node has two operations, selected via the Operation parameter:

• Fetch Issues (default) — the v1 flow. Connect to Jira, pick a project, pick a date range, and it fetches every matching issue with every field Jira returns. Use the Fields picker to choose which fields show up in the output; leave it empty to get everything. Returns one n8n item per issue.
• Generate Report — the analytics engine described below: 20 report types, rich filtering, and 6 output formats.

Features

• Fetch Issues: project(s) + date range in, one row per issue out, with a dynamic field picker (system + custom fields) so you only get what you asked for.
• 20 report types covering delivery health, sprint execution, quality, workload, and compliance (full list below).
• 6 output formats: JSON, Markdown, HTML, CSV-ready JSON, AI Summary, Executive Summary.
• Rich filtering (Generate Report): project(s), JQL, date range, status, priority, issue type, labels, components, sprint, board, epic, assignee, reporter, fix version, environment, and arbitrary custom fields.
• Scales to very large projects: cursor-based pagination against Jira's current search API (/rest/api/3/search/jql), so 100k+ issue projects are streamed rather than loaded in one request.
• Resilient by default: automatic retry with exponential backoff + jitter on 429/5xx responses (honoring Retry-After), and a concurrency gate to avoid tripping Jira's rate limiter in the first place.
• Auto-discovery: story points, epic link, and sprint custom field IDs are resolved automatically per Jira site (they vary per instance) and cached.

Installation

In n8n, go to Settings → Community Nodes → Install and enter:

n8n-nodes-jira-reports

Or, for a self-hosted instance:

npm install n8n-nodes-jira-reports

Credentials

Create a Jira Cloud API credential with:

| Field | Description | |---|---| | Jira Base URL | e.g. https://your-domain.atlassian.net (no trailing slash) | | Email | The Atlassian account email associated with the API token | | API Token | Generate one at id.atlassian.com → Security → API tokens |

The node authenticates with HTTP Basic auth (email + API token), Jira Cloud's standard for API tokens.

Usage

Fetch Issues

1. Add the Jira Reports node to your workflow. Operation defaults to Fetch Issues.
2. Select one or more Projects.
3. Optionally set a Start Date / End Date (filters on issue created date).
4. Optionally pick Fields — leave empty to get every field Jira returns.
5. Run the node — it returns one n8n item per issue, keyed by human-readable field name (e.g. Summary, Status, Story Points) plus key and id.

Reference-object fields (status, priority, assignee, etc.) are flattened to their display text (e.g. Status: "In Progress" rather than the raw { name, id, ... } object); arrays are flattened element-by-element. Anything else is passed through as Jira returned it.

Generate Report

1. Add the Jira Reports node, set Operation to Generate Report.
2. Select one or more Projects.
3. Choose a Report Type.
4. Optionally narrow the result set with the filter parameters (Statuses, Priorities, Sprint, Epic, Labels, Advanced JQL, etc.).
5. Choose an Output Format.
6. Run the node — it fetches the required issues (and changelog, for status-history-driven reports), computes the report, and returns one item per input item.

Every report returns the same envelope:

{
  "metadata": { "reportType": "...", "generatedAt": "...", "projects": ["..."], "issueCount": 0 },
  "summary": {},
  "statistics": {},
  "chartData": {},
  "table": [],
  "recommendations": []
}

For markdown, html, aiSummary, and executiveSummary output formats, the node returns { format, content } where content is a rendered string. For csvJson, table is flattened into scalar-only rows ready for n8n's Convert to File (CSV) node.

Report Types

| Report | What it returns | |---|---| | Executive Dashboard | Total/open/closed/blocked/reopened counts, completion %, avg resolution/cycle/lead time, story points, velocity, risk level, 0–100 health score | | Issue Status Report | Status distribution, percentage, 7-day trend, average days per status | | Priority Report | Highest→Lowest breakdown and average resolution time per priority | | Sprint Report | Committed / completed / added-mid-sprint / removed-mid-sprint / carry-over / velocity / completion % per sprint | | Velocity Report | Velocity history across closed sprints, average, median, trend | | Burndown Dataset | Daily remaining issues/points vs. an ideal linear burndown for a selected sprint | | Assignee Workload | Per-assignee open/in-progress/closed/blocked, average age, story points, completion % | | Aging Report | Open issues older than a configurable threshold, with age/status/priority/assignee | | Blocked Issues | Currently blocked issues, blocked-since date, reason, assignee, priority, sprint | | Epic Progress | Per-epic child issue counts, completed/remaining/blocked, story points, progress % | | Story Point Analysis | Completed/remaining points, average, largest, size-bucket distribution | | Bug Analysis | Critical/major/minor severity, regression and production flags, resolution time | | SLA Report | Average resolution/response time, SLA breach count and %, time remaining on open issues | | Reopened Issues | Reopen counts, 30-day trend, most-reopened issues | | Release Readiness | Open bugs/stories, testing/documentation coverage heuristics, computed risk | | Component Report | Issues, story points, completion % per component | | Label Report | Most-used labels, unused instance labels, 30-day usage growth | | Custom Field Analytics | Auto-discovered custom fields, population %, top values | | Changelog Report | Every field change in the date range: who, what field, old → new value | | Time Tracking Report | Estimated / logged / remaining time and variance per issue |

Filters (Generate Report)

| Parameter | Notes | |---|---| | Projects | Required. One or more project keys. | | Start Date / End Date | Filters on issue created date. | | Board / Sprint | Sprint dropdown is populated from the selected board. Required for the Burndown report. | | Issue Types, Statuses, Priorities, Labels, Components, Fix Versions | Multi-select, populated from your Jira site. | | Assignees / Reporters | Populated from /rest/api/3/users/search (capped at 200 for the dropdown; use Advanced JQL for a larger/precise set). | | Epic | Matches both classic Epic Link and next-gen parent. | | Include Subtasks | Off excludes sub-task issue types after fetch. | | Custom Fields | Key/value filter pairs, translated to cf[id] = "value" in JQL. | | Advanced JQL | Combined with the generated clauses using AND. Use this for anything the structured filters don't cover (e.g. "Team" = "Platform"). | | Aging Threshold (Days) / SLA Resolution Threshold (Hours) | Only shown for the Aging / SLA report types. | | Max Issues | Safety cap for exploratory runs. Leave at 0 (default) for accurate, complete reports. |

Architecture

credentials/JiraCloudApi.credentials.ts     Jira Cloud API token credential

nodes/JiraReports/
  JiraReports.node.ts                       INodeType: parameter wiring + execute() for both operations
  GenericFunctions.ts                       Builds the API/metadata services from node context
  descriptions/properties.ts                All node parameters (Operation gates which ones show)
  methods/loadOptions.ts                    Dynamic dropdowns (projects, fields, boards, sprints, users, ...)

src/
  types/                                    Jira domain types + report/report-context types
  utils/                                    RetryHelper, PaginationHelper, DateHelper,
                                             StatisticsHelper, FormattingHelper, ErrorHelper,
                                             Logger, JqlBuilder, FieldProjection — no Jira/report
                                             knowledge, pure utilities
  services/
    JiraApiService.ts                       Typed REST wrapper: retry + concurrency gate + pagination
    JiraMetadataService.ts                  Caching facade for projects/fields/boards/sprints/users/...
    JiraIssueRepository.ts                  Orchestrates JQL building + issue fetch for a report
  reports/
    BaseReport.ts                           Abstract contract: generate(dataset) -> ReportOutput
    ReportHelpers.ts                        Shared domain logic (status category, story points, cycle time, ...)
    <ReportName>Report.ts                   One class per report type (20 files)
    index.ts                                REPORT_REGISTRY + createReport()
  formatters/
    <Format>Formatter.ts                    Json / Markdown / Html / CsvJson / AiSummary / ExecutiveSummary
    index.ts                                formatReport(output, format) dispatcher

test/
  support/                                  Fixture builders (makeIssue, makeContext, makeDataset)
  unit/reports/                             One test file per report, no live Jira required
  unit/services/, unit/utils/, unit/formatters/

Adding a new report type means: add the enum value to ReportType, create src/reports/NewReport.ts extending BaseReport, register it in src/reports/index.ts, and add its display option to descriptions/properties.ts. Nothing else needs to change.

Development

npm install
npm run build     # tsc + copy node icons/codex into dist/
npm run lint       # eslint (includes n8n community-node conventions)
npm test           # jest — mocked Jira API, no network calls
npm run test:coverage

To try the node against a real n8n instance locally, use npm link from this package and npm link n8n-nodes-jira-reports from your n8n installation, then restart n8n.

Examples

See examples/ for importable sample workflows:

• sample-workflow-executive-dashboard.json — Schedule trigger → Jira Reports (Executive Dashboard, Markdown) → Slack/Email.
• sample-workflow-sprint-report.json — Manual trigger → Jira Reports (Sprint Report, CSV-ready JSON) → Convert to File.

Node type identifiers in the sample workflows assume the package is installed under its published name. If you're developing locally via npm link, re-select the node in the n8n editor after import so the type resolves correctly.

Screenshots

Add screenshots of the node's parameter panel and a sample report output here:

• docs/screenshots/node-parameters.png
• docs/screenshots/executive-dashboard-output.png

(Placeholders — this repository ships without captured screenshots; add your own when publishing.)

Limitations

• Sprint-scope reconstruction (Sprint Report's committed/added/removed) relies on the "Sprint" field changelog, which is the only signal Jira Cloud exposes for scope changes — see the code comment in SprintReport.ts for the exact assumption used when no explicit event is found.
• Testing/Documentation coverage in the Release Readiness report is a label-based heuristic (qa/test, doc/documentation) since Jira has no standard fields for these — adjust the patterns in ReleaseReadinessReport.ts to match your team's conventions.
• "AI Summary" and "Executive Summary" formats are deterministic, template-based text — this node has no external AI/LLM dependency.