--- title: "Steps SpreadSheet to Xray format converter tool" canonical: "https://docs.getxray.app/space/XRAY/301700403/Steps%20SpreadSheet%20to%20Xray%20format%20converter%20tool" format: markdown --- > ❌ **Deprecation Notice** > ❌ > ❌ This tool is deprecated and is going to be removed on future versions. > ❌ > ❌ From Xray 2.1 onwards, the preferred way of importing Manual Tests is by using Xray's Test Case Importer, as detailed in [Importing Manual Tests using Test Case Importer](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301695197). For some users, it is easier to create Manual Test definitions in a spreadsheet and then import them to Xray using the import procedure described in [Importing Tests with (CSV)](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/159974140). Xray provides a  **xray-converter** tool to make it straightforward. It converts a CSV, that basically contains the steps definitions, into the generic Jira CSV-compatible import format, which requires all rows to be filled.  > Macro (toc) # Conversion overview 1. Your step definitions must be defined in a spreadsheet that follows a specific format (see table below). You can either use an  file as basis, or adapt your already existing spreadsheet. 2. Then, you may run **xray-converter** to convert the "steps spreadsheet" into the generic CSV format supported by Jira/Xray. 3. Don't forget that in the end, you will have to import the tests using the newly-created CSV file, as described in [Importing Tests with (CSV)](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/159974140). ## Layout of spreadsheet with steps Your spreadsheet must strictly follow this format (: | **TCID** | **Project** | **Region** | **Issue_Type** | **Environment** | **Summary** | **Component** | **Description** | **Reporter** | **Priority** | **Labels** | **Test_Type** | **Step** | **Data** | **Expected_Result** | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | QA Test Repository | AMER | Test | Test | Test Case 1 | App1 | Test Description 1 | Ivaan, Iftekhar: IT (NYK) | Trivial | Java,Test | Manual | Browse to url | [www.bn.com](http://www.bn.com) | BN home page shows | | 1 | | | | | | | | | | | | Click login | | | | 1 | | | | | | | | | | | | Enter Userid | iivaan | | | 1 | | | | | | | | | | | | Enter Password | xyz123 | OK button enable | | 1 | | | | | | | | | | | | Click OK | | Welcome Msg shows | | 2 | QA Test Repository | AMER | Test | Test | Test Case 2 | App1 | Test Description 2 | Ivaan, Iftekhar: IT (NYK) | Trivial | Java,Test | Manual | Browse to url | [www.bn.com](http://www.bn.com) | BN home page shows | | 2 | | | | | | | | | | | | Click OK | | Welcome Msg shows | | 3 | QA Test Repository | AMER | Test | Test | Test Case 3 | App1,App2 | Test Description 3 | Ivaan, Iftekhar: IT (NYK) | Trivial | Java,Test | Manual | Browse to url | [www.bn.com](http://www.bn.com) | BN home page shows | > ℹ️ The **TCID** must be the first column of your spreadsheet and the **Step**, **Data** and **Expected_Result** the last three columns. These columns are mandatory; otherwise, the conversion won't work properly. > ℹ️ > ℹ️ It is also recommended that you always have the **Issue_Type** and the **Test_Type** columns in order to force Jira to create your tests with the correct Issue Type and Test Type. ## Export steps spreadsheet to CSV Export your "steps spreadsheet" to CSV and set your separator type as **;**. You'll now have a file similar to the following output . ```plaintext TCID;Project;Region;Issue_Type;Environment;Summary;Component;Description;Reporter;Priority;Labels;Test_Type;Step;Data;Expected_Result 1;QA Test Repository;AMER;Test;Test;Test Case 1;App1;Test Description 1;Ivaan, Iftekhar: IT (NYK);Trivial;Java,Test;Manual;Browse to url;www.bn.com;BN home page shows 1;;;;;;;;;;;;Clicl login;; 1;;;;;;;;;;;;Enter Userid;iivaan; 1;;;;;;;;;;;;Enter Password;xyz123;OK button enable 1;;;;;;;;;;;;Click OK;;Welcome Msg shows 2;QA Test Repository;AMER;Test;Test;Test Case 2;App1;Test Description 2;Ivaan, Iftekhar: IT (NYK);Trivial;Java,Test;Manual;Browse to url;www.bn.com;BN home page shows 2;;;;;;;;;;;;Click OK;;Welcome Msg shows 3;QA Test Repository;AMER;Test;Test;Test Case 3;App1,App2;Test Description 3;Ivaan, Iftekhar: IT (NYK);Trivial;Java,Test;Manual;Browse to url;www.bn.com;BN home page shows ``` > ℹ️ Make sure you have Java environment installed on your machine and set JAVA_HOME. Detailed instructions are in [https://confluence.atlassian.com/display/CROWD/Setting+JAVA_HOME](https://confluence.atlassian.com/display/CROWD/Setting+JAVA_HOME) # Implementation 1. Copy the CSV with the steps to the ***data/*** subdirectory within the xray-converter folder. 2. Run the xray-converter (see syntax below). 3. Import the issues to Jira using Jira's native CSV import feature. > ℹ️ In **Unix based systems or OS X,** you must use the *xray-convert.sh* executable; in **Windows,** you should use the *xray-converter.bat* batch file. ## Syntax | **Argument** | **Description** | **Example (based on spreadsheet example)** | | --- | --- | --- | | -path | The path to the file to convert | -path ./data/SampleTestCase.csv | | -data | The test step's Data column name | -data Data | | -result | The test step's Expected Result column name | -result Expected_Result | | -step | The test step's Step column name | -step Step | | -attrDelimiter | The delimiter used in the file to separate the different attributes | -attrDelimiter ";" | | -testDelimiter | The delimiter used in the file to separate the different tests to import or please provide the column name. When this cell value changes, it means that the line represents a new Test. | -testDelimiter TCID | ## Examples ### Unix ```plaintext ./xray-converter.sh -path ./data/SampleTestCase1.csv -step Step -data Data -result Expected_Result -attrDelimiter ";" -testDelimiter TCID ``` ### Windows ```plaintext xray-converter.bat .\data\SampleTestCase.csv Step Data Expected_Result ";" TCID ``` > ⚠️ When executing the** xray-converter.bat** file, you do not specify the argument's names, but you must follow the order shown in the example. > ⚠️ When exporting from XLS to CSV, choose the option: "*CSV (comma separated)*". > ⚠️ The test steps in the XLS cannot contain the character " at the end of any line; otherwise, the exported document will be unformatted. > ❌ **Troubleshooting** > ❌ > ❌ If you get an error like > ❌ > ❌ *'C:\Program' is not recognized as an internal or external command,* > ❌ *operable program or batch file.* > ❌ > ❌ it's because Windows is not interpreting the JAVA path correctly. > ❌ > ❌ e.g., > ❌ > ❌ ECHO %JAVA_HOME% > ❌ C:\Program Files\Java\jdk1.8.0_45 > ❌ > ❌ You can fix it by providing JAVA_HOME path with a "" e.g., "C:\Program Files\Java\jdk1.8.0_45" or more radically, copy this folder to C:\jdk1.8.0_45 and change JAVA_HOME to C:\jdk1.8.0_45 # Installation 1. Download **xray-converter** 2. Unzip it to a directory of your choice. > ℹ️ **Archive location** > ℹ️ > ℹ️ New version. Compatible with newlines inside cells ("\n", "\r").