Overview
ImportPilot for Jira helps teams bulk-create issues from a spreadsheet using a seven-step guided workflow: upload, field mapping, issue type mapping, preview, validation, import, and results review.
Jira administrators can install and use the app immediately. Other users need access through the importpilot-users-group group and the app’s user access settings.
1. Installation Guide
Follow these steps to install ImportPilot for Jira on your Jira Cloud site.
1.1 Prerequisites
- A Jira Cloud site.
- Jira administrator access to install apps on that site.
- A CSV file of the issues you want to create.
1.2 Installation Steps
- Open the ImportPilot for Jira listing on the Atlassian Marketplace.
- Click Get App.
- Choose the Jira site you want to install the app on.
- Confirm that Jira is the selected service and complete the install.
- Once installed, open Apps in the Jira top navigation and select ImportPilot for Jira.
Jira administrators can use the app right away. Other users need access set up as described in section 2.
2. Configuration and Setup
Access to ImportPilot for Jira is controlled by a Jira group named importpilot-users-group. Jira administrators always have access. Everyone else must be added to the group.
2.1 User Access Configuration
Step 1: Create the importpilot-users-group group
The app creates this group automatically when it is installed. Check that it exists, and create it only if it is missing.
- Go to admin.atlassian.com and select your organization.
- Select Directory > Groups.
- Search for importpilot-users-group. If the group is listed, go to Step 2.
- Select Create group.
- Enter importpilot-users-group as the group name, exactly as shown.
- Select Create.
Step 2: Grant the Use ImportPilot for Jira permission
This is a one-time step. It makes ImportPilot for Jira appear in the Apps menu for group members.
- In Jira, select Settings (gear icon) > System.
- Under Security, select Global permissions.
- Choose Use ImportPilot for Jira as the permission and importpilot-users-group as the group, then save.
Step 3: Give users access
- In Jira, select Settings (gear icon) > Apps.
- In the left sidebar, select ImportPilot for Jira User Access.
- Search for the user by name or email.
- Tick the checkbox next to the user. Their status changes to Has Access.
- To remove access, clear the checkbox.
You can also add or remove members of importpilot-users-group directly in admin.atlassian.com.
2.2 Project Permissions
Issues are created as the person running the import, so their project permissions also apply.
- Create Issues — required in the project you import into. Only projects where the user has this permission appear in the project list.
- Assign Issues — required if your CSV sets an assignee.
3. Usage Documentation
This section describes how to import issues and use validation, results, and the in-app assistant.
3.1 Feature 1: Import Issues from CSV
Purpose: Create many Jira issues at once from a spreadsheet, following seven guided steps.
How to Use:
- Go to Apps > ImportPilot for Jira.
- Upload CSV: Drag your file onto the upload area or click to browse. Check the five-row preview, then click Continue to Configuration.
- Configure: Select the target project. Each CSV column is matched to a Jira field automatically where possible. Review each match and change any that are wrong, or choose Skip this column.
- Map at least Issue Type and Summary. If a red box lists required fields that are not mapped, add those columns to your CSV first.
- Click Map Issue Types. Match each issue type value in your CSV to an issue type in the project, then click Preview Import.
- Preview: Review the project and field mappings, then click Run Pre-Import Check (see Feature 2).
- Click Start Import. A progress bar shows while issues are created.
- Results: Review the summary (see Feature 3). Click Start New Import to begin again.
AI field suggestions: Columns matched by AI show an AI % badge with the confidence score. Hover the badge to see why. Where confidence is low, click Use AI suggestion to accept it.
3.2 Feature 2: Pre-Import Validation
Purpose: Catch problems in your file before any issues are created.
How to Use:
- On the Validate step, wait for the hierarchy and AI checks to finish.
- Review the list. Each item shows the row number, the problem and a suggested fix.
- Click Download Report to save the list as a CSV.
- To fix problems, update your CSV and upload it again, or click Fix Mappings.
- To import anyway, tick I have reviewed these issues and want to proceed anyway, then click Proceed Anyway.
3.3 Feature 3: Import Results and Error Reports
Purpose: See what was created and why any rows failed.
How to Use:
- Review the totals for rows, issues created, errors and success rate.
- Open the Created Issues tab to see the new issue keys.
- Open the Errors tab to see each failed row and the reason.
- Click Download Error Report to save the errors as a CSV.
- Click Explain Errors for a plain-language explanation and suggested fixes.
- Correct the failed rows in your CSV and import only those rows again.
3.4 Feature 4: Import Assistant
Purpose: Get help at any step without leaving the page.
How to Use:
- Click the chat icon in the top-right corner of ImportPilot for Jira.
- Type a question, such as how to format dates or set up subtasks.
- To get a starter file, ask for a sample CSV or a CSV template. Click the download button in the reply to save it.
3.5 CSV Field Reference
The first row of your file must contain column headers. Keep each issue on a single line; line breaks inside a cell are not supported.
| Jira field | What to enter |
|---|---|
| Issue Type (required) | An issue type in the project, such as Task, Story, Bug or Subtask |
| Summary (required) | Plain text; becomes the issue title |
| Description | Plain text |
| Priority | Highest, High, Medium, Low or Lowest |
| Assignee | The user’s Jira account ID, not their email |
| Reporter | The user’s Jira account ID; ignored if the project does not allow setting the reporter |
| Due Date | YYYY-MM-DD preferred; MM/DD/YYYY and DD-MM-YYYY also accepted |
| Labels | Comma-separated, no spaces, such as frontend,urgent |
| Components | Comma-separated names that already exist in the project |
| Fix Versions | Comma-separated names that already exist in the project |
| Parent | The key of an existing Jira issue, such as PROJ-123; required for subtasks |
4. Support and Troubleshooting
For help, email [email protected]. For known issues, see the ImportPilot for Jira page on the Atlassian Marketplace.
Quick checks before contacting support:
- ImportPilot for Jira not in the Apps menu: Ask a Jira administrator to add you to importpilot-users-group and confirm the group has the Use ImportPilot for Jira permission (see 2.1).
- Project not listed: Confirm you have Create Issues permission in that project.
- Cannot continue past Configure: Map one column to Issue Type and one to Summary.
- User field errors: Use the person’s Jira account ID, not their email address or name.