Export / import user stories

Export; Import; User Story

Ksawery Lisinski avatar
Written by Ksawery Lisinski
Updated over a week ago

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).

Prerequisites

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.

  1. Summary:

    • mandatory field

    • name of the story (minimum 2 characters)

  2. Story ID:

    • mandatory field

    • sequential number of the story

    • must be unique within space

  3. Assigned to:

    • optional field

    • only accepts email address (john@example.com)

    • email address must match one of the existing users in the space

  4. Description:

    • optional field

    • text field explaining the purpose of the story

  5. Affected Roles:

  6. Acceptance criteria:

    • optional field

    • text field explaining the criteria to meet for story to be considered done

  7. Status:

  8. 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

  9. Release:

    • optional field

    • lookup to release

    • if filled out, must match the name of the existing release in the Space

  10. 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"

  11. Parent requirement:

    1. optional field

    2. if filled out, must match the Requirement ID (sequential number, unique in a space) of an existing requirement in the Space

  12. System ID:

  13. 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

  14. 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.

Did this answer your question?