Import Requirements via Excel Spreadsheets

Starting October 11, 2024 (Zephyr Enterprise 8.2), the Zephyr Enterprise documentation moved from its current location on Atlassian to a dedicated, standalone Zephyr Enterprise documentation page. Please see: https://support.smartbear.com/zephyr-enterprise/docs/en/zephyr-enterprise/zephyr-user-guide/requirements/importing-requirements/import-requirements-via-excel-spreadsheets.html

Important

Only requirements in Excel formats XLS and XLSX are supported.
Only the first tab is imported.
Special formatting is not supported (merged cells, formulas, etc.).
If importing in bulk, all source files should be located on the same machine where Zephyr is installed or on mapped or network drives. If the source files are located on the same machine where Zephyr is installed, then the import process should be run only from a desktop launched on the server machine. If the files are located on mapped or network drives, make sure you have specified the path correctly.
Individual files can be imported from a user's local machine.
Each row must contain data of a single requirement. Three discriminators are supported to demarcate requirements: ID change, requirement name change, and a blank line between requirements.
We recommend that you break large files into smaller ones with no more than 5000 rows for fast importing.

Import steps

You import requirements in four steps:

Prepare an Excel file

You can prepare an Excel file to be imported in two ways:

Create an Excel file and populate it manually.
Export data from a test management tool to an Excel file.

The name of the Excel file will be part of the name of the folder that will contain the imported requirements.

Regardless of the way you created the file, please keep in mind the following when populating or editing your spreadsheet:

Each spreadsheet column must correspond to a requirement field in Zephyr, so, you need to decide to which field each column will correspond. For example, the A column may contain the names of requirements, the B column may contain descriptions, and so on.
To avoid confusion, we recommend that you standardize the procedure of creating such Excel files at your organization.

The sample spreadsheet below contains three requirements with a set of parameters that will be shown in the corresponding fields in Zephyr:

Below is a list of Zephyr fields you can specify values for when populating an Excel spreadsheet:

Field	Description

Field	Description
Name (required)	The name of the requirement.
Description	Addition information about the requirement.
Alt ID	The ID the requirement has in Jira.
Priority	The requirement priority.
URL	Any URL related to the requirement.
Created by	The name of the user who created the requirement.

Map spreadsheet columns to Zephyr fields

Once your Excel file is ready, you can start importing it:

1. Click Requirements in the menu on the left, and then click Import above the list of requirements:

2. In the subsequent dialog, select Excel, and then click Next:

3. Click Add New Map in the Import Requirements dialog to create an Excel map:

4. In the Add New Map section, populate all the required fields (the ones marked with an asterisk):

A list of fields available in the dialog:

Field name	Description

Field name	Description
Map Name	The name of your Excel map.
Starting Row Number	The number of the row to start importing from. For example, there might be some header rows that need to be ignored.
Select Discriminator	Discriminators allow Zephyr to distinguish between multiple requirements in an Excel file. Possible values: By empty row By ID change By requirement name change
Description	Additional information about your Excel map.

The dialog also contains a list of Zephyr fields with empty fields next to them. In these fields, you specify column letters of the Excel file. To map a field to an Excel column, just enter the corresponding column letter in the empty field (see the image above).

Although there is the Attachment field, you cannot import attachments. Just leave the field blank.

After populating the fields, click Save. Zephyr will show the created map on the Import Requirements page. Click Next:

Create a job that will import the data

Now you need to create a job that will import your requirements. To do that:

1. Click Add New Job in the top-right corner:

2. Populate all the required fields in the Add New Job section and attach the Excel file to be imported:

A list of fields available in the dialog:

Field name	Description

Field name	Description
Job Name (required)	The name of your job.
Select Map (required)	The name of the mapping scheme you created earlier when mapping spreadsheet columns to Zephyr fields.
Select file to import (required)	The file whose data you want to import is attached here.
History	The job run history. Populated automatically after the job run.

3. Click Save. Zephyr will show the created job:

Each job has two actions - Run and Delete:

Clicking the Play icon runs the job that will import the data.
Clicking the Trash icon deletes the job.

Run the job

You can now run the job to import the requirements. To do that, click the Play icon. After the job run is over, Zephyr will show the details of the run:

View imported requirements

Now, to view the imported requirements, go back to the Requirements page, click Imported in the tree of requirements, and select the folder with the name of your Excel file. The requirements will be in the table on the right:

You can rename the imported folder, move it to another place, or just drag and drop the imported requirements to any folder in the tree.

Best Practices

Due to the varied nature of the source Excel files and potential inherent format inconsistencies, do not import too many requirements to ensure greater importing success. When confident of the results, import larger groups of requirements.
There might be issues when importing requirements if the Excel files were created manually by multiple users. We suggest standardizing the source files as much as possible to guarantee smooth importing.

Zephyr Enterprise 8.1.0