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.