Getting Started

QuickTaskImport is a Jira app that allows you to bulk import tasks from a CSV file directly into your Jira project. Unlike external tools, it runs natively inside Jira, so there's no need to configure API credentials or manage external connections.

Key Benefits

• No API setup required - Works instantly with your Jira permissions
• Secure - Runs entirely within Atlassian's infrastructure
• Smart mapping - Automatically detects and maps your custom fields
• Preview before import - Review and edit tasks before creating them
• Import history - Track all your imports with direct links to created issues

---

Installation

1. Install QuickTaskImport from the Atlassian Marketplace
2. Once installed, access it from your Jira project sidebar or the Apps menu
3. Start importing immediately - no additional configuration needed!

---

CSV File Structure

How It Works

• Each row = One Jira issue/task
• Each column = A field of the issue (Summary, Description, etc.)
• Column order doesn't matter
• Standard field names are flexible, but custom field names must match exactly as shown in Jira

Quick Start

1. Download the CSV template from the app's home page
2. Fill in your tasks following the format guidelines below
3. Upload and preview your tasks
4. Import to Jira!

Example CSV

Issue Type,Summary,Description,Epic,Priority,Assignee,Labels,Story Points
Story,Implement user login,Add authentication flow,User Management,High,,frontend,5
Task,Design database schema,Create ERD for user tables,User Management,Medium,,backend,
Bug,Fix header alignment,Header is misaligned on mobile,,Low,,bug-fix;ui,

---

Supported Fields

Standard Fields

