Jira Import

Import projects, issues, comments, attachments, and worklogs from a Jira Cloud or Data Center instance into Windshift. The Jira import wizard needs an API token; this guide walks through creating one with the right scopes and connecting it to Windshift.

Prerequisites

  • Running Windshift instance with admin access
  • An Atlassian account on the Jira instance you want to import from
  • That account must have Browse Projects permission on every project you intend to import (sign in to the Jira UI first to verify the project switcher isn't empty)

Step 1: Create a Jira API token

Atlassian Cloud offers two token types and Windshift accepts both.

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click either:
    • "Create API token" — legacy unscoped, inherits the account's full Jira permissions. Easiest if your org policy permits it.
    • "Create API token with scopes" — scoped. Select these classic scopes:
      • read:jira-work — projects, issues, fields, search
      • read:jira-user — resolve assignees and reporters
      • read:me — required by Windshift's auto-detection
      • read:jira-software (optional) — boards and sprints
  3. Give the token a name (e.g. "Windshift import") and click Create
  4. Copy the token immediately — Atlassian only shows it once

The importer is read-only. Don't grant write:* or manage:* scopes — they aren't used and broaden the impact of a leaked token.

Data Center: Use a Personal Access Token from your Jira profile. PATs have no scopes; the underlying account needs Browse Projects and View Issues on each project.

Step 2: Open the Jira import wizard in Windshift

  1. Navigate to Admin > Imports > Jira
  2. Click New Connection
  3. Enter:
    • Instance URL — https://<your-site>.atlassian.net (or your Data Center hostname)
    • Email — the email on the Atlassian account that owns the token
    • API token — the token you copied in Step 1
    • Deployment — Cloud or Data Center
  4. Click Test connection

Windshift detects whether the token is scoped or unscoped and routes API calls accordingly. On success, the wizard advances to project selection.

Step 3: Pick projects and run the import

  1. Select the Jira projects to import
  2. Optionally map Jira custom fields to existing Windshift fields
  3. Click Start import

Imports run in the background. Progress and per-project status appear in Admin > Imports.

Troubleshooting

When something goes wrong, the wizard shows Jira's own error message verbatim and the Windshift server log records it under the jira component.

Jira says What to do
Client must be authenticated to access this resource. Scoped token is missing the read:me scope. Recreate the token with read:me selected, or use a legacy unscoped token.
You do not have the permission to see the specified issue. The Atlassian account lacks Browse Projects on that project. Adjust the project's Permission Scheme.
Empty project list with no error The account has no Browse Projects grant anywhere. Sign in to the Jira UI to confirm, then ask a Jira admin to add the account to the relevant projects.

References