Jira has a powerful import tool that can be used for data migrations, even if they are from one project to another within the same instance, called External System Import. This tool is restricted to organization administrators, and can be found by clicking the settings wheel in the top right > System > Import and Export > External System Import.

Please note: External Systems Import is the recommended way to import project data and distinct from the 'import from CSV' option available on the all issues page of a project. 

• One of the main differences between the import tool most people are familiar with and the External System Import is the ability for the External System Import to access and define the issue key of items being created. With the typical import tool, Jira automatically creates issue keys for you, meaning you do not know what a given issue’s key will be before the import is run - which deems all imported items as new items. External System Import, on the other hand, can both create issues and update existing issue keys when a key is given that matches the key for an issue already existing in the project. This is a powerful difference, and many of the transformations described below are contingent on knowing what the issue key, or issue id, will be before you create each issue.

Setting up the External System Import

Navigate to the newly created target project and then to Settings>System>Import and Export> External System Import. Note: the below images and guidance are based on the 'old experience.' 

Select the following defaults when setting up the Import:

• CSV
• CSV source file
• File encoding > UTF-8
• CSV Delimiter > ,
• Import to Project > Target Project
• Email suffix > N/A
• Date format > dd/MMM/yy h:mm a 

Once these options are selected, the External System Import will take the user to a field mapping page, pictured below. 

On this page, Jira will list each column of the CSV on the left-hand side.

• When two columns have the exact same name, the column will only appear once. Whatever mapping is selected will apply to all of the data in all of the columns with the same name. This can be quite useful when mapping a multi-select column that may have many columns in the sheet. However, this of course could give you trouble, so ensuring column names are duplicated only when they should be is important.

You can then proceed down the list of CSV fields and choose to map them to fields in Jira.

• If the data need not be exported according to the data mapping activity, “Don’t map this field” may be selected. Otherwise, an option should be selected in the JIRA field dropdown.
• The checkbox on the far right may be selected to populate a page after this where you can map from the field value in the CSV to some field value option in the selected Jira field.
  • • For fields like Description, where there will be n distinct values for n issues, this is useless (and should not be selected). However, when there are a limited number of distinct values, this can be very useful.
    • It should not be selected for every field with a limited number of distinct values, as it is often unnecessary and mapping manually for every one would be cumbersome, but it is absolutely crucial for things like Status and Issue type.

When the checkbox is marked for a field, a view similar to the below will be populated for each selected field. The below image shows options after marking the checkbox for fields Status and Requirement Type:

In the image above, Requirement type, which was a dropdown field in the source project, has a limited number of distinct values in the CSV. However, even though the Requirement type field in the new instance is also a dropdown list, the target value that has been inferred is just plain-text. Why is that?

• Jira sees dropdown lists, radio buttons, yes/no, T/F as text. 
• Jira will receive the text and make it look like the dropdown or checkbox or radio button matching that text is selected to make you happy. But it’s just text.

This manual value mapping can be helpful for operations in which you are replacing values (Ex. I don’t want to differentiate between User documentation and User requirement anymore, so I’m going to fill the target value for User documentation as “User requirement”), but it will probably be seldom used.

Status, on the other hand, does have a dropdown. Why is that?

• Status is a “special” Jira field that looks like text to you but is actually in Jira’s database as some metadata id.
• Jira knows that mapping Open to “12” (or whatever the id is for the Open status in the target project is) might be a little confusing, so in the dropdown it gives us the text names for every status it has in the target project.
• Other than Status, Issue type is also a “special” field. There are no other “special” fields. These should always be mapped.

External System Import: Jira Fields and Rich Text Fields

How does Jira ingest dropdown, radio button, checkbox, label, component, sprint, rich text, plain text, etc. fields? Just as text. If the text you have in the CSV is what you want in these fields, that’s what will get put into those fields. For rich text fields, Jira will even ingest the formatting you’ve given in the applicable cell (if using Excel). This means that essentially no effort other than making sure the field is mapped correctly is all that is needed for 90% of the fields.

Below we explore for which fields this is not the case.

External System Import: Ketryx Option Fields

For all Ketryx built-in fields that are dropdowns, you cannot just give them the text of the option you want selected. Instead, you should give the Jira importer the field option id. Note that although Introduced in Version and Obsolete in Version are built-in fields that look like dropdowns, their version typing means that they do not require field option ids. Instead, you are able to just give these fields the text of the version name.

So what is a field option id? Imagine two dropdown fields, “Hair color” and “Eye color” with the following text options:

For each possible option for each field, Jira will maintain an id for that option. This id for the option has nothing to do with anything except that field. There are options that appear in both Hair color and Eye color (Brown, Gray), but that does not mean that they have the same field option id. For example:

If you want to have a new ticket you are creating in the import that contains “Brown” for Hair color and “Brown” for Eye color, then the cell value for the Hair color should be “2” and the cell value for Eye color should be “1”.

