Exporting/importing checklist CSV data

Available since 5.1.0

Checklist is integrated into Jira’s CSV import and export process.

On this page:

Exporting checklists

When exporting a multi-value field, Jira creates a column for each value with the exported field’s name as the column header. To learn more about Jira’s CSV exporting mechanism, see the Jira documentation.

Checklist is no different. If a checklist with three items is exported, the CSV will have a column for each of the three items in JSON format, with the checklist name as the column header.

Each item uses the same JSON structure as in the Enhancing checklists using scripts page.

Global items are included in the CSV export and could cause unexpected results, depending on how and where the CSV is imported later. This is discussed in more detail below.

Importing checklists

Checklists can be imported into Jira in CSV format, as long as:

The CSV file can be generated from Jira, generated from an external source, or manually created. Depending on how and where the file was created, the import process can be impacted.

Importing a file generated from Jira

If the CSV was generated from Checklist 5.1 or above, no issues will result.

If the CSV was generated from a Checklist version prior to 5.1, the checklist values will not be imported, because the multi-column format is not supported.

Importing a file generated from an external source or created manually

In these cases, you will need to write or adapt the contents of the file to use the JSON format. Although it may seem complex at first, most fields can be ignored for simplicity’s sake. The only required field is name, as shown in the examples below:

In Excel

1 {"name":"Item to import"}

In a text file

1 "{""name"":""Item to import""}"

The items will be imported into the checklist in the same order as in the CSV, regardless of whether the rank field is specified or not.

Using line feeds

Although the Jira documentation says that it handles line feeds, JSON ECMA standards cannot handle line feeds inside string values:

To include line feeds in the item names, use \n instead. This also means that if you are using a file generated from an external source, you will need to remember to replace any existing line feeds with \n.

Does not work

Works

Does not work

1 2 3 4 Summary,DoA,DoA "Example summary","{""name"":""Item name 1 >> Item description""}","{""name"":""Item name 2""}"

Works

1 2 Summary,DoA,DoA "Example summary","{""name"":""Item name 1\n>>\nItem description""}","{""name"":""Item name 2""}"

The quotation marks are doubled here because the JSON is in a CSV file.

If the JSON is not formatted correctly, the checklist values will be ignored during the import.
A warning will appear after the import is finished.

Behavior of imported global items

Global items are defined by the globalItemId field within the item’s JSON. The ID is a system-generated value. You can see the ID values when editing the global items:

Importing JSON with a globalItemId value can result in the following outcomes, some of which may not reflect the expected behavior:

Outcome #1: The global item is created with the expected name and values.

This is the desired outcome. Your best chance of achieving this is to import a CSV that was generated from the same Jira instance for the same checklist.

Outcome #2: The global item values are applied to a global item that has a different name.

This means that a global item in the target custom field has the same ID as the global item in the CSV file. This can happen in rare cases when importing global item values to another Jira instance.

Outcome #3: The global item is not imported at all and appears to be missing.

This can occur if no global item with the specified ID exists in the target custom field.


SERVER documentation (On Cloud? Go here.)
Have questions? Contact our Service Desk for help anytime.