Import Wizard

Learn how to effortlessly migrate from tools like Xray into ATM and keep all workflows intact.

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

Step 1: Select the testing element

In the first step, users have to choose what they want to import:

1. Select the Testing Project and the type of element from this project.

   1. At this moment, users can only import Test Cases.

Permission Checks

If a user does not have Create work item and Edit work item permissions in the project linked with the chosen Testing Project, the corresponding option (e.g. Test Cases) will be disabled and cannot be selected. To learn more about required permissions, visit this page.

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

Step 2: Choose the source tool

In this step, users select from which tool they are exporting data. 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, users need to upload it to Jira Admin Settings:

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

Always ensure the file is saved and maintained in .xlsx format.

3. Export the work items to complete the import.

If additional information is needed, refer to the official Xray documentation:

• Xray for Data Center

• Xray for Cloud

Step 3: Upload the file

Next, the exported file is uploaded to the importer - either by dragging and dropping the file or selecting the file from the disk.

Currently, Import in ATM supports .xlsx files only. The maximum size is 200 kB, with a maximum number of 1000 work items.

Step 4: Map the fields

In this step, users are required to map the columns from the file to Jira fields. The window shows a table, where the names of columns from the import file are displayed in the left column. The second column Field contains a list of dropdown menus, where users 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 project defined in the selected Testing Project, that row is skipped.

• Summary & Description

  • Summary field is required when creating a new work item.

    • If this field is missing, then 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 in that project.

• 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 the user doesn't 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 and not imported.

  • 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 in or any text field users select.

Unsupported fields

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

If you need to import unsupported fields, we recommend:

1. First importing work items to Jira using your usual method (e.g. Jira’s own import).

2. Then importing Test Cases with ATM import wizard to handle test‑specific fields.

Updating existing work items with steps

If users import data for an item that already has Test Steps, then the Import Wizard will create a new version of Test Steps and set them as the default. Previous steps are preserved and users 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 with estimated numbers of work items to be created/updated.

To complete the action, the users have to click Start import button. After this, the import process will begin and run in the background - the updates will be visible in the table. Users can continue working in the app while import completes.

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