Exporting/importing checklist CSV data

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 https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/3236626499/Checklist+item+representations#JSON-(Jira-REST-API) page.

Importing checklists

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

• The CSV uses Jira’s multi-value format (for more info, see the Jira documentation); and

• Each item follows the Checklist JSON format (for more info, see https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/3236626499/Checklist+item+representations#JSON-(Jira-REST-API)).

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:

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.

Example (Excel file)

Does not work

Open

Works

Open

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.