Setting up and using Zendesk with JIRA

Note: A newer version of the integration is available for JIRA OnDemand users. See Setting up Zendesk for JIRA OnDemand integration. The new integration does not currently support on-premise JIRA installations.

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

Zendesk for JIRA supports the following versions of 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.
JIRA 4.3.1 - Install the plugin manually as follows:
  1. Click here to download the Zendesk plugin and then unzip the file.
  2. Copy the contents of the plugin to <JIRA_HOME>/plugins/installed-plugins.
  3. 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.

  1. In JIRA, select Add-ons from the Administration () menu in the upper-right corner of the page.
  2. Click Connections in the sidebar. 
  3. Under Add New Cloud/System Connection, select Zendesk from the External System Type menu, and click Add.

  4. 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.

  5. Enter a name for your application link. We suggest Zendesk Application Link.
  6. 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.

  7. Click Add. A new application link is created.
  8. Click the Configure Authentication link under Actions.
  9. 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: email@zendesk.com/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.

  1. On the Add-ons page in JIRA, click Connections in the sidebar.
  2. 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.

  3. On the Add New Connection page that follows, select your new application link from the menu and click Add to create the connection.

  4. On the next page that appears, click Launch Wizard.
  5. 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.
  6. Select Yes, you would like to automatically associate a Zendesk ticket ID field to your JIRA account.
  7. 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:
    • JIRA Description - Zendesk Description
    • JIRA Summary - Zendesk Subject
    Note: The default field mapping is generated independently of the Yes/No option in the settings.

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.

  1. In Zendesk, click Manage () at the bottom of the sidebar and then select Tickets.
  2. Click the Ticket Sharing tab, then click the Add Sharing Invite link.
  3. Select Atlassian JIRA.
  4. 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.

  5. Click Send Invite.
  6. 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.
  7. Click the Ticket Sharing link of your Zendesk connection.
  8. Click Accept.
  9. 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.

  1. 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.
  2. 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.

Note: If you're using Zendesk Classic, you can skip this section. The app is installed automatically in your Zendesk when you install the Zendesk plug-in in JIRA.
  1. In Zendesk, click Manage () at the bottom of the sidebar and then click the Browse link under Apps.
  2. Click the JIRA icon and then click Install App on the upper-right side of the page.
  3. Enter a title for the app and click Install.
  4. Refresh the browser so that your Zendesk recognizes the new app.

Sharing tickets

Zendesk agents can share tickets as new JIRA issues.
  1. 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. 

  2. 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.
  3. 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.

Note: If you encounter connection issues, make sure that you entered a valid JIRA username into the Default Reporter field on the sharing agreement in JIRA. See Set up ticket sharing.

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:

Advanced tips

 

Custom field mappings

By default, the integration maps the following fields between JIRA issues and Zendesk tickets:
  • JIRA Description - Zendesk Description
  • JIRA Summary - Zendesk Subject
These default mappings are the only mappings officially supported by Zendesk.
Important: While custom mappings may be configured, they are not guaranteed to work. Custom mappings are not supported by Zendesk Support because they can corrupt the ticket sharing agreement and cause the integration to break.

Moving Zendesk-linked JIRA issues between JIRA projects

When you move a Zendesk-linked JIRA issue between JIRA projects, the status display of the JIRA issue in Zendesk automatically shows the updated issue key of the JIRA issue.
Note: The JIRA issue automatically takes on the new mappings of its new project.

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.

  1. In JIRA, select Projects > [Your Project], and then click Administer Project on the upper-right side of your project page.
  2. In the project sidebar, click Project Mappings.
  3. 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.

Note: Each project can be mapped to only one connection at a time. Mapping a project to a new connection removes its association with any previous connection.
Have more questions? Submit a request

