Setting up the Zendesk Support for Jira integration (Legacy)

Integrate Support with Jira to enhance collaboration between product
and support teams. You can link or create Jira issues from tickets, track
progress, and add custom fields to the issue creation form. Ensure you
have admin permissions, meet installation requirements, and consider
using a dedicated integration user for seamless operations. This integration
supports Jira Cloud, Data Center, and Server.




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


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


See
Using the Jira field syncing feature
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.


See
Using the Jira field syncing feature
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 IP addresses for
your account, as described in
Configuring your firewall for use with Zendesk.


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:


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.


Import the public root CA issuer certificate for
Zendesk into this keystore.

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.