The JIRA integration encourages collaboration between product teams and the support team. The JIRA v3 integration supports both Atlassian JIRA Cloud (OnDemand) and JIRA Server (OnPremise) version 7x.
Topics covered in this article:
- Setting up the integration
- Installing and configuring the integration
- Adding fields to the JIRA app in Zendesk Support
- JIRA Server-specific instructions
- Migrating to JIRA integration v3
Setting up the integration
You must have administrator permissions in both JIRA and Zendesk to set up the integration.
Additionally, you must meet the following requirements:
- You're part of the jira-administrators and jira-software-users groups
- You don't have any permission schemes that prevent you from creating or updating projects
- The reporter field is on the Create Issue screen for the respective projects
Make sure the following requirements are met as well:
- You're using JIRA Internal Directory as your user directory.
- Atlassian add-ons have permission to access your JIRA projects. They should have it by default, but somebody may have changed it. 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. Or, if third-party cookies need to remain disabled on your system, add jiraplugin.zendesk.com to the list of content exceptions.
Best practices for performing the setup
In Zendesk, set yourself up as an administrator with a generic name for performing the setup. For example, create and use a Zendesk administrator called Zendesk Support. For more information, see Managing users. This is important because in the integration, all escalations from Zendesk to JIRA are reported as coming from the Zendesk admin who set up the integration. Setting yourself up as a generic admin ensures that all future escalations are from Zendesk Support, not your personal user account.
The same consideration applies in the other direction, from JIRA to Zendesk. The integration creates a free admin user called Zendesk for JIRA that can be ideal for this purpose (JIRA Cloud only). You can also set yourself up as a JIRA administrator called JIRA Dev or JIRA Product for performing the setup. You can change the avatar of the user on the Profile page, as you would with any other user.
JIRA Service Cloud
If you are using JIRA Service Cloud, to ensure the integration works, add the user add_on_zendesk_for_jira to the group jira-users in the JIRA admin.
Installing and configuring the integration
- In JIRA, select Add-ons from the Administration () menu in the upper-right corner of the page.
- Under Atlassian Marketplace on the left, click Find new add-ons and search for Zendesk.
- After the Zendesk Support for JIRA add-on appears in the search results, click Install in the upper right corner.
- After installing the add-on, return to the Administration page and select Add-ons > Manage add-ons > Zendesk for JIRA.
- Click Configure, enter your Zendesk subdomain, and click Authenticate with Zendesk.
This is the account that will be used for the integration. Consider using a generic admin account, as explained above.
- A second browser page opens asking if you want to grant the add-on permission to access your Zendesk. After granting permission, close the page.
- Return to the original JIRA page and select the details you want to display in linked JIRA issues.
- Click Complete Set-up and Install App.
After confirming that you want to proceed with the installation, the add-on installs an app in Zendesk to support the integration.
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
- In your Zendesk, click Admin > Manage Apps.
- Using the dropdown menu on the right side of the JIRA Cloud app, select Change Settings.
- Select Enable Role Restrictions?, then click Administrator or Agent to grant access to the app to those users with the selected role.
- Click Update to save the changes.
That's it. Your teams can 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:
These default fields cannot be removed. However, you can include additional fields from JIRA in this form
To add additional fields, they need to be set to "required" in JIRA.
For more information, see Specifying field behavior on the Atlassian website.
To add fields to the Create a new JIRA issue form
- In JIRA, click the Administration icon () in the upper-right corner of the page. then select Issues.
- From the left-side toolbar, click Field configurations.
- Click to open the field configuration you want to edit.
- Scroll through the list to locate the field you want to ad to the form, and click Required. This adds it to the Create a new JIRA issue form in Zendesk.
- Repeat for any additional fields you want to add.
JIRA Server-specific instructions
- You need to ensure that you allow Zendesk to establish a connection to your JIRA server from the following public IP addresses listed here.
- We strongly recommend that SSL encryption is used 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.
- 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
Migrating to the JIRA integration v3
If you have the v2 integration, you can migrate issues to the v3 integration and then retire v2.
Tip: To create a list of all shared tickets and issues, see this Support tip from Jeremy Reyes.
To migrate shared issues from the v2 integration
- Open a ticket shared as a JIRA issue with the v2 integration.
- Make sure the Apps panel is open and that both versions of the JIRA app are displayed.
- Using the information about the JIRA issue displayed in the v2 app, create a link to the issue with the v3 app. See Creating a link to an existing JIRA issue from a ticket.
- Unshare the ticket with the v2 app.
After unsharing, the Apps panel should look as follows:
- Repeat the steps for each ticket you shared as a JIRA issue with the v2 integration.
After you're done, you can disable or uninstall the v2 integration.