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:

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

Filters (Generate Report)

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.