Setting up Zendesk Support for Jira integration

The Jira integration encourages collaboration between product teams and the support team. The Jira v4 integration supports both Atlassian Jira Cloud (OnDemand), Jira Data Center, and Jira Server (OnPremise) version 7x and above.

Topics covered in this article:

• Installation requirements
• Installing and configuring the integration
• Restricting access to the Jira Cloud app
• Adding fields to the Jira app in Zendesk Support
• Using the dedicated integration user option
• Jira Server-specific instructions
• Reinstalling the integration

Related topics:

• Using the Zendesk Support for Jira integration
• Restricting access to projects in your Jira integration
• Updating a ticket when the status of a Jira issue changes

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
• 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 to the list of content exceptions

Installing and configuring the integration

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

1. In Jira, click Apps in the top navigation bar, then select Find new apps.
2. On the Marketplace apps page, search for Zendesk.
3. Locate and click the Zendesk Support for Jira entry in the search results.
4. Click Get app.

   

5. Click Get it now.
6. When the installation success notification modal appears, click Configure.
7. 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.
8. Click Authenticate.
9. A second browser page opens requesting to sign in to your Zendesk account. Enter your login credentials. The page will close.
10. On the app's settings page, select the details to display in linked Jira issues.

    

11. Click Save.
12. If you are using Jira Cloud, you can check the integration works by adding the user add_on_zendesk_for_jira to the group jira-users in the Jira admin.

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

Restricting access to the Jira Cloud app

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

To restrict access to the Jira Cloud app

1. In Admin Center, click Apps and integrations in the sidebar, then select Integrations > Integrations.
2. Under the Currently Installed tab, locate the Jira Cloud app.
3. Hover over the Jira Cloud app. Using the drop-down menu on the right side of the app icon, select Change settings.
4. Under Installation, select the Enable role restrictions? checkbox.
5. Click in the Role restrictions text box, and select the roles that should have permission to use the app.
6. Click Update to save and apply the changes to your settings.

Your teams can now start collaborating using Zendesk and Jira. To find out how, see Using the Zendesk for Jira Cloud integration.

Adding fields to the Jira app 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 a number of default fields:

• Project
• Issue type
• Reporter
• Assignee
• Summary
• Description

These default fields cannot be removed. However, you can include additional fields from Jira in this form, either pre-existing fields, or custom fields.

For more information, see Specifying field behavior on the Atlassian website.

Configuring the issue creation form

You can define which Jira fields the agents sees when creating a new Jira issue from Support, a significant enhancement introduced in the Jira app v4.

These fields are specific to a particular Jira project and issue type. Issue fields defined as "required" in Jira will appear on the form regardless of configurations on this form.

Note: Only Support Admins can configure these fields for their agents.

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 ([e-mail]). 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 in order 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 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

1. In Jira, click Jira settings, then go to Apps > Manage apps.
2. Click to expand the Zendesk Support for Jira app, then click Configure.
3. Click Disconnect to disconnect your subdomain.

   

4. Re-enter your subdomain, and deselect the option to create a dedicated integration user.
5. Click Authenticate to re-authenticate your subdomain.

Jira Server-specific instructions

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:

• 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 information on how to obtain them, see "Getting the IP addresses" in Configuring your firewall for use with Zendesk
  • The Jira integration IP address range (Pod 19) in Getting IP addresses for additional products.
• We strongly recommend using SSL encryption to secure the communication between Jira and Zendesk, especially for 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.
• Make sure that the right port is open (usually 80/8080/443 depending on your SSL settings) on your network for inbound/outbound traffic between Zendesk and Jira.
• When configuring the add-on in Jira, the "Jira Base URL" may not be the same URL you use to access Jira on your private server. The Jira base URL must be a publicly accessible address so Zendesk can use it to make network requests to your Jira instance. You can connect this publicly accessible address to your private server address via NAT or reverse proxy.
• 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 overriding this file in a separate environment may prevent the Jira integration from working.
• The Zendesk addon in Jira needs to run with administrative privileges. We suggest creating a dedicated account as follows and adding it to jira-administrators and jira-software-users groups.

  Full name: Zendesk for Jira

  Username: addon_zendesk

The above username is what the integration looks for by default. In case it doesn’t exist, it will attempt to use the admin account that installed the addon, and if that fail, first available admin account will be used.

Note: If you're having trouble, disconnect and uninstall the Jira integration, then install it again with a user that has 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 (including sandboxes)
• Resestablish your connection between Zendesk and JIRA after restarting your 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

1. In JIRA, navigate to Apps > Manage your apps.
2. Click the Zendesk Support for JIRA accordion, and select Configure.
3. Select Disconnect.
4. Go back to the Manage your apps page, click the Zendesk Support for JIRA accordian, and click Uninstall.
5. Complete the the setup process. See Installing and configuring the integration.