Welcome to the new Ranorex Support Portal

Jira integration

Jira is an issue tracking software by Atlassian. It is used for agile project management, which includes test management.

The Jira integration allows you to connect your Ranorex Studio solution to a Jira project. Once the integration is configured Ranorex Studio automatically creates and update Jira issues or you can manually create issues for failed test cases directly from a test report.

On this page, you’ll find out how to set up the integration with the Jira wizard, the difference between manual and automatic Jira issue handling and how to configure the required optional and custom fields.

In this chapter


Watch our on-demand webinar

Mastering Jira Integration: If you prefer video instructions, you can also watch our on-demand webinar. You will see a live demonstration of how Ranorex Studio 9.1, integrates seamlessly with Jira followed by a Q&A with the Ranorex Studio product team.

Setup with the Jira wizard

To set up the integration, you need to use the Jira wizard in Ranorex Studio.

To start it:

  1. With a solution opened in Ranorex Studio, click Tools > Jira integration > Start Jira wizard.

  2. The wizard opens with the Connect to Jira screen. For connection to Jira cloud, enter your Jira URL, Email, API token, and click Sign in.

Note Icon


Your credentials will be saved in the Windows Credential Manager on this machine. Deleting them is explained further below.

  1. Once signed in successfully, click Continue.

  1. From the drop-down menu, select the Jira project you want to link the solution to and click Continue.

On the following screens, you can configure manual and automatic issue handling. The Jira issue types, state values, plus the default, optional, and required fields are all pulled from your Jira project.

  1. If you want to activate manual issue handling, switch on Enable issue buttons in report and select the type of issue that should be created by default. Click Continue.

  1. To activate automatic issue handling, switch on Enable automatic handling and select the default issue type and open/closed states. Click Finish to complete setup.


Jira Configuration File

After you’ve completed integration with the Jira wizard, you are ready to start running tests and creating issues in Jira. First, there are a few Jira options you can configure.

These Jira options are saved in the Jira.jsd configuration file which is stored in the Solution Items folder and contains all information the Jira integration requires to work.


With the Jira integration set up in Ranorex Studio,


Click Tools > Jira integration > Configure integration.


The Configure Jira Integration opens in the projects view under the Jira.jsd.

The configuration integration screen includes two tabs, the Manual issue handling and the Automatic issue handling. In both tabs, you can specify default values for various fields. This configuration will be used when you create an issue by clicking on the button in the report or when Ranorex Studio creates them automatically.

Manual issue handling

In the Manual issue handling tab you can create issues for failed test cases manually from the report.

  1. Variable editor

Click [x] to open the variable editor dialog box. It lists the variables you can enter into the fields and a description for each of them.

For manual issue handling the test report will include a Create Jira issue button next to each failed test case:

  1. Create Jira issue button next to a failed test case in the report.

Clicking it opens the integrated Jira project and the dialog box for creating a new issue. The default issue type (task, story, etc.) was selected in the Jira wizard or in the configuration options of the integration (explained further above). You can also set values for other Jira issue fields in the new issue dialog box.

Automatic issue handling

Automatic issue creation/updating follows the behavior described below. For explanation purposes, suppose we set the issue type to Bug, the open state to To do, and the closed state to Done. The behavior would be as follows:

If a test case fails one of the following actions will be taken:

  • Ranorex creates a new bug issue in Jira and sets it to To do state. By default, the bug issue summary is the test case name and the description is the unique test case tag for identification by Ranorex Studio and automatically attaches the test report from Ranorex Studio. This information allows you and your team to see exactly what went wrong.
  • No action is taken if an open issue with the same test case tag already exists.
  • If a closed issue with the same tag exists, the issue is reopened and set to To do state.

If a test case succeeds:

  • No issue is needed.
  • If an issue with the same test case tag exists, the state of this issue is set to Done, then the issue is closed.
Note Icon


As you can see from the explanations above, automatic handling works by identifying issues by the test case tag. This also works if you include the tag in a manually created issue. If you then switch to automatic handling, Ranorex Studio will also update this issue automatically.

In the Automatic issue handling tab, you can configure that Ranorex Studio creates issues on Jira automatically for each test.

Note Icon


For automatic issue handling, at least one field e.g. Description, must contain the variable $TestCaseTag. Otherwise, Ranorex Studio cannot identify issues automatically. You can find out what type a field is by hovering the mouse over it.

Upload Attachments

  1. To include attachments in the Jira issue, click Add Files. A window opens, where you need to select the files you want to include.

The selected files are listed in the Attachments section. You can delete the attached files by clicking the trash bin located on the right side of the attachment path.

  1. Some field types cannot be configured automatically, which means you need to fill them in manually when you create the issues with the report button. For automatic issue handling, they will remain empty unless you update the issue manually after it’s been created.

Jira Custom Fields

Ranorex supports Jira custom fields. When a Jira project contains custom fields, they show up in the Jira automated integration setup screen. If these custom fields contain dropdown values, Ranorex users can select the appropriate value.

Custom fields that are not dropdowns fields also display, but users will not be able to change these values within Ranorex.

Sign out

Signing out means deleting your Jira credentials from the current machine, i.e. from the Windows Credential Manager.

To do so:

  1. In Ranorex Studio, click Tools > Jira integration > Sign out () and confirm the dialog.

Remove connection to Jira

Removing a connection to Jira means deleting the Jira.jsd file. All configurations will be lost.

To do so:

  1. In Ranorex Studio, click Tools > Jira integration > Remove connection to Jira and confirm the dialog.

Note Icon


When a Jira connection is started, you can switch projects that are under the same connection. You need to sign out to remove the credentials.

If you select Remove connection to Jira, the Jira.jsd file along with the configurations are removed. In this scenario, the Jira credentials remain signed in.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved