Setting up Jira Integration

Prerequisite: connection between Zephyr and Jira

In order for Zephyr and Jira to be able to exchange data, they should be accessible to each other via network. This is especially important if you use an On-Premise (Server) instance of Zephyr and a Cloud instance of Jira, or vice versa. To provide the connection, you may need to configure proxies and firewalls working in your network. See Connection Between Server and Cloud Instances.

1. Configure connection to Jira

The connection to Jira that you set up in Zephyr Enterprise can use either OAuth, or Basic authentication (the Basic authentication is called cookie-based authentication in Zephyr UI).

The connection type to use depends on the Jira instance type you use.
Follow the links below to learn how to configure the connection parameters:

Jira Cloud
➡ OAuth authentication

Jira Server / Data Center
➡ OAuth, or
➡ Basic (cookie-based) authentication
_Tip:_{Basic authentication is simpler, but OAuth is more secure.}
^{We recommend using OAuth connections where possible.}

2. Configure your Zephyr project

After you configured Jira connection, you need to map your Zephyr project to a Jira project:

Log in to Zephyr Enterprise as a user with administrator permissions. Then, go to Administration > Project setup settings:
On the Project setup tab, select your project and scroll the page down to the Edit Project section.
In the Requirements & Defect Tracking box, select the Jira connection you created on the previous step:
Choose carefully. Selecting another defect tracker later, after you map Zephyr items to Jira tickets, might be problematic.
Confirm the connection in the subsequent message box:
Zephyr will load a list of projects from your Jira instance and will show it in the Map external Defect project drop-down list (this list is invisible until you select a Jira instance for your project).
Select the Jira project in that list to link it to your Zephyr project:
If later you rename your Jira project, the Jira project will get unmapped in Zephyr and you have to map it again.
Scroll the page down and click Save to save the changes you’ve made.

Congratulations! You’ve mapped your Zephyr project to a Jira project.

When using Jira for defect tracking, the Jira fields on the Create and Edit screens MUST be the same, otherwise users won't be able to properly file/modify defects.

Refer to this Jira resource for more information: Associating a screen with an issue operation | Administering Jira applications Data Center and Server 9.12 | Atlassian Documentation

Note about webhooks

Webhooks are an essential part of Zephyr integration with Jira. They are used to synchronize Zephyr and Jira requirements and information about defects.

Webhooks can be created in two ways:

Zephyr creates a pre-configured webhook automatically when you are mapping a project in Zephyr. In this case, there is no need to perform any additional actions, but you need to have a Jira account with special permissions (for example, Browse Projects). You can view the created webhook in Jira settings: go to ⚙ > System (under Jira Settings) > Webhooks (under Advanced).
Don’t delete this webhook, and don’t change its properties. It has all the needed settings enabled. Later, you can update the webhook, if needed.
You, as an administrator, can create and manage webhooks manually. This can be useful if you do not have (or do not want to create) a Jira service account with permissions required for automatic webhook management.

Further steps

After you set up the integration, you may need to configure certain settings in Jira and to provide better support for Jira custom fields:

➡ Jira Management Preferences