How do you find the catalog of field option ids for each Ketryx built-in, dropdown field?

All of this information is accessible via the Jira API, in the following format: https://<Instance>.atlassian.net/rest/api/3/field/com.ketryx.app.atlassian__<Built-In Field Name>/option

• Overall, this will be a limited number of fields, depending on data mapping. Where this is most prevalent is the risk scoring fields, such as Initial probability of occurrence, Initial probability of harm, Initial severity, etc. and “type” fields like Requirement type, Software item type, Context etc.
• Implementation tip: If you don't see your items field option ids at the URL, it could be a query limit if there are a lot of other items of the same type in the instance. You could add ?maxResults=50000&startAt=0 to the end of the url to get the full list (50000 is some arbitrary big number)
• Note: When data is imported to Risk scoring fields in Jira, you should use the “Jira field mapping” advanced setting in the appropriate project to read this data in. Ketryx will not read these fields by default. THIS SETTING SHOULD ONLY BE IN PLACE TEMPORARILY. Ketryx cannot write to this field, and therefore cannot overwrite what is in the Jira database. Therefore, edits made in Ketryx to these fields will not persist if Ketryx continues to read from them.
• CAUTION: Ensure there is no data in the Jira database for existing Risks if you are adding more to a project. This setting can be dangerous. Consult with the team before using it.

External System Import: Date Fields

During the setup of the External System Import tool, a date format was defined. The date format given as an example above (dd/MMM/yy h:mm a ), which is the default date format for Jira, should be used when importing to Jira from a Jira export. This is because the comment and attachment fields use this date format and also contain a lot of other information. It is hard to transform the format of these dates that are wrapped with a bunch of other text. Other standalone date fields (Created, Updated, Resolved), however, will not have this date format in a Jira export. These should be transformed to match the date format that was given in the External System Import setup. Unless custom date fields have been added and are being retained, this transformation only needs to occur for the Created and Resolved date fields (which can be mapped to Date Created and Date Resolved in the External System Import wizard, respectively).

The Updated date field, mentioned earlier, does not need to be transformed because it is not even given as an option in the External System Import wizard. Why is that? When you create this new ticket upon import, whatever updated date you give it would be immediately overwritten by the date the importer created the item.

External System Import: User and Team Fields

The External System Import tool does not ingest user and team names. Instead, it ingests ids. These ids are specific to the user and completely disconnected from the Jira project or instance. If you are migrating from one project to another in the same instance, you can just give Jira to ids it gave you upon export to retain Assignees, Reporters, Teams and Commenters. If you are importing from an external tool, you should consider creating a column in your CSV that contains ids for any User fields you intend to fill. User ids that are available in the instance (meaning they have been added to the Jira instance) can be found by accessing Jira’s API:

https://<instance>.atlassian.net/rest/api/3/users/search?maxResults=1000

• Important: The import will default to the logged-in user where it finds that the given User ID does not exist in the instance. To ensure you don’t appear as the Assignee/Reporter/Commenter, you should be logged in with a user like “Ketryx Migration”. Given this user an email like name+ketryxmigration@ketryx.com and ensure that user has the same permissions as your normal account, so that you can use the import tool.

External System Import: Attachments

Jira stores attachments in its database, and you can access the database in the source project via API to attach files to issues being created via import.

Attachments in jira exports will have the following format:

10/Jul/24 9:15 AM;ug:4efee3-1c5-28-893234-7dc2242179999;something.zip;https://<instance>.atlassian.net/rest/api/3/attachment/content/<id>

The format above is Date/Time;User;File name;API call. Luckily this is everything you need! The Date/Time should already be in the correct format (see earlier, the User is already a User Id instead of name (good! Just make sure they are in the new instance if moving instances), a file name we will take as is, and the exact API call the importer needs to grab it and attach it to the issue in the corresponding row of the csv. The only problem is that you can’t just access an API to grab people’s stuff, you need to inject authentication into the url. So you will need to take the url:

https://<instance>.atlassian.net/rest/api/3/attachment/content/<id>

…and transform it to include a user email and API key:

https://carltono%40ketryx.com:<API TOKEN>@<instance>.atlassian.net/rest/api/3/attachment/content/<id>

• The blue text above is the only thing that needs to be inserted. It consists of an email (with the HTML character for @ in emails, %40), a colon to introduce the API token, the full API token, and an actual @ character to direct the call to the appropriate location.

Once you transform the attachment data by inserting this information, that cell is ready for import. You can do this with a script or use an Excel formula like (with [@Attachment] as the cell with the data):

=IF([@Attachment] = “”, “”, CONCATENATE(LEFT([@Attachment],SEARCH("https://",[@Attachment])-1),"https://carltono%40ketryx.com:<API-Token>@",RIGHT([@Attachment],LEN([@Attachment])-7-SEARCH("https://",[@Attachment]))))