Skip to content
sprintrrdocs
Sign in

Jira

One-way import from Jira Cloud into sprintrr. Encrypted token storage, idempotent re-imports, no write-back to Jira.

on this page

    sprintrr does a one-way import from Jira Cloud. Connect a workspace, pick a project, preview the field mapping, import. Re-running the import updates existing tasks instead of duplicating them.

    When to use it

    • You already use Jira and want to evaluate sprintrr's AI features (status updates, transcripts → tasks, risk register, date cascades) on your real data — without re-typing 80 issues.
    • You want a one-time migration into sprintrr but keep Jira as the archival source for past work.
    • You want to use sprintrr as a sandbox / what-if planner alongside Jira, with periodic re-syncs.

    What we do NOT do (yet)

    • Two-way sync — sprintrr never writes back to Jira. Out of scope for v1; in roadmap for later if there's customer pull.
    • OAuth 2.0 (3LO) — sprintrr connects with an API token + email for now; OAuth is on the roadmap.
    • JQL filters / sprint scoping — v1 imports the top N issues ordered by updated DESC. Custom JQL is on the roadmap.
    • Custom field mapping — we map the standard fields (see below) and ignore custom fields in v1.
    • Auto-create milestones — we map Jira epics to existing milestones by title. We don't create new milestones from epics automatically to avoid silently spawning rows.

    Setup

    1. Go to Settings → Integrations → Jira.
    2. Paste your Jira Cloud URL (e.g. https://yourcompany.atlassian.net).
    3. Create an Atlassian API token:
      • Open id.atlassian.com/manage-profile/security/api-tokens (opens in a new tab).
      • Click Create API token. (Atlassian also exposes a separate Create API token with scopes button — both work. Scopes are optional but recommended; if you scope, grant read:jira-user and read:jira-work for full import coverage.)
      • Give the token a name (e.g. "sprintrr").
      • Set an expiry. As of December 15, 2024 the default is 1 year; you can choose 1–365 days. Pre-2024 perpetual tokens have all been auto-expired by Atlassian.
      • Atlassian may prompt you for a one-time passcode (password / 3rd-party logins only — SSO and service accounts skip this).
      • Copy the token immediately — it's only shown once.
    4. Paste your Atlassian email + the token into sprintrr.
    5. Click Connect & verify — sprintrr calls /rest/api/3/myself to validate the credentials before persisting. If Atlassian rejects them, you get the exact error inline.

    The token is encrypted at rest with AES-256-GCM (the same BYOK_ENCRYPTION_KEY used for user-supplied AI keys). It never leaves the server decrypted. When the token expires (1 year by default), sprintrr will surface a clear connection-failed error on the next import — generate a new token and reconnect.

    Running an import

    1. Click Import issues in Settings → Integrations → Jira.
    2. The wizard walks four steps — Jira project → Preview → Destination → Done: pick the Jira project, click Preview mapping to see its first 25 issues as sprintrr will file them, pick the sprintrr project they land in, then click Import into it.
    3. Each run imports 100 issues by default, up to 200, most recently updated first. When it finishes, the window reports new tasks, updated tasks and anything skipped.

    Re-importing the same Jira project updates existing tasks (matched by the Jira issue key stored in tasks.external_id). The mapped fields get overwritten with the latest values from Jira.

    Field mapping

    Jira→ sprintrr
    summarytitle (truncated to 200 chars)
    description (ADF)description (flattened to plain text)
    status.statusCategory (done / indeterminate / new)status (Completed / In Progress / Not Started)
    status name matching block / impediment, or label blockedstatus = Blocked
    priority.namepriority (Highest/Critical → High, Low/Trivial → Low, else Medium)
    issuetype.namecategory (Bug → Testing, Story → Development, Epic → Strategy, …)
    assignee.emailAddressassigned_to[] (only matched if the email exists in user_profiles)
    duedatedue_date
    parent.fields.summary (epic)milestone_id (matched against existing milestones by title)
    key + browse URLexternal_id + external_url (renders the "Imported from Jira" badge)

    MCP usage

    Imports aren't currently exposed via MCP — the wizard is the only interface. We may add an MCP import-from-jira action in a later pass if there's demand from Claude Desktop / Cursor users.

    Security + audit

    • Token: AES-256-GCM encrypted with BYOK_ENCRYPTION_KEY, stored as bytea in jira_integrations.encrypted_api_token. Decrypted only in-memory for each Jira API call.
    • All actions audited: JIRA_CONNECTED, JIRA_REVOKED, JIRA_IMPORT_STARTED, JIRA_IMPORT_COMPLETED, JIRA_IMPORT_FAILED.
    • Import emits an imported_from_jira activity event on the destination sprintrr project.
    • Job history visible at Settings → Integrations → Jira → recent imports.
    • RLS: only the owning user can see their integration row or import job rows.

    Roadmap

    • JQL filter on the import wizard for projects with thousands of issues.
    • Background-job chunking for >200-issue imports.
    • OAuth 2.0 (3LO) instead of API token.
    • Asana / Linear / ClickUp importers built on the same external_* provenance contract.
    • Two-way sync — only if customers ask. Bidirectional sync is a large surface (webhooks, conflict UX, sync state) and not always what users want.

    Something unclear or out of date? Email support@sprintrr.ai — the subject line already names this page.