Field	Required	Description
Summary	✅ Yes	The title of the issue
Issue Type	✅ Yes	Task, Story, Bug, Epic, or any custom type
Description	No	Detailed description of the issue
Epic	No	Link to existing Epic or create a new one
Priority	No	High, Medium, Low (or your project's priorities)
Assignee	No	Person responsible for the issue
Labels	No	Tags for categorization
Components	No	Project components
Story Points	No	Estimation points (Story issues only)
Time Estimate	No	Original time estimate (e.g., 4h, 2d)
Start Date	No	Planned start date
Due Date	No	Deadline for the issue
Sprint	No	Target sprint name

Custom Fields

QuickTaskImport automatically detects and supports any custom field available in your Jira project:

• Text fields
• Number fields
• Select/dropdown fields
• Date fields
• Multi-select fields
• And more...

Simply use the exact field name as your CSV column header.

---

Field Format Guidelines

Issue Types

The Issue Type must match exactly what's available in your Jira project:

Example	Notes
Story	Standard Scrum issue type
Task	Generic work item
Bug	Defect or problem
Epic	Large body of work
Tech Task	Custom issue type (if configured)

Time Estimate

Supported time formats:

Format	Meaning	Example	Converts To
h	Hours	4h	4 hours
d	Days	5d	5 days
w	Weeks	2w	10 working days
m	Months	1m	20 working days

Note: Weeks and months are automatically converted to working days.

Invalid formats: 4 hours, 4hrs, 240 minutes

Date Fields (Start Date & Due Date)

Supported date formats:

Format	Example	Notes
MM/DD/YYYY	12/25/2024	US format (recommended)
YYYY-MM-DD	2024-12-25	ISO format
DD/MM/YYYY	25/12/2024	European format

Assignee

You can use any of the following formats:

• Display name: John Smith
• Email: john.smith@company.com
• Account ID: 5d7c2d8e-f4a1-4b2c-9e3f-1a2b3c4d5e6f

The app will attempt to match the assignee from your project's team members.

Labels

Separate multiple labels with commas or semicolons:

• Single label: frontend
• Multiple labels: frontend,urgent,bug-fix or frontend;urgent;bug-fix

Story Points

• Only processed for Story issue types
• Use numeric values: 1, 2, 3, 5, 8, 13, etc.
• Fibonacci sequence is common but not required

Priority

Use the exact priority name from your Jira project.

Example:

• Highest
• High
• Medium
• Low
• Lowest

---

Epic Handling

The Epic field allows you to organize tasks under Epics in two ways:

Link to an Existing Epic

Enter the Epic's name (Summary) in the Epic column. The app will search for a matching Epic in your project.

Issue Type,Summary,Epic
Story,Implement login,User Authentication
Task,Write tests,User Authentication

Create New Epics Automatically

If an Epic with the specified name doesn't exist, QuickTaskImport will automatically create it for you.

Issue Type,Summary,Epic
Story,Design homepage,New Website Redesign
Story,Build navigation,New Website Redesign

This creates:

1. A new Epic called "New Website Redesign"
2. Two Stories linked to that Epic

Create Epic as a Standalone Issue

Set Issue Type to "Epic" and put the Epic name in the Summary column:

Issue Type,Summary,Description
Epic,Q1 Product Launch,All tasks related to Q1 launch

---

Smart Field Mapping

QuickTaskImport includes intelligent field mapping that:

1. Auto-detects custom fields - Scans your project for available fields
2. Preview validation - Shows which fields were recognized before import
3. Warnings for unrecognized fields - Alerts you if any columns couldn't be mapped

Important: Custom field names in your CSV must match exactly as they appear in Jira (case-sensitive).

How It Works

When you upload a CSV:

1. The app reads your column headers
2. Matches them against standard Jira fields
3. Searches for custom fields with exact name match in your project
4. Displays the mapping in the preview screen
5. Highlights any unrecognized columns

---

Import Process

Step 1: Select Project

Choose the Jira project where you want to import tasks.

Step 2: Upload CSV

Drag and drop your CSV file or click to browse. The app accepts files up to 5MB.

Step 3: Preview & Edit

Review your tasks before importing:

• See all parsed tasks in a table view
• Edit individual fields if needed
• Check for validation warnings
• Verify field mappings

Step 4: Import

Click "Import to Jira" to create the issues. You'll see:

• Real-time progress indicator
• Estimated time remaining
• Success/failure count

Step 5: Results

After import completes:

• View all created issue keys (clickable links)
• See details of any failed tasks with suggestions
• Access your import in the history section

---

Import History

QuickTaskImport keeps a record of all your imports, accessible from the home page.

What's Tracked

• Date - When the import occurred
• CSV name - Original file name
• Project - Target Jira project
• Importer - Who performed the import
• Results - Success/failure counts

Viewing Created Tasks

Click on any import record to expand it and see:

• Tasks created - Clickable links to all issues created in that import
• Links open in a new tab for easy navigation

---

Troubleshooting

Common Import Errors

"No valid tasks found in CSV"

Cause: The Summary column is missing or empty.

Solutions:

• Ensure you have a column named "Summary"
• Check that Summary values are not empty
• Verify there are no hidden characters in headers

"Issue type not supported"

Cause: The issue type doesn't exist in your project.

Solutions:

• Check exact spelling in your Jira project settings
• Verify the issue type is available for your project
• Use standard types: Task, Story, Bug, Epic

"Epic creation failed"

Cause: Your project doesn't support Epic issue types.

Solutions:

• Leave the Epic column empty to skip Epic linking
• Contact your Jira admin to enable Epic issue type
• Use an existing Epic name instead

Field-Specific Issues

Story Points Not Importing

Cause: Story Points field not configured for Story issues.

Solutions:

1. Go to Project Settings → Issue Types → Story
2. Ensure Story Points field is added to the screen
3. Contact your Jira admin for configuration help

Assignee Not Found

Cause: User doesn't exist in the project or name doesn't match.

Solutions:

• Verify the user has access to the project
• Try using the exact display name from Jira
• Leave empty and assign manually after import

Custom Field Not Found

Cause: Field name doesn't match or isn't available.

Solutions:

1. Check the exact field name in Jira (go to issue → find field)
2. Verify field is available for your issue type
3. Check field permissions

Performance Tips

Large Imports

For best results with large CSV files:

• Split files into batches of 50-100 tasks
• Import during off-peak hours
• Check your network connection

Partial Success

If some tasks fail:

1. Review the error details in the results screen
2. Note the specific issues for each failed task
3. Fix the problems in your CSV
4. Re-import only the failed tasks

---

Getting Help

Built-in Guide

Access the in-app guide by clicking "Look at the guide" on the home page. It covers:

1. General instructions
2. Epic behavior
3. Smart mapping
4. Preview and modify
5. Field format guidelines

Error Details

When tasks fail to import, QuickTaskImport provides:

• Error message - What went wrong
• Suggestion - How to fix it
• Task details - Which task was affected

Support

For additional help:

1. Check this documentation
2. Test with our CSV template
3. Contact your Jira administrator for project-specific questions
4. Visit quicktaskimport.com for more resources

---

Quick Reference

Minimum Required CSV

Issue Type,Summary
Task,My first task
Story,Implement feature X
Bug,Fix login issue

Full Example CSV

Issue Type,Summary,Description,Epic,Priority,Assignee,Labels,Story Points,Start Date,Due Date
Story,User authentication,Implement OAuth 2.0 login,Security Features,High,John Smith,backend;security,8,01/15/2024,01/30/2024
Task,Setup CI/CD pipeline,Configure GitHub Actions,DevOps,Medium,,infrastructure,,,02/15/2024
Bug,Memory leak in dashboard,Dashboard crashes after 1 hour,Performance,Highest,Jane Doe,bug;urgent,3,,01/20/2024
Epic,Q1 Release,All features for Q1 release,,High,,milestone,,,03/31/2024