Setting up the Zendesk Support for Jira integration

Available on all Suite plans Available on all Support plans

The Zendesk Support for Jira integration encourages collaboration between product and support teams. For example, agents can link or create new Jira issues from a Zendesk ticket. They can then use the link to track the progress made by the product team on addressing the issue.

The integration supports Atlassian Jira Cloud, Jira Data Center, and Jira Server version 7x and above. The integration is not supported on the Jira Cloud mobile app.

This article covers the following topics:

Installation requirements
Jira custom field type compatibility
Installing and configuring the integration
Restricting access to the Jira app in Zendesk Support
Adding fields to the Jira issue creation form in Zendesk Support
Using the dedicated integration user option
Jira Server-specific instructions
Reinstalling the integration

Installation requirements

You must have administrator permissions in both Jira and Zendesk Support to set up the integration.

Additionally, you must meet the following requirements:

Be a member of the jira-administrators and jira-software-users groups.
Have no permission schemes that prevent you from creating or updating projects.
The reporter field is on the Create Issue screen for the respective projects.
Use the Jira Internal Directory as your user directory (applies to Jira Server only).
Atlassian add-ons have permission to access your Jira projects. This is enabled by default. To verify this, check the Project Permissions page for each project in Jira. The various project actions should have a Project Role called Project Role (atlassian-addons-project-access).
Third-party cookies are enabled. However, if third-party cookies need to remain disabled on your system, add jiraplugin.zendesk.com as well as your Jira subdomain to the list of content exceptions.

Jira custom field type compatibility

The Zendesk Support for Jira integration enables you to create a Jira issue from a ticket using the Jira app in Zendesk Support, located in the sidebar of the agent interface. The form used to create Jira issues includes default fields, but Zendesk Support admins can add custom Jira fields to this form.

Refer to this worksheet for a list of the Jira custom field types compatible with the Jira app in Zendesk Support. You can add compatible field types to the Jira issue creation form. You can also add compatible field types to views of linked Jira issues.

Installing and configuring the integration

Note: Before you start the installation, make sure you meet all the installation requirements, including having third-party cookies enabled.

The integration setup process involves installing the Zendesk Support for Jira app in Atlassian Marketplace from your Jira account, then configuring the app.

To install and configure the integration

In Jira, click Apps in the top navigation bar, then select Explore more apps.
On the Marketplace apps page, search for Zendesk.
Locate and click the Zendesk Support for Jira entry in the search results.
Click Get app.
Click Get it now.
When the installation success notification modal appears, click Configure.
Enter your Zendesk subdomain. By default, the Create a new dedicated Zendesk user for this integration checkbox is selected. We recommend using this feature to allow all escalations from Jira to Zendesk Support to not come from the admin who set up the integration, but from the dedicated user. This automatically creates a new admin user in your Zendesk account that is only used by the Jira integration. For more information, see Using the dedicated integration user option.
Click Authenticate.
Click Allow.
A second browser page opens, requesting you to sign in to your Zendesk account. Enter your login credentials. The page will close.
On the app's settings page, select the details to display in linked Jira issues.
Click Save.

In Jira Cloud, the integration creates a free admin user called Zendesk Support for Jira. You can change the avatar of the user on the Profile page.

You can check the integration works by confirming that the Zendesk Support for Jira user appears in a user drop-down field in Jira.

Restricting access to the Jira app in Zendesk Support

If you want to control who has access to the app in Zendesk Support, for example, admins or agents only, you can make the change in Zendesk.

To restrict access to the Jira app in Zendesk Support

In Admin Center, click Apps and integrations in the sidebar, then select Apps > Zendesk Support apps.
Under the Currently Installed tab, click the JIRA app.
Under Installation, select the Enable role restrictions? checkbox to restrict access to the app to specific roles, then select the roles.
Select the Enable group restrictions? checkbox to restrict access to the app to specific groups, then select the groups.
Click Update to save and apply the changes.

Your teams can now start collaborating using Zendesk and Jira. See Using the Zendesk Support for Jira integration.

Adding fields to the Jira issue creation form in Zendesk Support

When creating a Jira issue from a Zendesk Support ticket, you're asked to enter details about the issue being reported in the Create a new Jira issue form:

This form includes several default fields:

Project
Issue type
Reporter
Assignee
Summary
Description

These default fields can't be removed and are specific to the selected Jira project and issue type.

Zendesk Support admins can add pre-existing or custom Jira fields to this form. Adding fields to the issue creation form makes them visible to all agents when creating issues for the selected project and issue type.

Refer to this worksheet for a list of the Jira custom field types compatible with the Jira app in Zendesk support.

To add fields to the Jira issue creation form

