JIRA - Create Issue using CSV

Jira - Create Issues using CSV Import

Jira allows you to efficiently create multiple issues at once by importing data from a Comma Separated Values (CSV) file. CSV files are plain text files that store tabular data, with values typically separated by commas.

The process generally involves three main steps:

• Prepare your CSV file with the issue data.
• Import the CSV file into Jira using the built-in import wizard.
• Optionally, save the import configuration for future reuse, which is highly recommended for recurring imports.

Prepare Your CSV File

Careful preparation of your CSV file is crucial for a successful import. Consider these guidelines:

• Header Row: The first row of your CSV file must be a header row. The values in this row should correspond to Jira issue fields (e.g., Summary, Description, Assignee, Reporter, Priority, Issue Type, Due Date, Labels, Sprint). Example: Summary,Description,Issue Type,Assignee,Reporter,Priority.
• Mandatory Fields: At a minimum, you typically need a Summary field. Depending on your Jira project configuration, other fields like Issue Type and Project Key (if importing into multiple projects via system admin import) might also be mandatory.
• Multi-line Data: To include data that spans multiple lines within a single field (e.g., a detailed description), enclose the entire field content in double quotes ("). For example: "Login issue","This is a detailed description. It spans multiple lines.",Open.
• Special Characters: If your data contains commas, enclose the field in double quotes. If it contains double quotes, escape them by using another double quote (e.g., "He said ""Hello!""").
• User Fields (Assignee, Reporter): For user fields, you can typically use Jira usernames or email addresses. Ensure these match existing users in your Jira instance. Mismatches are a common import error.
• Date Fields: Use a consistent date format that Jira can recognize. The import wizard often allows you to specify the date format used in your CSV (e.g., dd/MMM/yy, yyyy-MM-dd).
• Project Identification: When importing as a Jira administrator, you can specify Project Name and Project Key columns to import issues into specific projects. For project-level imports, issues are typically created in the current project.
• Encoding: Save your CSV file with UTF-8 encoding to ensure proper handling of special characters and international languages.

Example CSV Snippet:

Summary,Description,Issue Type,Assignee,Reporter,Priority,Labels
"Fix login button","User cannot log in when clicking the main login button.",Bug,jsmith,adoe,High,"login,ui-bug"
"Develop new user profile page","Create a new user profile page as per specifications.",Story,cjohnson,adoe,Medium,"profile,new-feature"

Import the CSV File into Jira

The exact steps to access the CSV import wizard can vary slightly depending on your Jira version (Cloud or Data Center) and permissions. Generally, you’ll find this feature in one of two places:

• Jira System Administrators: Look for an option like ‘External System Import’ or ‘CSV Import’ under Jira Administration (usually accessed via the cog icon ⚙️ > System). This allows importing into multiple projects.
• Project Administrators/Users: Within a specific project, you might find an ‘Import Issues from CSV’ option in the project settings or via an ‘Actions’ or ‘More’ menu on the issues page.

Once you’ve located the import wizard, the process typically follows these steps:

Step 1: Setup File Import

• Choose your CSV source file for upload.
• You’ll be asked if you want to use an existing configuration file. If this is your first import or you need a new mapping, do not select this. A configuration file saves your field mappings and settings, which is very useful for repeated imports of similarly structured CSVs.

Previously, you might have seen a page titled ‘Bulk Create Setup’. The modern interface guides you through ‘Setup’, ‘Settings’, ‘Map Fields’, and ‘Map Values’.

Step 2: Settings

• Specify the CSV delimiter (usually a comma ,). If your file uses a different delimiter (e.g., semicolon ;, tab \t), enter it here.
• Indicate the file encoding (UTF-8 is recommended).
• If you’re using an existing configuration file, you might select it here.

This step ensures Jira correctly parses your CSV file structure.

Step 3: Map Fields

• Jira will display the column headers from your CSV file. You need to map each CSV header to the corresponding Jira issue field.
• For example, map your ‘Summary’ CSV column to Jira’s ‘Summary’ field.
• It’s crucial to map the Summary field. Other important fields to map include Issue Type, Assignee, Reporter, Priority, Description, etc.
• Select the ‘Map field value’ checkbox for fields where you want to control how specific data values are translated into Jira values (e.g., mapping a CSV status ‘In Progress’ to Jira’s ‘In Progress’ status, or mapping CSV priority ‘1’ to Jira’s ‘Highest’ priority).

Accurate field mapping is key to a successful import. If a CSV column header perfectly matches a Jira field name, Jira might auto-map it.

Step 4: Map Values (Conditional)

• This step appears if you checked ‘Map field value’ for any fields in the previous step.
• Here, you can define specific mappings for values within those fields. For example, if your CSV has a ‘Priority’ column with values ‘P1’, ‘P2’, you can map ‘P1’ to Jira’s ‘High’ priority and ‘P2’ to Jira’s ‘Medium’ priority.
• For user fields like ‘Assignee’ or ‘Reporter’, if you didn’t select ‘Map Field Value’, Jira will attempt to match usernames or email addresses from your CSV to existing Jira users (case-insensitivity might apply depending on configuration).

This fine-grained control helps align your CSV data with Jira’s specific field options and user base.

Step 5: Begin Import (Validation)

• Before starting the actual import, Jira usually offers a ‘Validate’ option. Clicking this will check your mappings and data for common errors without actually creating issues.
• Review any errors or warnings. Common issues include unmapped mandatory fields, incorrect date formats, or users not found.
• Once validation is successful (or you’ve addressed any issues), click ‘Begin Import’.

Validation helps catch problems early, saving you from a messy import. The system will report how many issues will be successfully imported.

Step 6: Import Completion & Results

• Jira will process the import. For large files, this might take some time.
• Upon completion, you’ll receive a summary of the import, including the number of issues created successfully and any errors encountered.
• You’ll typically have an option to ‘Save the configuration’. This is highly recommended as it saves your field and value mappings to a file, which you can reuse for future imports of similar CSVs, significantly speeding up the process.
• You can also navigate to view the newly created issues.

After a successful import, it’s good practice to check a few of the newly created issues to ensure all data has been imported as expected.

Practical Application Scenarios

• Migrating from another tool: Export tasks from a legacy system to CSV and import them into Jira.
• Bulk-loading a backlog: Gather product backlog items (PBIs) or user stories in a spreadsheet during planning, then import them into Jira.
• Creating repetitive tasks: For recurring project phases or onboarding new clients, a CSV template can be used to quickly generate standard sets of tasks.

Troubleshooting Common Issues

• User matching: Ensure usernames or email addresses in your CSV match exactly with those in Jira. Check for typos or domain differences.
• Date formats: Specify the correct date format used in your CSV during the import wizard. Mismatched formats are a common error.
• Custom fields: For custom fields, especially select lists or multi-selects, ensure the values in your CSV match the available options in Jira, or map them accordingly.
• Required fields: Make sure all Jira project-required fields are present in your CSV and mapped correctly.
• File encoding: Always use UTF-8 to avoid character corruption.

For detailed, up-to-date instructions and advanced options, always refer to the official Atlassian Jira documentation for your specific Jira version (Cloud or Data Center).