Importing from a csv to Jira project

[#1]

Hi

I recently had to do a complex import. After several iterations, I got it right. I would like to share the steps that helped me get the source and destination organised for the import. 

Migration/Data Import:

For anyone familiar with data migration in the context of Jira/Database/ Excel, etc there are basically two key areas.

• Input Source
• Output (Destination where data needs to be imported)

In my example where the import was done from a csv file to a new Jira project, the steps I followed in a successful/clean import (after having several hiccups without a process ) are below:

• Source Data Review: Understanding your input.
• Destination/Jira Project requirements.
  • Mapping and cleansing input source
  • Prepare destination.
• Test migration.
• Run migration.

 Source Data Review:

• How many rows of data?
• What columns/fields have data and what columns/fields have none. 
• Use Excel formula for the column to identify this.

=COUNTA(A2:A101).

This is to count all non-empty cells between A2 and A101, assuming you have 100 rows of data.

• Identify the Issue Types
• Identify the statuses
• Identify the labels, components, Fix versions

Just understand your input data. It will help you with making decision for migration.

 Destination/Jira Project requirements:

• What fields I need to import to my Jira project? This is the first question you want to answer looking at all the fields that have one or more values in the CSV file.

•  Does the field add value? This is the good opportunity to not carry over data that is not required. I did not migrate watchers, assignee, estimates etc, as that were not of value to my requirement.

• Delete the columns that you do not require. This will help keep your CSV clean and lean. Otherwise there will be so many columns to work with.

• One easy way to review the columns to copy the row which has the column name and paste in a new tab with Data transpose. This will list the fields in a single column and is more visual to review and decide.

Sample table to do mapping between Source and Destination

Field Name (Source)	Field Name (Target)	Comment
Assignee	Assignee	Do not migrate
Assignee Id	Assignee Id	Do not migrate
Comment	Comment	Migrate
Components	Components	Required components created
Created	Created	Migrate
Creator	Creator	Do not migrate. Delete column
Creator Id	Creator Id	Do not migrate. Delete column

Issue Types mapping:

Example mapping:

Source Issue Type	Target Issue Type
Activity	Task
Bug	Bug
Core Task	Task
Design	Task
Epic	Epic
Improvement	Task
Story	Story
Sub-task	Sub-task
Task	Task

I chose to map the issue types and workflow status and update the source CSV to limit the mapping decisions I need to make at the time of import in Jira.

But you will have an option to make these mapping decisions at the time of import.

Workflow/Status mapping:

Source Workflow Status	Destination Jira Project Workflow Status
Open/Ready	TO DO
In Progress	DEVELOPMENT
Blocker	BLOCKED
Needs Review – UAT	READY FOR UAT
UAT Ready	READY FOR UAT
UAT TEST	IN UAT
In UAT Testing	IN UAT
Need Review – Prod	PRODUCTION VERIFICATION
Client Approved or Closed	DONE

• Update the workflow status/create new workflow in the Jira project to the required set of statuses
• In the source CSV, do a Find and Replace All to match to the required Target Statuses.

Components and Labels

 Options

1. Create components/labels in the project you are importing to or
2. the import process will create the components or
3. a combination of some components created and some not created will work too.

All three options have been tested.

Parent-Child Links 

To import parent-child links, make sure the below fields are selected for import.

Jira sorts and manages the order of Parent-child issues. The file doesn’t have to be sorted by EPIC first.

User IDs

I did not migrate user ids.

HTML Formatted Text

I had issues with importing HTML formatted text initially.

Just leave the ‘Map field value’ unchecked

When this is checked, the import gives you an option to review all values to be mapped for this field. I left this unchecked for all fields. If there is a discrepancy, for example if a status is not present in destination, the import process will force you to map the field to a value that is available.

Image Import

When importing images, Browse Project permission to be allowed as Public for the Jira project where the images are stored at source. There is another option to use Userid, password in the CSV. But I used the Browse projects permission method.

Date format

Choose/update to the right date format setting when you commence the import.

Field to be mapped not available in the list of fields in the dropdown

If you do not see the field, check field configurations, context etc to make sure the field is available for the destination project.

Test Migration:

I ran the import with a small sample to check if images, dates and other values are imported correctly.

I had ‘delete issues’ permission and deleted the issues and re-ran the import few times until I got everything right. But doing the pre-work and mapping helped run the import more smoothly and identify and address gaps easily.

Some useful links

https://support.atlassian.com/jira-cloud-administration/docs/import-data-from-a-csv-file/

https://confluence.atlassian.com/jirakb/importing-attachments-via-csv-file-fails-with-exception-1004939288.html

[Dave Mathijs]

Hi @Kavitha Chandrasekaran thank you for laying out the steps and best practices.

What would be the best ways to import Comments from a legacy tool into the Jira issue history?

[Kavitha Chandrasekaran]

Hi @Dave Mathijs I imported the comments to comment body of the Jira issue. It will show as separate comments with the date those comments were previously added. Hope this helps. Thanks!