You can export and import multiple user stories (or bulk-update existing ones) from a CSV file (you can export a CSV file from any spreadsheet software like Excel or Google Sheets).
You can also import stories directly from JIRA and create stories via API call.
Prerequisites
Export: This can be done by any user.
Import: This can only be done by a user with a requirement manager permission.
Exporting user stories
Any user can export user stories from the grid. You need to click on the "Import/Export" menu item in the toolbar and then select one of the export options. The export file will only contain the user stories that are currently present in the grid, i.e. if you apply any filter only the filtered list will be exported.
There are 2 export options:
Export to Excel file: this format includes all standard and custom fields (all columns)
Export to CSV: this format only includes the standard fields and IDs
When exporting a list of user stories, the linked processes, Salesforce org model items, and additional attachments are not included.
Importing user stories
There are 2 ways to import stories. You can either import stories to a specific requirement or as stand-alone stories.
To import a CSV file with stories for a particular requirement, you must click on "Import from CSV" text button in the stories tab for the selected requirement in the right sidebar.
You can also import stories as stand-alone. Switch to the Stories grid and select the "Import/Export" icon in the upper right corner of the toolbar. You will still be able to choose whether the stories should be uploaded to a specific requirement or if they should stand alone.
CSV file import format for stories import
Only the following fields (columns) should be included in the CSV import file.
The CSV import file must have all the columns listed below, even if some are left blank for stories being imported.
The order of columns in the CSV import file must be the same one as outlined below. We match stories not by field name but by field order during the import process.
Summary:
mandatory field
name of the story (minimum 2 characters, maximum 255 )
Story ID:
mandatory field
sequential number of the story
must be unique within space
Assigned to:
optional field
only accepts email address (john@example.com)
email address must match one of the existing users in the space
Description:
optional field
text field explaining the purpose of the story
Affected Roles:
optional field
lookup to resource collection
must match an existing resource in the Space
Acceptance criteria:
optional field
text field explaining the criteria to meet for story to be considered done
Status:
mandatory field
must match existing statuses in the story workflow
Risk:
optional field
picklist value explaining the level of risk a story poses to the system
if filled out, only accepts values: Low, Medium, or High
Release:
optional field
lookup to release
if filled out, must match the name of the existing release in the Space
Tags:
optional field
does not accept special symbols like = _ > < ! % $ etc.
new tag can be imported but it needs to be a single string of letters and numbers only
multiple tags can be imported but they must not be comma separated, instead they need to be separated by a space, like "Tag1 Tag2 Tag3"
Parent requirement:
optional field
if filled out, must match the Requirement ID (sequential number, unique in a space) of an existing requirement in the Space
System ID:
optional field
system ID can be extracted from the export file
system ID is used to update existing stories with the CSV import (read import rules for explanation)
External ID:
optional field
you can use it to 'tag' stories that come from external system
accepts letters, numbers and "-", for instance "JIRA-123" or "ServiceNow-1121"
must be a single string
Custom fields:
optional: if you have custom fields on your stories, you can include them in your CSV import file. If a custom field is 'required' on a story, you must include it in the import file.
if custom field is filled out, it must support the same data format as the field in the Space. For instance, a 'date' field will only accept numbers, not letters or rich text.
custom fields must be included in the CSV import file in the same order they appear in the setting page.
Import rules
If a story record in a CSV file has the external ID provided, then:
if we can match it to an existing story's external ID (one that was imported before), we will update the existing story;
if we cannot find an existing story with the same external ID, we will create a new story with that external ID.
If a story record in a CSV does not have the external ID provided, then:
if we can match it to an existing story's system ID AND the existing story does not have an external ID, we will update the existing story;
if we can match it to an existing story's system ID BUT the existing story does have an external ID, we will create a new story;
if we cannot match it to an existing story's system ID we will create a new story.
Troubleshooting / FAQ
Here are some common issues that happen with manual CSV imports of stories:
Unnecessary standard fields included:
if you exported list of stories from Elements, then the export file likely contains fields like 'Conflict", "JIRA ID,"JIRA dev project", and maybe others. These fields are not supported in the import and should be discarded.
Wrong data format:
you need to ensure that the data format in the import file matches the expected data in Elements. For instance, users often fill out the 'Assigned to' field with name and surname instead of an email.
Import creates new stories instead of updating existing ones:
consult import rules. This usually happens when system ID is not provided in the import file.
Wrong order of custom fields:
custom fields can be imported with the stories but they must be added as columns 14 and onwards in the CSV file
the order of columns representing custom fields must be the same as they are listed in the settings page.