Jira Import

Use the Jira import wizard to import projects, issues, comments, attachments, and worklogs from Jira Cloud or Data Center. The wizard also imports boards, sprints, custom fields, and Insight/Assets. For Jira Cloud, use a classic API token without scopes.

What gets imported

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

Prerequisites

  • A running Windshift instance with admin access.
  • An Atlassian account on the Jira instance you want to import.
  • Browse Projects permission for that account on every project you want to import. Sign in to the Jira UI first. Make sure the project switcher is not empty.

Step 1: Create a classic Jira API token

For Jira Cloud, create the classic API token without scopes. Do not select Create API token with scopes.

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.
  2. Click Create API token.
  3. Name the token, such as "Windshift import", then click Create.
  4. Copy the token immediately. Atlassian shows it once.

A classic token inherits the Jira permissions of the Atlassian account. The importer reads data only. Use an account that has access to everything that needs importing.

Data Center: Use a Personal Access Token from your Jira profile. It has no scopes. The underlying account needs Browse Projects and View Issues for each project.

Step 2: Open the Jira import wizard in Windshift

  1. Navigate to Admin > Imports > Jira
  2. Click New Connection
  3. Enter the connection details:
    • Instance URL: https://<your-site>.atlassian.net or your Data Center hostname.
    • Email: The email address for 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 verifies the token. When the test succeeds, the wizard opens project selection.

Step 3: Pick projects and run the import

  1. Select the Jira projects to import.
  2. Map Jira custom fields to existing Windshift fields if needed.
  3. Click Start import.

Windshift runs imports in the background. It shows progress and per-project status in Admin > Imports.

Re-running an import

The importer records the data it creates. It does not silently create duplicates when you import the same project twice. If data from a previous import exists, Windshift stops the wizard with a conflict. To import again, first delete the previous import data in Admin > Imports. You can also use the re-import option when the wizard offers it.

Troubleshooting

When an import fails, the wizard shows Jira's error message. The Windshift server log records the error under the jira component.

Jira says What to do
Client must be authenticated to access this resource. Create a new classic API token with Create API token. Do not use Create API token with scopes.
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