In Zendesk Support, go to the ticket you want to use as a basis for a new Jira issue.
Click Create Issue in the Jira app next to the ticket.
In the Project field, select the project.
The Configure fields button appears after you select a project. This button is visible only to Zendesk Support admins.
Select the Issue type.
Click Configure fields.
A drop-down list of available fields displays.
Select the fields to add to the Jira issue creation form.
These fields will be visible to all agents when creating issues for this project and issue type.
Finish creating the issue, as described in Creating a Jira issue from a ticket.
Click Create issue.

Using the dedicated integration user option

If you choose to create a dedicated integration user in your Zendesk Support account, a new, verified admin user (Jira Integration) is automatically created, along with an email address (jira_integration_XXXXXX@jira.zendesk-integrations.com). This user account is fully managed by the integration and will be suspended if the integration is removed.

Note:

The dedicated integration user option requires an available agent seat. While in use, that seat will not be available for other agents.
The admin account who installed the Jira integration and the dedicated integration user must always have admin rights and be active for the integration to function. If you suspend or downgrade the admin account or the dedicated integration user, the integration will not function.

After the authentication and creation processes are completed, the integration service is ready to use. All the commenting and field sync actions will be performed as if they’re done by the dedicated integration user.

If you decide to stop using the dedicated integration user, you can disconnect the integration from the Jira side. When disconnected, Jira will stop using the dedicated integration user. The dedicated integration user in the Zendesk Support account will be downgraded to an end user and suspended. Uninstalling the plugin will also downgrade and suspend the user.

To disconnect the dedicated integration user

In Jira, click Settings, then go to Apps > Manage apps.
Click to expand the Zendesk Support for JIRA app, then click Configure.
Click Disconnect to disconnect your subdomain.
Re-enter your subdomain, and deselect the option to create a dedicated integration user.
Click Authenticate to re-authenticate your subdomain.

Jira Server-specific setup requirements and considerations

While the features and setup processes of the Jira Cloud and Jira Server integration with Zendesk Support are very similar, you need to consider the following when installing on Jira Server:

Zendesk access: Ensure you allow Zendesk to establish a connection to your Jira server by creating an allowlist for the following:
- The IP addresses for your Zendesk account. For more information on obtaining them, see Getting the IP addresses.
- The Jira integration IP address range (Pod 19) described in Getting IP addresses for additional products.
SSL Encryption: We strongly recommend using SSL encryption to secure communication between Jira and Zendesk, especially in production environments. If SSL is enabled, you must have a full SSL certificate stack from a certificate authority. Self-signed certificates are not supported. The intermediate certificate is commonly not installed on the Jira server, which may lead to errors.
SSL certificate issues: If you encounter SSL certificate errors on the plugin configure page (for example, being unable to access jiraplugin.zendesk.com), this may be due to Jira not trusting the Zendesk certificate. To resolve this issue, follow these steps:
1. Locate the Java keystore named cacerts, which Jira uses for trusted Certificate Authorities (CA). It can be found at: %Jira Install%\jre\lib\security\cacerts.
2. Import the public root CA issuer certificate for Zendesk into this keystore.
3. Restart Jira services to apply the changes.
Port configuration: Make sure the correct port is open (usually 80/8080/443, depending on your SSL settings) on your network for inbound and outbound traffic between Zendesk and Jira.
Jira base URL: When configuring the add-on in Jira, the Jira Base URL is publicly accessible. This URL may differ from the one you use to access Jira on your private server. You can connect the public address to your private server through NAT or reverse proxy.
Environment migration: If you configure the add-on in a staging or sandbox Jira server environment and then migrate the environment to production, do not copy the zendesk_plugin.properties file over. Replicating or overwriting this file in a different environment may cause the Jira integration to malfunction.
Administrative privileges: The Zendesk add-on in Jira requires administrative privileges to function correctly. We recommend creating a dedicated account with the following credentials and adding it to the jira-administrators and jira-software-users groups:
- - Full name: Zendesk for Jira
  - Username: addon_zendesk
If this username is not found, the integration will attempt to use the admin account that installed the add-on. If that fails, it will default to the first available admin account.

Note: If you're having trouble, reinstall the Jira integration with a user with admin privileges in both systems.

Reinstalling the integration

Reinstalling the integration is usually required in the following situations:

Changing the integration user
Changing the Jira instance linked to your Zendesk Support account
Changing the Zendesk Support instance linked to your Jira instance (including sandboxes)
Reestablish your connection between Zendesk and Jira after restarting Jira server or clearing the plugin cache

If you are reintegrating the same Zendesk and Jira accounts, your linked issue data remains intact.

To reinstall the integration

In Jira, navigate to Apps > Manage your apps.
Click Zendesk Support for JIRA, then select Configure.
Click Disconnect.
Go back to the Manage your apps page, click Zendesk Support for JIRA, then click Uninstall.
Complete the setup process. See Installing and configuring the integration.