Jira Sync Projects Issues Dashboard

Jira Sync Projects Issues Dashboard

Mirror one or many Jira projects into your Obsidian vault — one note per issue, organized by project — and view a local, filterable KPI dashboard on top of them: completion, overdue, workload-by-assignee, weekly productivity, and bug accountability. Works against Jira Cloud and Jira Server / Data Center. Read-only, desktop-only.

📖 Setting up? See SETUP.md for connection options, API tokens/PATs, custom-field detection, large-instance tuning, and troubleshooting.

Desktop-only — it makes HTTPS requests to your Jira instance via Node's requestUrl. Not available on Obsidian mobile.

Table of contents

• What it does
• The dashboard
• Vault layout
• Install
• Quick start
• Settings reference
• Commands
• Large instances
• How sync works
• Observability
• Security & privacy
• Development
• License

What it does

• Connects to Jira three ways: Cloud (email + API token), Server/DC (Personal Access Token), or Server/DC (username + password). All traffic goes straight to your instance over HTTPS via requestUrl — no third-party server, no CORS proxy.
• Syncs multiple projects. Pick which projects to mirror (or all), add an optional JQL filter, and sync on demand, on a timer, or on startup.
• Writes Markdown notes — one per issue with YAML frontmatter (status, assignee, sprint, story points, due date, labels, …), plus per-project summary notes and an index, all under a folder you choose, in friendly-named per-project subfolders.
• Caches everything locally (jira-cache.json) so the dashboard renders instantly and works offline once synced.
• Renders a KPI dashboard — see below.
• Read-only. The plugin issues only GET requests. It never creates, edits, or deletes anything in Jira.

The dashboard

Open it from the ribbon icon (kanban square), the "Open dashboard" command, or by dropping a fenced block into any note:

```jira-dashboard

```

Filters (cascading)

Multi-select by project, sprint, assignee, status, issue type, priority, plus free-text search and an Open only toggle. Filters cascade: choosing a project narrows the sprint / assignee / status / type / priority dropdowns to that project's values. Projects show their friendly name, not the key.

KPI cards

Total · To-Do · In-Progress · Done · Completion % · Overdue · Due ≤ 7 days · Unassigned · Story points (done/total) · Average resolution time.

Productivity — tasks closed / week

• Project level: a 12-week column chart of tasks closed (respects the current filters, so it scopes to a selected project), plus a "Closed by project" table.
• Individual level: pick a person → their own 12-week closed-tasks trend, plus workload by status and priority.

Bugs

Total & open bug counts, Top 5 projects by bug count, and Top 5 developers by bug count (matches Bug/Defect issue types).

Pending by assignee

Open count, open story points, overdue, done, and next due date per person — click a name to focus their individual KPIs.

Breakdowns

By project, status, priority, and sprint, as inline stacked bar charts (To-Do / In-Progress / Done). No external chart library — CSP-safe, zero network.

Issue table

Sortable, searchable; click an issue key to open its note (or Jira, if note writing is disabled).

Tip: the ribbon dashboard view is always full width. The jira-dashboard code block also expands to full width even when your note uses "Readable line length".

Vault layout

13-Jira/                          ← your chosen target folder
  _Dashboard.md                   ← embeds the ```jira-dashboard``` block
  _Index.md                       ← projects & issue counts
  Payments/                       ← per-project folder, named by project name
    _PAY.md                       ← project summary + open issues
    PAY-123 — Fix login race.md   ← one note per issue
  Alliance/
    _ALM.md
    ALM-4 — Onboard partner.md

Each issue note carries frontmatter you can query with Dataview/Bases:

---
key: PAY-123
project: PAY
type: Bug
status: In Progress
status_category: indeterminate
priority: High
assignee: Alice Smith
reporter: Bob Lee
sprint: Sprint 14
story_points: 5
created: 2026-06-01T10:00:00.000+0530
updated: 2026-07-08T14:22:00.000+0530
due: 2026-07-10
resolution:
labels: [mobile, auth]
url: https://your-site.atlassian.net/browse/PAY-123
---

Install

From source:

npm install
npm run build          # typecheck + produce main.js
VAULT="/path/to/your/vault" npm run install:vault

That copies main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/jira-sync-dashboard/. Then in Obsidian: Settings → Community plugins → Installed plugins → enable Jira Sync & Dashboard.

Manual: copy main.js, manifest.json, styles.css into <vault>/.obsidian/plugins/jira-sync-dashboard/ yourself and enable it.

Quick start

1. Settings → Jira Sync & Dashboard.
2. Choose a Connection method, enter the Base URL and credentials, click Test — you should see a "Connected as …" notice.
3. Click Load projects and tick the ones to sync (leave all unticked = all).
4. Click Auto-detect fields to resolve the Story-Points / Sprint / Epic custom-field ids.
5. Set the Target folder (default 12-Jira).
6. Click Sync now (or use the ribbon / command).
7. Open the dashboard from the ribbon icon.

