Bulk import of tests into Jira with Xray Test Case Importer - Actonic – Unfolding your potential
We have outsourced our Atlassian licensing and services business to the newly founded Seibert Solutions GmbH. Actonic's products will be further developed under the usual name.

Bulk import of tests into Jira with Xray Test Case Importer


You have set up Xray for the first time, and now you want to import tests in a time-saving way? Or you manage different teams on different Xray instances and want to merge them?

There are several reasons to import a large amount of tests into your Jira instance at once. One method is to do this via the Jira REST API – but this is not the fastest way and highly inconvenient for inexperienced users, as programming skills are required.

The already integrated Jira CSV Importer can be a helpful support if necessary. However, the tool cannot completely solve your problem, as the Jira CSV Importer does not support Xray-specific functions. Therefore, the CSV import via the Xray Test Case Importer is particularly useful for manual tests.

In this article, you will learn how this works quickly, efficiently and easily: Our knowledgeable consultants share their proven expert knowledge.

Don't miss it!

Claim your free consulting session

Unfold your Jira potential with our tailor-made solutions.

Request consultation

What is the Xray Test Case Importer?

The Xray Test Case Importer is a wizard of Xray Test Management for Jira that helps you to import tests from CSV or JSON files. In this tutorial, we show you how to easily master the import of CSV files. If you have any questions about importing with JSON, just contact us – we’ll be happy to help!

Generally, you can also import tests via the REST API, but this is time-consuming and requires some preparatory work and knowledge. The Xray Test Case Importer, however, is an intuitive tool that can save you an immense amount of time and reduce the risk of potential pitfalls.

Xray Test Case Importer or Jira CSV Importer?

In Jira, you also have the option of importing CSV data via the CSV Importer integrated in Jira. These two tools are, of course, suitable for different purposes:

Xray Test Case Importer Jira CSV Importer

can create or update the issue types test, precondition and test sets

can create new issues and import all Jira issue types

especially well suited for manual tests

suitable for all issue types shipped with the system (third party applications excluded)
supports the Xray semantics does not support Xray semantics

You may have already used the Jira CSV Importer to import some tasks. In order to add your predefined tests to your Jira instance, working with the Xray Test Case Importer is unavoidable.

But don’t worry: with these instructions, you will succeed in no time!

Use Xray Test Case Importer for Jira efficiently: Step-by-step guide

Before the import: prepare the CSV file

Before the actual task begins, there are a few things to keep in mind with the CSV file. You can name the fields of your file according to your individual wishes, but make sure to include these following three mandatory fields:

  • Test ID: Unique designation for the operation. This can be used to group rows or identify preconditions for test sets.

  • Summary: In Jira, no task can be created without a summary. Since Xray imports the tests as tickets, a summary is also necessary here.

  • Test type: The test type of the test to be imported is defined here. The types are: Manual, Generic and Cucumber.

Our example shows what a well-structured CSV file can look like that meets all the requirements of the Xray Test Case Importer:

Here, you see the same file displayed in a conventional text editor:

When exporting your CSV file, make sure to choose a separator that optimally separates field values only. We recommend the semicolon “;”.

The import

Step 1: Open your Jira Dashboard, select the app “Xray” and then the Test Case Importer from the menu.

Step 2: After you have decided between JSON and CSV for the import of a CSV file, the following screen appears:

Select your CSV source file and the previously defined separator here. If you do not remember the separator, you can simply look it up in the file by right-clicking on the CSV file → “Open with Editor”.

Usually, it is advisable to use the UTF-8 encoding so that all special characters and umlauts are displayed without errors. However, this is not the case with the Xray Test Case Importer and the format “ISO-8859-1” is necessary to display umlauts correctly, for example.

Step 3: Now, you can select additional setup information:

  • Select the project to import into

  • The delimiter format

  • A date format that will be used to analyze the fields: the main thing to match here is the format from the system settings

  • Whether or not the test repository folder should be created automatically

Step 4: You can now determine the assignment of columns to Jira/Xray fields. The default setting for Jira fields is: “Don’t map this field”, as you can see in the next screenshot.

Making the assignments conscientiously is of great advantage for the clarity of your project. Do not forget to assign the fields “Test ID”, “Summary” and “Test Type”, because these are – as already mentioned – mandatory fields.

If you have defined other mandatory fields in the Issue Type Test in your Jira project, an assignment must also be specified for these.

A possible assignment could look like this:

Then click on “Begin Import” to start the process.

Step 5: During the process, you can track how far the import has progressed.

Step 6: A successful import gives you a screen that looks similar to this

After the import

After the import process is complete, you can display a list of results and, if necessary, edit or save them in order to insert the imported tasks into a test set, for example.

Tests that are to be removed from the project again can simply be deleted via Bulk Change.

You can also check whether all imports have been successfully completed. If not, click on “Click here to download detailed import results”. The JSON file there will then explain where the error was. Then, correct the errors in the CSV file.


This practical guide has shown you how to efficiently import multiple test cases at the same time using the Xray Test Case Importer. One advantage of this method compared to the Jira CSV Importer is that the tool is designed for tests and is intuitive to use.

This way, you can quickly import a large amount of tests into your instance without a high risk of errors. Our consultant tips for uncomplicated test import ensure your success.

If you would like to receive further tips, need support with a migration or want to know how the import works with JSON, simply contact our consultants.

Claim your free consulting session

  • Tailored consulting for your goals
  • Professional software development and implementation
  • Custom training and onboarding plans
Request consultation

How useful was this post?

Click on a star to rate it!

Average rating 5 / 5. Vote count: 1

No votes so far! Be the first to rate this post.