Jira Import

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

What gets imported

• Projects and issues, with comments, attachments, and worklogs.
• Boards become collections with matching board configurations.
• Sprints become iterations.
• Custom fields are created in Windshift and mapped, so issue field values carry over. You can also map Jira fields to existing Windshift fields during the import.
• Insight / Assets schemas import as asset sets and types, including asset-backed custom fields.

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 — required to import boards and sprints. Omit it only if you want an issues-only import.
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.

Re-running an import

The importer tracks everything it creates, so it will not silently create duplicates if you import the same project twice. If import data from a previous run already exists, Windshift detects it and the wizard stops with a conflict instead of importing again. To re-import, delete the previous import data from Admin > Imports first (or choose the re-import option the wizard offers), then run it again.

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.

References

• Manage Atlassian API tokens
• Jira OAuth 2.0 scopes