Jira integration setup

Overview

The Jira integration lets a moderator connect a Jira Cloud site to their SprintBee account, then attach that connection to individual rooms as a work item source. Once a room has a Jira source, moderators can search Jira from inside the room and import issues into the queue with one click, and participants without search access can paste an issue key or URL to request an import.

When a room is configured for story-point write-back, accepting an estimate for an imported Jira item updates the mapped field(s) on that issue automatically — no separate sync step.

This integration is available on Pro plans. Free plans don't see a working Jira connect option.

Prerequisites

Before connecting, make sure you have:

• A Jira Cloud site (Jira Data Center/Server is not supported by this OAuth flow).
• A SprintBee account on a Pro plan — the Integrations tab shows "Integrations are a Pro feature" until then.
• Permission in Jira to authorize a third-party app for the site (your Atlassian admin may need to approve the app the first time anyone on the site connects it).
• Edit permission on the Jira fields you intend to map for story-point write-back, if you plan to use it.

Connect SprintBee to Jira

Connections are made once per SprintBee account (not per room) from the moderator dashboard.

• Go to Dashboard → Integrations.
• Click "Add connection" and choose Jira.
• You're redirected to Atlassian's consent screen. Approve access — SprintBee requests read:jira-work, read:jira-user, read:me, write:jira-work, and offline_access (see FAQ for what each is for).
• After approving, you're returned to Integrations with the connection listed as "Connected", showing the connected Atlassian account and every Jira site (workspace) it can reach.
• Open a room's settings and, under "Jira source", pick the Jira site to use for that room and save. Each room links to one Jira site at a time; the same account-level connection can be attached to multiple rooms.

Import work items

Inside a room, moderators add issues from the "Add work items" panel's Jira tab. The search box does double duty: paste a bare issue key or a Jira URL and it imports directly; type anything else and it runs a keyword search.

Three quick-search presets are offered — Current sprint, My open issues, and Recently updated — plus a "Room default" preset when the room has a configured default JQL. An "Advanced (raw JQL)" toggle exposes a raw JQL field for anyone who wants full control.

Room settings can scope search to specific Jira projects. When one or more projects are selected, every search (presets, keyword, and advanced JQL) is constrained to `project in (...)`; leaving the scope empty searches all projects on the site.

Participants who aren't moderators don't get inline search. Instead they can paste one or more issue keys/URLs into the Jira tab to submit an import request, which a moderator approves or dismisses from the queue.

Story-point write-back

Write-back is configured per room, under the Jira source's "Story point write-back" section, and is off by default.

Mapping depends on how the room estimates. Single-team rooms map one "Story points field" that receives the accepted estimate. Rooms using Split Dev/QA voting can independently map a Dev estimate field, a QA estimate field, and a Dev + QA total field — the total is only written when both the Dev and QA estimates are numeric.

Mapped fields can be numeric, plain text, or single-select (Jira "option") fields, so non-numeric decks such as T-shirt sizes can be written to a text or select field. A numeric field only accepts a numeric value — if the accepted card is non-numeric (or is a non-estimate card such as "?", "∞", or "Pass"), that field is simply left unwritten rather than erroring.

Write-back fires once, automatically, when a moderator accepts an estimate for a round linked to a connected Jira issue. It requires the room's Jira connection to have granted the write:jira-work scope; read-only connections show a warning in the mapping section and won't write anything until reconnected.

Each attempt records an outcome (succeeded, failed, or skipped) against the round, so moderators can see whether the last accepted estimate actually reached Jira.

Troubleshooting

Most Jira integration problems fall into a few known categories:

• "Jira connection needs to be reconnected" — the stored access/refresh token is missing or Jira rejected a refresh attempt. Reconnect Jira from Dashboard → Integrations.
• "Jira rejected this connection. Reconnect Jira and try again." on search/import — Jira returned a 401/403 on a read call, usually an expired or revoked authorization. Reconnect.
• "Jira rejected the update. Reconnect Jira to grant write access, then try again." on write-back — the connection doesn't currently hold the write:jira-work scope. This happens to connections made before write-back existed; reconnect Jira to re-consent with the newer scope set.
• Write-back silently skipped — check that write-back is enabled for the room, at least one field is mapped, and the accepted card isn't a non-estimate sentinel ("?", "∞", or "Pass"). The room records a "skipped" status with a reason when this happens.
• "Jira rejected the update: ..." with a specific field error — Jira's own validation message is surfaced, most often because the mapped field doesn't accept the value's type or the connected account lacks edit permission on that field in the target project.
• No Jira sites appear after connecting — the Atlassian account that authorized SprintBee doesn't have access to any Jira Cloud site, or site access changed after connecting; reconnect using an account with access to the right site.
• "Configure a Jira source in room settings before importing issues." — the room has no Jira source attached yet; add one from room settings using an existing dashboard connection.

FAQ

What scopes does SprintBee request, and why? read:me and read:jira-user identify the connected Atlassian account; read:jira-work lets SprintBee search and read issues; write:jira-work lets SprintBee write accepted estimates back onto an issue; offline_access lets SprintBee refresh the connection without asking you to re-authorize on every use.

Can I use a read-only connection? Yes — write-back is optional per room. A connection without write:jira-work (for example, one made before write-back existed) can still search and import issues; only the write-back step is blocked until you reconnect.

Does SprintBee write anything to Jira besides the mapped estimate field(s)? No. Write-back only sets the specific field(s) mapped in a room's story-point sync settings — it doesn't change status, comments, or any other field.

Can I disconnect Jira? Yes, from Dashboard → Integrations click Disconnect on the connection. SprintBee deletes the stored OAuth tokens; issues already imported into room queues stay as they are.

Is Jira Data Center or Server supported? Not currently — the connect flow authorizes against Jira Cloud via Atlassian's OAuth and accessible-resources API.