---
title: "Importing Tests using Test Case Importer"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/44565062/Importing%20Tests%20using%20Test%20Case%20Importer"
format: markdown
---
Table of Contents
> Macro (toc)
Introduction
You can use the Xray's Test Case Importer to import new or existing tests, preconditions and Test sets Issues from a CSV or JSON source file.
The Test Case Importer follows a wizard-like interface, guiding you through the process which involves:
- preparing data (CSV/JSON) beforehand
- submit the data
- choose the destination project along with some global settings
- for CSV, define the mapping of CSV columns <=> fields in Jira
> ℹ️ **Supported issue types**
> ℹ️
> ℹ️ The Test Case Importer is only able to create or update **tests, preconditions, and test set** issues. If you wish to create or update other types of issues, you should use Jira's CSV importer instead. Note that Jira's CSV importer is not able to handle any Xray-related semantics though.
> ⚠️ **See and try some examples by yourself**
> ⚠️
> ⚠️ Please see a tutorial with working [Examples using Test Case Importer](https://docs.getxray.app/space/XRAYCLOUD/44565495/Examples+using+Test+Case+Importer), showcasing different scenarios, which you can download and try by yourself.
# Accessing the Test Case Importer
Xray provides the ability to import multiple Tests, Preconditions, or Test Sets at once either as a standard user or as a Jira administrator; the user can create or update all those issues types with a maximum number limit of 1000 issues per import.
> ℹ️ **Permissions**
> ℹ️
> ℹ️ Only users who have **Make Bulk Changes** permission will have this option available. The configuration can be found in the *Jira Administration / System*.
> ℹ️
> ℹ️ Additionally, the user will only be able to import data into projects where he has the **Create Issues** permission. This configuration can be found in the *Jira Projects / Project Settings / Permissions.*
## From the top Apps menu
Go to **Apps > Xray**. In the "Xray" side menu, select "Test Case Importer" and then select the format you want to use (**e.g. CSV**).
> Macro (inline-media-image)
> Macro (inline-media-image)
## From within Testing Board in a project
The Test Case Importer is also accessible from within the Testing Board of an Xray-enabled project.
> ℹ️ **If you have the old Jira UI**
> ℹ️
> ℹ️ > Macro (inline-media-image)
> ℹ️
> ℹ️ > Macro (inline-media-image)
# Importing data
## CSV Importing
### Downloadable examples
Please check multiple examples in the tutorial [Examples using Test Case Importer](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565495) (as well as code in GitHub).
### Preparing the source file
The CSV source file must follow some simple rules.
You can name the fields as you wish since they are going to be mapped during the importation process, but there are three mandatory fields that must be mapped:
1. **Issue Id** – a unique identifier for the issue, this field is used to group lines that belong to the same test case or to identify a precondition or a test set.
2. **Summary** – this field is mandatory since Jira doesn’t allow you to create an issue without a summary.
3. **Test Type** – this field defines the test type of each test to import. The test type must match one of the types of the project to which the test is being imported.
Here is an example of a source file as seen in a spreadsheet application:
Here is the same example as seen in a text editor:
> ℹ️ **Importing into multiple projects**
> ℹ️
> ℹ️ The issues can all be imported to the same project or into multiple projects, one column in the source file can be used to define the destination project (either by having its key or id).
> ℹ️ **CSV column delimiter**
> ℹ️
> ℹ️ If you choose the "," (comma) as the CSV column delimiter, then you must use quotation marks around any field that contains commas. The same is true if you use ";" (semicolon) as a delimiter and you want to use them in a field, for example as a list value delimiter (see the example above).
> ℹ️ **Fields with line breaks**
> ℹ️
> ℹ️ If you need to use new lines within a field, for example, in the issue description, then you need to quote the field.
> ℹ️ **<> special marker**
> ℹ️
> ℹ️ The <> special marker removes the values of the field (with the exception of test step fields) where it is specified (only applicable as a valid input of a CSV file).
### Open Test Case Importer
Open Test Case Importer and select CSV format.
### File Import step
Provide the source file and settings regarding the file to import.
- An existing configuration file saved from the last import made with this file or a similar one.
- The file encoding is used in the CSV source file; this is especially important when the file contains non-ASCII characters. The supported encodings can be seen [here](https://encoding.spec.whatwg.org/#concept-encoding-get).
- The CSV delimiter is the column delimiter used.
### Setup step
Additional setup information, for choosing the destination project along with some settings related to the source data.
- The default project to which the tests will be imported into. Tests without project information will be imported into the project defined by this field.
- The list value delimiter is the delimiter used for fields that are lists of values.
- Date format is used to parse the fields that represent dates, refer to [this page](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44570389) for help on how to define a valid format.
- Flag indicating if Test Repository folders should be created automatically if they do not exist.
### Map fields step
During this step, you'll define the mapping of columns to Jira/Xray fields.
There are three mandatory fields that must be mapped: Test ID, Summary, and Test Type.
Besides these ones, if you have defined additional fields as mandatory for Test issues, then you will also need to specify their mapping.
#### Project field
The project to which the test will be imported can be defined for each issue in a field. The fields "Project Key" or "Project Id" can be used for this.
If no project field is mapped or when the value in this field is empty, the project selected in the Setup step will be the one which these issues will be imported into.
#### Issue Key field
To update existing issues, your CSV file needs to contain a column that maps to the Issue Key. If an issue exists for a given key, it will be updated.
#### Issue Type field
The type of the issue being imported. The supported issue types are:
- Test ("test" case insensitive)
- Precondition ("precondition" case insensitive)
- Test set ("testset", "test_set" or "test set" case insensitive)
If no issue type is defined for an issue being imported, it will default to test. When updating issues, the field can be left empty on the CSV file.
#### Test Type field
The type of the Test being imported. Must be filled for a Test in your CSV file, when creating one, and can be left empty when updating an existing Test.
#### Precondition Type field
The type of the Precondition being imported. Must be filled for a Precondition in your CSV file, when creating one, and can be left empty when updating an existing Precondition.
#### Precondition Specification field
The "Steps", "Definition" or "Background" of a manual, generic or cucumber Precondition type, respectively.
#### Preconditions field
Only for test issues, a list of preconditions to which a test will be added.
Each value should be the issue key of an existing precondition or the ID of a precondition also being imported ("Test ID" field).
#### Test Sets field
Only for test issues, a list of test sets to which a test will be added.
Each value should be the issue key of an existing test set or the ID of a test set also being imported ("Test ID" field).
#### Test Repository Folder field
The Test Repository folder path to the folder in which the Tests will be associated.
The folder path consists of folder names separated by the "/" character, for example: *Main Tests/Sub Tests 1/Inner Tests 2*
#### List fields
List fields can hold multiple values separated by the list delimiter defined in the Setup step.
#### Link fields
Links can be created between imported tests and other existent issues using the "Link ..." Jira fields. Only applicable when creating a test.
The field is a list field and the value of the respective field should hold a list of the issue keys of the issues to link to the test.
The direction (inward/outward) can also be specified.
> ℹ️ **Issue links limit**
> ℹ️
> ℹ️ Due to technical restrictions, there is a limit to the total amount of links the import file can have. The limit is 2000 issue links apart from the first one in every test.
> ℹ️ In other words, every test in the import file can have an issue link defined,and every additional issue link after that one, added up can be no more than 2000.
> ℹ️ An error will be shown if this limit is exceeded.
#### Datetime fields
Datetime fields must have values that can be parsed using the Datetime format in the Setup step.
[This page](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44570389) explains possible date formats and respective values.
#### Test step fields
You can also map columns to test step fields for manual tests.
The fields are in the group "Xray Test Step Fields".
> Macro (inline-media-image)
The configured test step fields for every project in the instance is shown here and the ones that are required are shown with a "*".
#### Unstructured Definition field
The "Definiton" of a generic Test type.
#### Gherkin Definition field
The "Scenario/Scenario Outline" of a cucumber Test type.
After this step the import process will start.
## JSON importing
### Preparing the source file
The JSON source file must have the same structure as the one used in the import through the [REST API](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44564857).
Example of one test being created and one existent test being updated in the JSON import format:
Example of one Test Set being created and one existent Test Set being updated in the JSON import format:
Example of one Precondition being created and one existent Precondition being updated in the JSON import format:
### Open Test Case Importer
Open Test Case Importer and choose the JSON file format.
### File Import step
Choose the file having the source data to import from.
### Setup step
Choosing the default project to import into. If each test to import already refers to a project, this field is not necessary to be filled, otherwise you should choose a project.
## Results of the import process
After the import process has begun its status will be periodically updated on the Test Case Importer page. No new import process can be started until the current one finishes.
After the process finishes the result will be visible for about a day and then it will be removed from the page.
Example of 5 tests imported successfully:
You may also download the detailed import results, this is useful to get the issue keys of the imported issues and also to see which issues were not imported and why.
Example of 2 issues imported out of 5:
Example of detailed import results:
In the detailed import results, the `elementNumber` field represents to which issue the information corresponds (elementNumber 0 being the first issue).
When importing tests into Test Repository folders, if for any reason the process is unable to create a folder or move a test to the respective folder, the respective tests will still be migrated and a warning detailing the situation will be written to the import result.
## Configuration file
When importing a file, when the import status is being shown, you can download the configuration file that will have all the settings you've set:
And then you can use it when you import the next file (if the configurations are supposed to be the same or similar):
# Learn More
- [TTI Migration: Examples Using Test Case Importer](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565495)
- [Importing TestLink Test Cases Using Test Case Importer](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565518)
Support/Troubleshooting
If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44577312).