Comments

  • Avatar
    JM

    This new integration look great :! This may be helpfull :!

    Just a question, does the attached files are syncs too ?

  • Avatar
    Andy Fleming

    @JeanMarc - Yes it does. I had a couple of tickets in Zendesk and the attached docs showed up in JIRA. Haven't tested the other way though...

  • Avatar
    Anton Marinov

    @ Andy - do you have any issues with projects and assignees pulled from JIRA?

    We updated yesterday, but this affected the JIRA widget, which is used by our Support team to connect with the dev team, so we had to rollback to the older version.

    In fact, I posted a comment here yesterday, however it looks like all the previous comments were removed, which is not nice.

  • Avatar
    Steven Yan

    Hi everyone, let me answer your questions:

    @Jean, we will include links to the Zendesk files attached when the comment is shared with JIRA.

    @Anton, I just checked and you posted in the old JIRA forum, not here.  I will open a ticket for you so we can look at the conflict with the old JIRA widget -- it really should not cause any conflicts as the integrations use completely separate mechanisms for linking tickets.

  • Avatar
    David Hyman

    Is anybody have comment loop problems?

  • Avatar
    Steven Yan

    Hi David, are you seeing comment loop problems?  The ticket sharing protocol we built this on is designed to prevent such loops, let me know where you are observing this.

  • Avatar
    David Hyman

    @ Steven:

    I am getting comment loops, I'm not sure if it's caused by the way we have our Zendesk/JIRA configured. But basically the tickets will keep spawning over and over.

  • Avatar
    David Hyman

    So I figured out why we had a comment loop. I used my login info with a token instead of the user we created to sync JIRA and Zendesk issues. 

    So now all comments made from Zendesk are from our JIRA ZenDesk Sync up user not from the agent from Zendesk. But no comment loops!

  • Avatar
    Jack Baty

    When creating the connection, I selected all projects. This works fine, but raises 2 questions.

    1. How to I include a new project that has been added to JIRA after the connector was added?

    2. Can the project names be sorted alphabetically when sharing a ticket?

  • Avatar
    Andy Fleming

    Re: @Jack's comments, particularly point #2 - it would be nice to be able to specify the order.

    I've got two projects linked at the moment, one active, one on the back-burner.

    Guess which one has set itself to the default? *grin*

  • Avatar
    Thomas Einwaller

    Hi, I am also getting the messages

    Unable to load projects from JIRA

    and

    Unable to load issues types from JIRA

    when I try to share a ticket with JIRA from Zendesk like @Matt - seems like this has something to do with https and Zendesk not being able to validate or certificate 

  • Avatar
    Steven Yan

    Hi everyone, we have fixed the special character issue (ampersands) last week, so that was fixed on the Zendesk side without any of you needing to do anything.

    We also discovered an issue with HTTP vs HTTPS Zendesk accounts and connectivity issues.  You will need to install the new version of the plugin to fix this, we have released version 2.0.1 to the Atlassian Plugin Exchange.

    For those of you who have specific issues, please install the latest plugin and I will be following up with each of you.

  • Avatar
    Damien Evans

    Hi, 

    When we share a ZenDesk ticket to Jira, the ticket description is properly set to the description in JIRA, but it is also added as a comment in JIRA.  One note about this though is that if there are attachments to the Zendesk issue they are included as links in the JIRA comment, but not the JIRA description.

    It would be better to use the Zendesk description for the JIRA description and include links to the attachments there - while not adding the identical comment.

  • Avatar
    Flemming Ottosen

    @StevenYan said: "Hi everyone, we have fixed the special character issue (ampersands as James mentioned) last week, so that was fixed on the Zendesk side without any of you needing to do anything."

    Perhaps the problem is solved for ampersands, but it is still a problem for other special characters. All of the the tickets with subjects containing Norwegian characters in Zendesk gets cut off on the first occurrence of a special character when updating a ticket i Jira. I believe this is a major showstopper for customers in the Scandinavian countries.

  • Avatar
    Aaron

    I'm trying to create an Application Link in JIRA but Zendesk is not coming up as an Application Type.  We have a host-mapped service.  Any ideas?

  • Avatar
    Chris Welford

    I have sent a ticket sharing invitation from Zendesk to JIRA - in fact I sent a couple - and they are sat in Zendesk with the status "pending" - and nothing has appears in JIRA.

    When I view the details of the invitation, against 

    "Entering agreement with"

    there is a blank entry.

    Can I get any diagnostics out of Zendesk about what the problem is?

  • Avatar
    Ken Roberts

    The images in this post don't match with what I see in the real app, and when I try to test the connection it fails.  I'm using hosted jira and hosted zendesk, and I just can't get the connection to work.  Is there an incompatibility right now anyone knows of?

    I get an authentication failure when I click "test" from the connections list.  I've tried any of these combinations:

    1. jira@mycompany.com/token
    2. jira@mycompany.com (password)
    3. me@mycompany.com/token
    4. me@mycompany.com (password)

    Is anyone else getting this problem?  Am I doing something stupid that's obvious to everyone else?

    Thanks.

  • Avatar
    Brad Beaver

    Hello.

    I just got JIRA and Zendesk up and going here and the plugin is almost working 100%.  I have successfully linked JIRA and Zendesk tickets and have been able to create a new JIRA issue from Zendesk too (sweet).  However, the only issue I've ran into so far is the comments are not being synced from JIRA to Zendesk.  The other way works just fine though....adding a comment in the Zendesk ticket immediately populates in the JIRA issue.

    Any pointers or ideas?

    Thanks.

  • Avatar
    Jan Sondergaard

    @Ken Roberts

    If you used Host Mapping (Settings->Account->Branding) you should use the domain when setting up the zendesk integration. Such as support.mycompany.com instead of mycompany.zendesk.com

    Secondly, you should use  jira@mycompany.com/token and then copy in the API token into the token/password field.

    Once I used our Host Mapping, my Test Connection went fine

  • Avatar
    Jan Sondergaard

    @Ken Roberts

    One more thing. Did you specify https:// in the URL for the ticket sharing agreement?

    JIRA @ https://mycopmany.atlassian.net

  • Avatar
    Toni Van de Voorde

    Hi,

    I configured everything correctly. In jira a can even do my mappings on new added fields in zendesk! However when in zendesk I create (or edit) a ticket and I want to share it with jira it does not display any projects to select from?!

    Any idea what the problem is?

    Thank you

  • Avatar
    outaTiME

    In working on jira onDemand, i do all steps ... and all was good auth success but when i try to test connection (in JIRA) ... 

    throws me ...

    Failed to establish connection to remote system 

    No ticket sharing agreement exists between this JIRA instance and the specified Zendesk account 'http://xxx.zendesk.com'

    ideas ?

  • Avatar
    Jeffrey Davidson

    @Toni Van de Voorde

    That's exactly what I'm seeing too. I tried to get this working in Jira 5 (I had plugin issues when trying with Jira 4.3, so this project was put on the backburner until the release of Jira 5) - and everything looks great until I try to share in Zendesk and get a "Could not load projects from JIRA". Doing the tests in Jira check out just fine.

    Is this just a Jira 5 compatibility thing?

  • Avatar
    Steven Yan

    Hi guys, sorry about the errors you are experiencing.  Let me look into your accounts and I will follow-up with each of you.  As for JIRA 5 compatibility, our plugin on the Plugin Exchange is updated with a JIRA 5 compatible version:

    https://plugins.atlassian.com/plugin/details/678489

    You will want to use version 2.1 of the plugin, and please note this is a JIRA 5 only version.  JIRA 4.4.x users should use version 2.0.1.

  • Avatar
    outaTiME

    yup, same issue here version 2.1 of plugin with Jira 5 onDemand, connection issue ... sharing agreements fine in both sides (zendesk / jira) ... 

    "Test Connection" from Jira 5 throws ...

    Failed to establish connection to remote system 

    No ticket sharing agreement exists between this JIRA instance and the specified Zendesk account 'http://outatime.zendesk.com'

  • Avatar
    Toni Van de Voorde

    My problems are solved now thx to zendesk support. They simple recreated all mappings in jira through the wizard and it did the trick. 

  • Avatar
    Matt

    We were just upgraded to Jira OnDemand and are attempting to setup this integration.  We have followed the above steps but are getting an "unable to load projects" and "unable to load issue types" when attempting to share a ticket to a new Jira issue.

    Please help.

  • Avatar
    Du Nguyen

    After installing the plugin we need to reboot the JIRA server, after that the wizard button appears. Hope this is helpful to all who is having issue that i had

  • Avatar
    Jeffrey Davidson

    I found out what was wrong with my setup, too. It turns out if you get an SSL certificate error (as I was just using an IP rather than a DNS entry that matches my cert), you'll just get the "Could not load projects from JIRA" message in Zendesk. So to fix it, I just added a DNS entry, resent my sharing request with the new DNS name instead of the IP, and BAM - it's all working again. Thanks to Zendesk support for finding that our for me.

  • Avatar
    Jackson Chung

    @steven, is there any way to configure the mapping such that it is "conditionally" bi-directional?

    the issue I am running into is when link a zendesk ticket to an existing jira (using the default mappings), the subject and the description of the jira got overwritten, which is not what i want. My use case is jira to zendesk could be 1 to many (though in reality this is many to many), that a bug fix (jira) could be impacting multiple issues (say multiple clients reporting the same bug). So if a jira already exists, I just want to link a new (or even old) zendesk ticket to that jira, without modifying the summary/description. I would still want the zendesk -> jira direction if I am trying to link to a new jira. Thoughts?

    Or any one in the community has a solution to this? Thanks.

    (oh and I too see the description and comment on linking new jira contain the same contents, that's really duplicated, it'd be great to have that fixed)

Please sign in to leave a comment.