Settings reference

Connection

• Connection method — Cloud (email + API token) · Server/DC (PAT) · Server/DC (user + password).
• Base URL — e.g. https://your-site.atlassian.net (no trailing slash).
• Credentials (conditional on method) — token/PAT fields are masked.
• Test connection — calls /myself and reports the account + deployment type.

Projects & scope

• Load projects → tick which to sync (none = all). Or type comma-separated Project keys.
• Extra JQL — ANDed onto every search, e.g. labels = mobile.
• Sync since (YYYY-MM-DD) — floor on updated for the first sync (empty = all history).

Custom fields

• Auto-detect fields — resolves Story-Points / Sprint / Epic field ids by name.
• Manual overrides for each id.

Vault

• Target folder — where notes live (per-project subfolders inside).
• Write issue notes / Write project & index notes — toggle note writing (cache still populates either way).

Rate limiting

• Delay between API calls (ms) — throttle (default 150). 0 = no delay.
• Discover boards & sprints — enumerate sprints via the Agile API. Turn off on large instances (see below).

Automation

• Auto-sync interval (minutes) — 0 = off.
• Sync on startup.

Diagnostics

• Debug logging — verbose [jira] console output.
• Sync now.

Maintenance

• Rebuild notes — deletes the target folder and re-writes every note from the local cache (no API calls). Two-click confirm. Use to clean up old folders after renaming or a folder-scheme change.

Commands

• Sync now
• Stop sync
• Open dashboard
• Rebuild notes from cache (clears the Jira folder)

Large instances

On big Jira sites (thousands of boards/sprints, thousands of projects):

• Turn Discover boards & sprints OFF. Board enumeration is the most expensive step; sprint names still come from each issue, so the sprint filter keeps working — you just don't get a pre-populated sprint roster.
• Set a Sync since date (e.g. last 90 days) for the first sync.
• Keep Delay between API calls at 150ms or higher to avoid rate limits.
• Restrict scope with Load projects and/or Extra JQL.
• The client automatically backs off and retries on 429 Too Many Requests.

How sync works

• Incremental per project. Each project stores the highest updated timestamp it has written; the next sync fetches only issues changed since then (with a 1-minute overlap buffer). Dedup is by issue key, so overlaps never duplicate.
• Deployment-aware search. Jira Cloud uses the token-paginated /rest/api/3/search/jql endpoint (the old offset /search was removed by Atlassian and returns 410 Gone). Server/DC uses the classic /rest/api/2/search with startAt/total.
• Cancellable. Stop mid-run; written notes are kept and the next sync resumes from each project's cursor.

Observability

• Status bar: Jira · <last sync> / Jira · PAY 340 (or 340/1200 on Server) / Jira · rebuilding … / Jira · error.
• Notices on completion (issue + project counts) and on errors.
• Debug logging toggle → verbose [jira] console output (open devtools with Ctrl/Cmd+Shift+I). The auth token is never logged.

Security & privacy

• Credentials (API token / PAT / password) are stored in the plugin's data.json inside your vault. Keep the vault private; the token is never logged. Prefer a scoped API token / PAT over a full account password.
• All traffic goes directly to your Jira base URL over HTTPS via requestUrl — no third-party server, no analytics, no telemetry.
• The plugin performs only GET requests; it never writes to Jira.
• Synced issues are plain Markdown in your vault — don't sync the Jira folder to untrusted locations.

Development

npm install
npm run dev        # esbuild watch, rebuilds main.js on change
npm run typecheck  # tsc --noEmit
npm run build      # typecheck + production bundle

Source layout:

• src/main.ts — plugin lifecycle, ribbon, status bar, commands, timer, view + code-block registration, rebuild-from-cache.
• src/types.ts — shared types + defaults.
• src/settings.ts — settings UI (connection, projects, fields, rate limiting, automation, maintenance).
• src/jira/client.ts — auth, requestUrl, error mapping, throttle, rate-limit backoff.
• src/jira/api.ts — projects, JQL search (Cloud token / Server offset), boards/sprints, field detection, normalization.
• src/sync.ts — orchestration, incremental cursors, cache + note upsert, cancellation.
• src/notes.ts — filename sanitizing, friendly-name folders, frontmatter, race-tolerant writes.
• src/cache.ts — cache load/save, filtering, KPI / workload / weekly-productivity / top-N aggregation.
• src/dashboard/view.ts — ItemView host.
• src/dashboard/render.ts — filter bar, KPI cards, productivity & bug sections, tables, bar/column charts (DOM).

License

Released under the MIT License © 2026 Nabheet Madan.

This project is an independent, community-built plugin. It is not affiliated with, endorsed by, or sponsored by Atlassian. "Jira" is a trademark of Atlassian.