Clone wiki

zfj-importer / Home


Zephyr for JIRA Importer Utility


To know more about ZFJ Importer release, see the Release Notes

Latest Release 0.38 Download

User Guide


This guide will cover how to import tests into Zephyr for JIRA (both Server/DataCenter and Cloud versions) using the Importer Utility; this includes:

  1. Downloading the Importer Utility
  2. Launching the Importer Utility
  3. Configuring fields necessary for importing
  4. JIRA results of an import


Java – Please make sure you have the latest version of Java installed. You can acquire it from if you do not have it already. API Access & Secret Keys (only for Zephyr for JIRA Cloud) – you’ll need your Zephyr for JIRA API access and secret key in order to make a connection. You can find them by logging into your JIRA Cloud instance, browse to Tests (top menu bar) > Importer > API Keys. zfj-importer-topmenu.png

Selecting "API Keys", the Zephyr API Key view will be displayed which contains an Access Key and Secret Key unique to your JIRA user. Also on this view are three options in the top right hand corner:

  • Copy to clipboard which copies both Keys to your system clipboard
  • Delete which removes the current generated Key pair
  • Regenerate which regenerates the Key pair. Note that once the Keys are regenerated the previous Keys can no longer be used with the Importer Utility.


Use the Copy to Clipboard option to save this Key pair to your system clipboard. You will require it before starting the import process in the Importer Utility.

Note the following:

  1. The use of the Access and Secret Keys is required only for Zephyr for JIRA Cloud users. This option in the Test menu is not available in Zephyr for JIRA Server/DataCenter.
  2. For security purposes, do not share this Key pair. Each user that needs to use the Importer Utility should use the steps above to generate their unique Key pair.
  3. This Key pair does not expire so users can use their unique Key pair every time they use the Importer Utility.
  4. Copying to the clipboard copies both Access Key and Secret Key in below format. Paste it to a notepad. Copy each key individually and paste it in its appropriate box in the importer.
  5. “XXXXXXX” in Access Key (First box) and “YYYYYYY” in Secret Key (Second box) of the importer.


Downloading the Importer

The Zephyr for JIRA Importer Utility is available on BitBucket. The direct link for it is This location provides download of the Importer Utility software. Download the Utility software to the system from which imports to Zephyr for JIRA will be run.

Using the Importer

Launching the Importer

To launch the utility double click on the downloaded jar file or run through the command prompt as: java -jar <importer file> which will result in opening a window as shown below.


Note: By default, the Excel tab will be selected in the importer.

Importing from Excel

  • Enter the URL for your JIRA Server or Cloud instance. If importing to Zephyr for JIRA Cloud, make sure the Cloud checkbox is checked. Enter your JIRA username and password. Zephyr for JIRA Server version users, proceed to Step 3.


  • For Zephyr for JIRA Cloud users only: The "ZFJ URL" field is a read-only field and is pre-entered. Enter your API Access and Secret keys (view the "Requirements" section of this document to see how to access this Key pair).


  • Click Connect.

  • Select the project and issue type desired (supported: Test, Bug, Improvement, Task, New Feature)

zfj-importer-4-1.png -> zfj-importer-4-2.png

  • Select a Discriminator and enter Starting Row value.


The Discriminator field is used by the Importer Utility to determine the end of one test case and the beginning of the next test case. It allows one of four options for selection:

  • By Sheet: use this when a test case is listed per excel sheet
  • By Empty Row: use this when an empty row separates consecutive test cases
  • By ID change: use this when a unique test ID exists for each test case to be imported
  • By Test Case Name change: use this when each test case has a unique test case name

Note: to properly determine the Starting row value, reference the excel file to be imported. The Starting row will be the first row in the excel spreadsheet containing a test case. For example, if the first two rows of the excel sheet are headers and the third row is where the first test case is listed, then the Starting row value should be set to 3.

  • Map your Excel spreadsheet columns to your JIRA and Zephyr for JIRA fields. Use the column letters instead of any headers you might have to reference the data. For example: if test case name is in Column B of the excel sheet, enter "B" against the JIRA field “Name” zfj-importer-6.png

If your Excel file has multiple sheets and you wish to import them all, check Import All Sheets.

  • Select the Excel file to be imported by choosing either Pick Import File or Pick Import Folder. zfj-importer-7.png

  • Click Start Import. The results of the import will appear in the log window below. Any errors that occur will be displayed here.