Import wizard

The import runs through a guided wizard that takes you through the process step-by-step. Below, each step is explained in detail.

Step 1: Select the testing element

In the first step, you need to choose what you want to import:

1. Select the Testing Project and the type of element from this setup.
   • At this moment, you can only import Test Cases.

You will see all Testing Projects in the list, including those marked as Disabled, but you can import only into setups for which you have sufficient permissions.

Step 2: Choose the source tool

In this step, you select the tool you are exporting data from. Currently, the supported source tool is Xray, however, import from Zephyr is a planned feature as well.

How to prepare a file for data import?

1. Download the template.

Start by downloading the pre-configured Excel template provided through the Download template link. This template contains the essential columns and structure expected by the importer.

2. Upload to Jira settings.

Once the template is ready, upload it to Jira Admin Settings:

• Navigate to Jira Admin Settings > Apps > Xray > Document Generator.

3. Export the work items to complete the import.

Step 3: Upload the file

Next, upload the exported file to the importer—either by dragging and dropping the file or selecting it from your disk.

Step 4: Map the fields

In this step, you must map the columns from your file to Jira fields. The window shows a table where the names of columns from the import file are displayed on the left. The second column, Field, contains a list of dropdown menus where you can select target fields for each row.

The wizard will try to auto-map columns based on header names, however, any mapping can be adjusted manually.

Required and supported fields for Test Cases

Below is the explanation of how specific fields are handled:

• Work-key
  • If this cell is empty, the importer will create a new work item.
  • If this cell is filled, the importer will update an existing work item with that key.
  • If the key does not exist, or belongs to a different project than the one defined in the selected Testing Project, that row is skipped.
• Summary & Description
  • The Summary field is required when creating a new work item.
    • If this field is missing, the row will not be created.
  • Description is imported as plain text.
    • ATM supports the description field in the ADF markdown format.
• Priority
  • If the cell is empty when creating a new work item, the project’s default priority is used.
  • If the value does not match any existing Jira priority name, that row is skipped.
• Component
  • If the Component with the given name does not exist in the project, it will be automatically created.
• Reporter
  • If empty, the user performing the import becomes the reporter.
  • If the provided Account ID does not exist in Jira, the row is skipped.
• Assignee
  • If the Account ID does not exist, or you do not have sufficient permissions, the Assignee field is ignored, but the work item is still created/updated.
• ATM Test Type
  • This field must be mapped.
    • Currently, the only accepted cell value is Manual.
    • Rows where this field is empty or has a different value are skipped.
  • Once the Test Type is set for a Test Case, it cannot be changed by later imports.
• Preconditions
  • This field can be mapped to the dedicated ATM Preconditions custom field or any text field you select.
• ATM Repository
  • This field is optional.
  • If the column is not mapped, or if the cell in the file is empty, no value will be set. In such cases, the Test Case will automatically appear in the default All Test Cases folder.

Unsupported fields

At this moment, some fields are not supported for import, such as the Status field or any other Jira field not listed above.

Updating existing work items with steps

If you import data for an item that already has Test Steps, the Import Wizard will create a new version of Test Steps and set them as the default. Previous steps are preserved, and you can clearly see which version came from which file.

Step 5: Summary & starting the import

This is the last step before starting the import. Here, the wizard shows a summary of what will happen, including estimated numbers of work items to be created or updated.

To complete the action, click the Start import button. The import process will begin and run in the background, with updates visible in the table. You can continue working in the app while the import completes.

Once finished, the status will change to Success, Warning, or Failed, and you can use the Work items created/updated links to review the results directly in Jira.