Getting Started with QuickTaskImport

Setting Up Jira API Credentials

To create your Jira API credentials, we recommend first reading the official Atlassian Support documentation:

Official Guide: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/

Creating Your API Token

1. Go to your Atlassian account security page: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a descriptive name (e.g., "QuickTaskImport Import Tool")
4. Set an expiration date (we recommend the maximum of 1 year)
5. Click "Create"

Important: Save your API token securely and privately. You won't be able to see it again after creation.

Required Information for QuickTaskImport

You'll need these details to configure the import:

• Jira Base URL (e.g., https://yourcompany.atlassian.net)
• Email Address (your Atlassian account email)
• API Token (the token you just created)
• Project Key (e.g., "PROJ", "DEV", "SCRUM")

---

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
• Field names must be in English and match exactly what's used in Jira
• Case sensitive: "Summary" (correct) vs "summary" (incorrect)

Before You Import

1. Download our template (available at the top of the import page)
2. Verify field support - Ensure all fields you want to import are available in your Jira project
3. Check permissions - Make sure you can create issues in the target project

Supported Fields

Standard Fields

• Summary (Required)
• Epic
• Issue Type (Required - supports custom issue types)
• Description
• Priority
• Time Estimate
• Start Date
• Due Date
• Assignee
• Labels
• Story Points (Story issues only)

Custom Fields

• Any custom field supported by your Jira project
• Field name must match exactly as shown in Jira
• Value format must match the field type requirements

Required Fields

Only Summary and Issue Type are mandatory. All other fields are optional.

---

Field Format Guidelines

Issue Types

QuickTaskImport supports any issue type (including custom ones). The text must match exactly what appears in your Jira project.

Examples:

• Story
• Task
• Bug
• Epic
• Tech Task (custom)

Epic Handling

The Epic field links your task to an existing Epic or creates a new one.

Linking to Existing Epic

Simply enter the Epic's name in the Epic column.

Creating New Epics

There are two ways to create new Epics:

1. Create Epic + Task: Set Issue Type to your desired type and fill in the Epic column with the new Epic name
2. Create Epic Only: Set Issue Type to "Epic" and put the Epic name in the Summary column

Time Estimate

QuickTaskImport supports these time formats:

Format	Meaning	Example	Converts To
h	Hours	4h = 4 hours	Stays as hours
d	Days	5d = 5 days	Stays as days
w	Weeks	2w = 2 weeks	Converts to 10d (working days)
m	Months	1m = 1 month	Converts to 20d (working days)

Note: Weeks and months are automatically converted to working days (1 week = 5 days, 1 month = 20 days).

Invalid formats: 4 hours, 4hrs, 240 minutes, 1y

Date Fields (Start Date & Due Date)

We support multiple date formats for your convenience:

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

Assignee

Use the Atlassian Account ID (not username or email).

How to find Account IDs:
Follow this guide: https://support.atlassian.com/atlassian-cloud/kb/get-an-atlassian-cloud-users-account-id/

Example: 5d7c2d8e-f4a1-4b2c-9e3f-1a2b3c4d5e6f

Labels

Separate multiple labels with commas (no spaces after commas).

Examples:

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

Story Points

• Only processed for issues with type "Story"
• Numeric values only: 1, 2, 3, 5, 8, 13, etc.
• Other issue types will ignore this field

Custom Fields

QuickTaskImport supports any custom field available in your Jira project.

Requirements:

1. Exact field name as shown in Jira
2. Correct value format based on field type:
   • Date fields: Use supported date formats above
   • Select fields: Use exact option text from Jira
   • Number fields: Numeric values only
   • Text fields: Any text content

Examples:

• Sprint: Sprint 1
• Team: Frontend Team
• Severity: High (must match Jira options exactly)

---

Troubleshooting Common Issues

Import Errors

"No valid tasks found in CSV"

Cause: The Summary column is missing, empty, or incorrectly named.

Solutions:

• Ensure you have a column named exactly "Summary" (case-sensitive)
• Check that Summary values are not empty
• Verify there are no hidden characters in the column header

"Failed to connect to Jira"

Cause: Incorrect Jira credentials or configuration.

Solutions:

1. Verify your Jira Base URL - Should be https://yourcompany.atlassian.net (no trailing slash)
2. Check your email - Must be the email associated with your Atlassian account
3. Validate API token - Create a new token if unsure
4. Confirm project key - Check your Jira project settings for the exact key
5. Test permissions - Ensure you can manually create issues in the target project

"Epic creation failed"

Cause: Your Jira project doesn't support Epic issue types or you lack permissions.

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 of creating new ones

"Issue type not supported"

Cause: The issue type doesn't exist in your Jira project or is misspelled.

Solutions:

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

Field-Specific Issues

Story Points Not Importing

Cause: Story Points field is not configured for the Story issue type.

Solutions:

1. Check Jira configuration:
   • Go to Project Settings → Issue Types → Story
   • Ensure Story Points field is added to the screen
2. Alternative: Use a different numeric custom field
3. Contact admin: Ask them to configure Story Points for Story issues

Date Format Errors

Cause: Date format doesn't match supported formats.

Solutions:

• Use MM/DD/YYYY format (recommended): 12/25/2024
• Avoid formats like: Dec 25, 2024, 25-Dec-2024
• Check for extra spaces or characters

Custom Field Not Found

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

Solutions:

1. Check exact field name in Jira (case-sensitive)
2. Verify field availability for your project and issue type
3. Check field permissions - you might not have access

Assignee Issues

Cause: Using email/username instead of Account ID.

Solutions:

• Use Atlassian Account ID format: 5d7c2d8e-f4a1-4b2c-9e3f-1a2b3c4d5e6f
• Find Account IDs using Atlassian's official guide
• Leave empty if unsure - you can assign later in Jira

Performance Issues

Import Taking Too Long

Cause: Large CSV files or network issues.

Solutions:

• Split large files into smaller batches (recommended: 50-100 tasks)
• Check your internet connection
• Try importing during off-peak hours

Partial Import Success

Cause: Some tasks failed due to validation errors.

Solutions:

• Review the detailed error report in Step 4
• Fix the specific issues mentioned for each failed task
• Re-import only the failed tasks after corrections

Getting Help

If you're still experiencing issues:

1. Check the error details in Step 4 of the import process
2. Review this guide for field format requirements
3. Test with our template to isolate the issue
4. Contact your Jira administrator for project-specific questions

Error Report Information

When reporting issues, please include:

• The exact error message from Step 4
• Your CSV file structure (headers only)
• Jira project type (Company-managed vs Team-managed)
• Issue types you're trying to create