If your organization uses Zendesk for customer support and JIRA for internal work processes, you can use the Zendesk for JIRA integration to escalate support tickets to JIRA issues, share comments between support agents and JIRA users, and solve Zendesk tickets by solving JIRA issues.
The integration described in this article supports the following tasks:
- Create a new JIRA issue from a Zendesk ticket
- Link a ticket to an existing JIRA issues
- Resolve Zendesk tickets automatically by resolving JIRA issues
- Link multiple Zendesk help desks to a single JIRA account
Zendesk for JIRA uses the Networked Help Desk open standard to synchronize information between Zendesk and JIRA.
Make sure you check out the release notes for the latest updates and known issues.
Setting up Zendesk for JIRA
- Atlassian OnDemand JIRA
Note: If you have OnDemand, a newer version of the JIRA integration is available as a public beta. See Setting up the JIRA integration v3.
- On-premise installations of JIRA 4.3.1, 4.4, and 5.0 to 6.3.x (any 6.3 version).
Installing the Zendesk plugin in JIRA (for on-premise JIRA installations only)
In addition to installing the Zendesk plugin as described below, make sure all of the following apply to your JIRA On-Premise server:
- You white listed the Zendesk public IP addresses listed here. You could run into firewall issues at any time if you don't white list the IP addresses.
- If you're using SSL, have a full SSL certificate stack from a certificate authority. Self-signed certs are not supported. The intermediate certificate is commonly not installed on the JIRA server.
- Make sure that ports 80/8080/443 are open (depending on your SSL settings) on your network for inbound/outbound traffic between Zendesk and JIRA. If you'd like to open only one specific port, you can hard-code the port number in the ticket sharing agreement URL. Example: 123.456.78:5555.
- Click here to download the Zendesk plugin and then unzip the file.
- Copy the contents of the plugin to <JIRA_HOME>/plugins/installed-plugins.
- Restart JIRA.
JIRA 4.4 and 5.0 to 6.3.x - Download the plugin from the Atlassian Marketplace and install it with the Universal Package Manager (UPM). JIRA 4.4 administrators should install version 2.0.3 of the plugin. JIRA 5.0 to 6.3.x administrators should install version 2.2.10 of the plugin.
Creating an application link in JIRA
An application link specifies your Zendesk URL and authorizes JIRA to access your Zendesk account. The link is required to create a connection between JIRA and Zendesk.
- In JIRA, select Add-ons from the Administration () menu in the upper-right corner of the page.
- Click Connections in the sidebar.
- Under Add New Cloud/System Connection, select Zendesk from the External System Type menu, and click Add.
- Click the Manage Application Links link next to the Application Link dropdown menu.
A form to add a new application link appears on the page.
- Enter a name for your application link. We suggest Zendesk Application Link.
- In both the RPC URL and Display URL fields, enter your Zendesk account's URL. Example: http://mysubdomain.zendesk.com.
If you have a host-mapped Zendesk account, enter your host-mapped domain. Example: http://support.mydomain.com. If you have an SSL-enabled Zendesk account, use https:// instead of http:// in your URL. You can check these settings in Zendesk by clicking the Admin icon in the sidebar, then selecting Settings > Account > Branding > Host Mapping. Your SSL settings are in Settings > Security > SSL.
- Click Add. A new application link is created.
- Click the Configure Authentication link under Actions.
- Enter a Zendesk username and API token, and then click Update.
Your username is your email address followed by a forward slash and the word “token”. Example: firstname.lastname@example.org/token. Your password is the encrypted token itself.
Your token is listed in Zendesk under Settings > Channels > API > Edit.
Creating a connection in JIRA
A JIRA connection specifies an application link that gives JIRA access your Zendesk account. A connection also specifies the JIRA accounts you want to associate with your Zendesk account.
- On the Add-ons page in JIRA, click Connections in the sidebar.
- In the Add New Cloud/System Connection section, enter a name for the new connection, select Zendesk from the External System Type menu, and click Add.
We suggest "Zendesk (yoursubdomain.zendesk.com)" as the connection name.
- On the Add New Connection page that follows, select your new application link from the menu and click Add to create the connection.
- On the next page that appears, click Launch Wizard.
- Select the JIRA projects you want to associate with your Zendesk account.
Note: Associating too many projects with your Zendesk account may cause the integration to time out in Zendesk when fetching the projects.
- Select Yes, you would like to automatically associate a Zendesk ticket ID field to your JIRA account.
- Click Create Configurations.
The wizard associates the JIRA projects with your Zendesk account. It also maps the following fields between JIRA issues and Zendesk tickets:
Note: The default field mapping is generated independently of the Yes/No option in the settings.
- JIRA Description - Zendesk Description
- JIRA Summary - Zendesk Subject
Setting up ticket sharing
Zendesk creates new issues and synchronizes comments with JIRA using the same method that allows sharing of tickets between Zendesk accounts.
You must be an administrator in Zendesk to set up ticket sharing.
- In Zendesk, click Manage () at the bottom of the sidebar and then select Tickets.
- Click the Ticket Sharing tab, then click the Add Sharing Invite link.
- Select Atlassian JIRA.
- Configure the sharing agreement as follows:
- JIRA server URL - Enter the address of your JIRA server. Example: https://mydomain.jira.com
- Comment and status permissions - Decide if you want to let JIRA users make public or private comments, and sync status between the JIRA issue and the Zendesk ticket.
- Tag synchronization - Do not select anything from the dropdown. Tag syncing can corrupt the ticket sharing agreement and cause the integration to break.
- Click Send Invite.
- Sign in to JIRA as an administrator, select Add-ons from the Administration () menu in the upper-right corner of the page, and click Connections.
- Click the Ticket Sharing link of your Zendesk connection.
- Click Accept.
- Set any of the following sharing options in the ticket sharing agreement and click Update.
- Project and Issue Type - The default JIRA project and issue type created if a ticket is automatically shared with JIRA (Zendesk Enterprise customers only)
- Default Reporter - You must enter a valid JIRA username for a JIRA admin user or the integration will not work. This is the JIRA username used for the reporter field when a JIRA issue is created. The JIRA admin user must have full access permissions -- Developer, Admin, owner, and user -- for the projects that JIRA shares with Zendesk.
- Allow public comments - Leave unchecked to force all JIRA comments to be private comments when sent back to Zendesk
Testing the connection
After you set up ticket sharing, you can test the connection between JIRA and Zendesk.
- If you're not already on the Connections page in JIRA, login to JIRA as an administrator, select Add-ons from the Administration () menu in the upper-right corner of the page, and click Connections.
- Locate your connection in the list and click the Test link under Actions.
You should get a "Connection successful” message.
Installing the JIRA app in Zendesk
The final setup step is to install the JIRA app in your Zendesk.
- In Zendesk, click Manage () at the bottom of the sidebar and then click the Browse link under Apps.
- Click the JIRA icon and then click Install App on the upper-right side of the page.
- Enter a title for the app and click Install.
- Refresh the browser so that your Zendesk recognizes the new app.
- In Zendesk, go to the ticket you'd like to share as a JIRA issue, and then select the JIRA agreement from the Share menu in the ticket properties panel.
- When the JIRA App panel opens on the right, select your project and issue type, or paste a JIRA story ID to share the ticket with a specific story.
Note: If you have a large number of JIRA projects associated with your Zendesk account, the integration may time out in Zendesk after ten seconds when it tries to fetch all the JIRA projects. A workaround is to reduce the number of associated JIRA projects.
- Update your ticket as needed, then click Submit.
Submitting the ticket shares the ticket information with JIRA. The Zendesk ticket header indicates that the ticket has been shared with JIRA. The sidebar app also indicates the shared JIRA issue ID, resolution, and current assignee.
Tip: Right-click the issue ID in the app sidebar to open it in JIRA in a new tab.
In JIRA, an issue is created with all the comments from the Zendesk ticket as well as the subject and original description.
Syncing comments and status
By default, any comment you enter in a JIRA issue is synced automatically to the shared Zendesk ticket.
For example, here's a new comment for an issue in JIRA:
The comment appears Zendesk and retains the JIRA username:
In addition, selecting any resolution in JIRA solves the Zendesk ticket. In the following example, somebody resolves an issue in JIRA:
As a result, the status of the shared ticket in Zendesk is set to Solved:
Custom field mappings
- JIRA Description - Zendesk Description
- JIRA Summary - Zendesk Subject
Moving Zendesk-linked JIRA issues between JIRA projects
If you move the JIRA issue to a project that's not associated with your Zendesk connection through a mapping scheme, you need to add the project to that mapping scheme.
- In JIRA, select Projects > [Your Project], and then click Administer Project on the upper-right side of your project page.
- In the project sidebar, click Project Mappings.
- Select the mapping scheme for your mapping.
Connecting to multiple Zendesk accounts
If you use multiple Zendesk accounts, you can create a separate connection to each Zendesk account using separate project mappings. For each Zendesk account you want to connect, follow the setup steps in this guide.