Documentation validated against connector build on April 11, 2026

Technical deployment guide for the Zendesk Connector for Jira

This guide covers Marketplace installation, Zendesk Support authentication, Smart Connected Items, sync behavior, and issue-panel operations for enterprise Jira environments.

Marketplace app Forge app Jira admin page Jira issue panel Zendesk Support
Zendesk polling Every 5 minutes

The scheduled sync looks for new and updated Zendesk tickets on five-minute runs.

Jira push events Near real time

Jira issue, comment, and attachment events push eligible changes back to Zendesk.

Attachment limit 10 MB per file

Files above 10 MB are skipped to stay inside Forge runtime and payload limits.

Supported records Tickets, customers, organizations

Tickets support sync flows. Customers and organizations support display-only links.

Fast Path

Quick start in six steps

1

Install the app

A Jira site admin installs the app from Atlassian Marketplace and opens the Zendesk Connector admin page from Jira administration.

2

Prepare Zendesk credentials

Gather the Zendesk subdomain, an agent email address, and a Zendesk API token for the account you want Jira to use.

3

Save the Zendesk connection

Enter the subdomain, email, and token in the Jira admin page. The token is stored securely in Forge secret storage after validation succeeds.

4

Create Smart Connected Items

Choose display-only, one-way sync, or two-way sync behavior, then set Jira scope, Zendesk object, field mappings, and optional sync features.

5

Enable optional sync behavior

For synchronized ticket items you can enable auto-create, status sync, comments sync, and attachment sync.

6

Link or auto-create records

Jira users can manually link Zendesk records from the issue panel, and synchronized ticket items can auto-create Jira issues from new Zendesk tickets.

Architecture

How the connector works

Current sync model in this build

The scheduled trigger runs every five minutes. It can create Jira issues for new Zendesk tickets when auto-create is enabled, and it applies Zendesk-to-Jira updates for mapped fields, status, comments, and attachments on linked tickets.

Jira-to-Zendesk updates are event-driven. Jira issue updates push field and status changes, Jira comment events push comments, and Jira attachment events push new files to Zendesk without waiting for the next scheduler run.

Where configuration lives

  • Zendesk connection settings are stored in Forge app storage.
  • The Zendesk API token is stored in Forge secret storage.
  • Smart Connected Item definitions and issue-to-record links are stored in Forge app storage.
  • Marketplace license checks gate production usage while development installs stay flexible.

How Jira users see the integration

  • The issue panel shows one card per Smart Connected Item that applies to the Jira project.
  • Display-only items wait for a manual link before showing Zendesk fields.
  • Synchronized ticket items can either be manually linked or auto-managed by the scheduler.
  • Linked records can expose field previews, a direct Zendesk link, refresh, and unlink actions.
Object Catalog

Supported Zendesk objects in this connector

Zendesk object Supported flows Notes
Tickets Display-only, one-way sync, two-way sync, auto-create Tickets are the only Zendesk object with the full scheduler and Jira event sync pipeline.
Customers Display-only manual linking, search, refresh, preview Customer search supports partial ID, name, and email matching in the Jira issue panel.
Organizations Display-only manual linking, search, refresh, preview Organizations can be linked and previewed from Jira, but they are not part of synchronized flows.

Why synchronization is ticket-only

The scheduled sync depends on ticket-specific APIs such as incremental ticket export, ticket status, ticket comments, and ticket attachments. Customers and organizations are supported today through the display-only path, not the synchronized scheduler path.

Terminology

Key terms used in this guide

Display-only Smart Connected Item

A manual mapping that lets Jira users link a Zendesk ticket, customer, or organization in the issue panel and view selected fields. It does not auto-create Jira issues or run scheduled field sync.

Synchronized Smart Connected Item

A ticket-only mapping that can create Jira issues from Zendesk and keep mapped fields aligned in one direction or both directions.

Auto-managed link

A link created by the scheduler when auto-create is enabled. Auto-managed records are read-only in the issue panel and can be refreshed but not manually unlinked there.

Initial workflow safeguard

When the scheduler creates a new Jira issue, the connector intentionally keeps that issue in the first Jira workflow status until a later Jira or Zendesk status change occurs. After that, the normal sync logic takes over.

Admin Setup

Install from Atlassian Marketplace

1

Install the app on the Jira Cloud site

Install the Zendesk Connector from Atlassian Marketplace using a Jira site admin account. After installation, open Jira administration and locate the app under the Marketplace apps area.

2

Confirm the license state

Paid and trial environments must have an active Marketplace license. If the license is missing or expired, both the admin page and the issue panel show a license-required message and block normal usage.

3

Prepare Zendesk credentials before the first save

The app will not let you complete setup until you provide a valid Zendesk subdomain, agent email, and API token, so prepare those values before saving the connection form.

Zendesk

Prepare Zendesk credentials

What the connection validates

When you save the admin form, the connector validates the provided subdomain, agent email, and API token by calling Zendesk and confirming the connected agent identity.

1

Choose the Zendesk account

Use the Zendesk Support subdomain for the account this Jira site should connect to, for example your-team from https://your-team.zendesk.com.

2

Create or reuse an agent API token

Use an agent account with permission to read and update the Zendesk records you plan to expose. The connector stores only the token secret, not the agent password.

3

Keep the exact agent email

The admin form expects the full agent email address. The connector uses it with the token to authenticate Zendesk API requests.

Token scope matters

If the Zendesk token or agent permissions cannot read the selected object or update ticket content, the connector surfaces the failing API error in the Jira admin or sync flow rather than silently skipping the action.

Jira Admin

Authenticate in the Jira admin page

Connection form fields

  • Subdomain: the Zendesk Support subdomain without the host suffix.
  • Agent email: the full Zendesk agent login email address.
  • API token: a password-style field stored in Forge secret storage.
  • Save connection: validates the credentials and stores them securely.

Connected-state summary

  • Connected lozenge.
  • Zendesk subdomain, connected agent email, connected agent display name.
  • Stored-securely token indicator.
  • Revoke Connection button to disconnect the account.
Zendesk Connector Jira admin page before connection, showing the subdomain, agent email, and API token fields.
The Jira admin authentication view before Zendesk credentials are saved.
Configuration

Create Smart Connected Items

One admin screen, multiple item types

The Smart Connected Items table lists every configured item, including its sync mode, Jira scope, issue type, Zendesk source, mapped fields, and enabled sync features.

What every item defines

  • A name that appears in the Jira issue panel.
  • A sync mode: none, one-way sync, or two-way sync.
  • A Jira project and optionally a specific Jira issue type.
  • A Zendesk module and object choice.

What synchronized items add

  • Field mappings between Zendesk and Jira.
  • Optional auto-create for new Zendesk tickets.
  • Optional status sync, comment sync, and attachment sync.
  • Warnings when a Jira issue type is missing safe create-field coverage.
Zendesk Connector Jira admin page after connection, showing the connected summary and Smart Connected Items table.
The connected admin view with the connection summary and Smart Connected Items dashboard.
Display-only

Display-only Smart Connected Items

When to use display-only mode

  • You want Jira users to manually link a Zendesk record from the issue panel.
  • You only need a read-friendly preview of selected Zendesk fields.
  • You want to expose customers or organizations, which are not synchronized objects.
  • You do not want the scheduler to create or update Jira issues.

Supported objects in this mode

  • Tickets
  • Customers
  • Organizations
  • Readable option labels and non-empty preview values are rendered in the issue panel.

Field previews are selected by the admin

The issue panel only displays the Zendesk fields you map into the Connected Item. The connector now preserves values by field ID first, which prevents duplicate labels from hiding real values in the preview table.

Synchronization

One-way and two-way ticket items

Tickets only

Only Zendesk tickets are supported for synchronized Smart Connected Items. Customers and organizations remain available through the display-only Connected Item flow for manual linking in the issue panel.

One-way sync

  • Zendesk is the source of truth for mapped fields.
  • The scheduler reconciles Zendesk ticket updates into Jira every five minutes.
  • Optional auto-create can open new Jira issues from new Zendesk tickets.

Two-way sync

  • The scheduler still pulls Zendesk changes into Jira.
  • Jira issue update events push mapped field changes back to Zendesk.
  • Comments, attachments, and status can be synchronized in both directions when enabled.

Initial status protection for auto-created issues

When the five-minute scheduler creates a Jira issue from a Zendesk ticket, the new Jira issue is intentionally kept in the first status of the Jira workflow for that project and issue type. Once the linked items later change status, the normal sync logic resumes.

Create Smart Connected Item modal showing sync mode, Jira project, issue type, module, and Zendesk object selection.
Step 1 of the synchronized item setup flow: choose sync mode and scope.
Create Smart Connected Item modal showing field mappings, auto-create, and status, comment, and attachment sync options.
Step 2 of the synchronized item setup flow: map fields and enable sync options.
Matrix

Sync options matrix

Capability Display-only One-way sync Two-way sync
Manual link in issue panel Yes Yes Yes
Preview selected Zendesk fields Yes Yes Yes
Scheduler pulls Zendesk changes into Jira No Yes Yes
Auto-create Jira issues from Zendesk No Optional Optional
Jira pushes mapped field changes back to Zendesk No No Yes
Status sync No Optional Optional
Comment sync No Optional Optional
Attachment sync No Optional Optional
Manual Refresh action Yes Yes Yes
Platform

Permissions and scope reference

Forge scopes in the manifest

  • storage:app
  • read:jira-work
  • write:jira-work
  • read:jira-user
  • read:issue:jira
  • write:issue:jira

Configured backend egress domains

  • https://*.zendesk.com
  • https://*.amazonaws.com
  • https://*.cloudfront.net
  • https://*.zdusercontent.com
Jira User Guide

Issue panel overview

What users see before linking

  • A card per Smart Connected Item that matches the Jira project.
  • The item name, Zendesk module and object label, and current sync mode.
  • A Link action when no record is connected yet.
  • For synchronized items, a note explaining that linking a ticket starts synchronization.

What users see after linking

  • The linked Zendesk record ID.
  • A preview table of the selected Zendesk fields and their readable values.
  • Open in Zendesk and Refresh actions.
  • Unlink when the record was linked manually, not by the scheduler.
Jira issue panel showing display-only Smart Connected Items before linking, with Link buttons visible.
The issue panel before display-only records are linked.
Jira issue panel showing linked Zendesk customer, organization, and ticket previews with action buttons.
The issue panel after Zendesk records are linked and preview data is available.
User Actions

Link, Refresh, and Unlink

1

Open the Link dialog

Click Link on a Smart Connected Item card. The dialog title and helper copy adapt to the selected Zendesk object type.

2

Search for a Zendesk record

Ticket searches support ticket IDs and partial subject matching. Customer searches support partial ID, name, and email matching. Organization searches support partial ID and name matching.

3

Refresh the linked preview on demand

The Refresh action forces an immediate pull of mapped fields. On synchronized tickets it also re-runs the current comment and attachment sync logic.

4

Unlink only manual records

The Unlink action is available for manually linked records. Links created automatically by the scheduler stay read-only in the issue panel.

Scheduler Behavior

Auto-managed links

What happens when auto-create is enabled

During the five-minute sync run, the connector can create Jira issues for new Zendesk tickets and immediately store a linked-record relation for that Smart Connected Item.

Issue panel behavior

  • The linked Zendesk ticket is shown as read-only in the issue panel.
  • Users can still open the ticket in Zendesk.
  • Users can still run Refresh without waiting for the next scheduler cycle.
  • Users cannot manually unlink the auto-managed record from the issue panel.

Status safeguard

  • New scheduler-created Jira issues stay in the first Jira workflow status initially.
  • This prevents the very first sync pass from skipping that initial status entirely.
  • Once Jira or Zendesk status changes later, the normal sync logic resumes.
  • The safeguard applies only to scheduler-created issues, not to manual links.
Outbound Behavior

What changes in Zendesk

Mapped field updates

  • In one-way sync, Zendesk remains the source of truth for mapped fields.
  • In two-way sync, Jira issue update events can push mapped values back to the linked Zendesk ticket.
  • Priority values are normalized so Zendesk only receives valid ticket priorities.

Status synchronization categories

  • Jira new aligns with Zendesk new.
  • Jira indeterminate aligns with Zendesk open, pending, and hold.
  • Jira done aligns with Zendesk solved and closed.
  • Zendesk closed tickets cannot be reopened by API, so the connector records that as a sync limitation.

Comment behavior

  • Zendesk public comments become Jira comments.
  • Zendesk internal notes are copied into Jira with a connector prefix.
  • Jira comments are pushed back to Zendesk as public comments.
  • Existing comments are matched and not edited in place because Zendesk ticket comments are immutable.

Attachment behavior

  • Zendesk attachments are downloaded and added to Jira during scheduled sync and manual refresh.
  • New Jira attachments are uploaded to Zendesk through the Uploads API.
  • Connector-managed Jira comments are added to provide traceability for synced files.
  • Files above 10 MB are skipped to keep the sync reliable inside Forge limits.
Traceability

Connector markers and traceability

[Zendesk internal note]

Prepended to Jira comments that originated as Zendesk internal notes so teams can distinguish them from public conversation.

[Zendesk Connector]

Used in connector-managed metadata blocks so the sync engine can recognize comments and attachment notes that it previously created.

type=jira-attachment-sync

Stored in the connector metadata for Zendesk attachment comments so later sync runs can match the originating Jira attachment safely.

Preview-value normalization

The issue panel resolves readable option labels and stores preview values by field ID first, which keeps duplicate labels from hiding the real data.

Operations

Troubleshooting

1

The admin connection does not save

Recheck the Zendesk subdomain, agent email, and API token. The connector validates those values immediately and will return the upstream Zendesk error when the credentials do not match.

2

The object or fields are missing in configuration

Refresh the Smart Connected Items screen after reconnecting. Missing object metadata usually points to a credential or permission gap in Zendesk, not a silent fallback inside the app.

3

Manual search shows no records

Ticket, customer, and organization search now support partial matching, but the results still depend on the object type and the actual Zendesk data. If a search result is unexpectedly empty, retry with the record ID to separate search behavior from permission issues.

4

Refresh or sync fails on priority

The connector now reads the Jira priority catalog through the Jira API that works with the current Forge scopes, and it normalizes Jira priorities before sending them to Zendesk. If priority still fails, confirm the mapped Zendesk field is the standard ticket priority field.

5

Comments or attachments are missing

Confirm that the Smart Connected Item has those sync options enabled. For large files, remember that attachments above 10 MB are intentionally skipped.

Known Limits

Current product limits

Important product boundaries

This section documents the current behavior of the shipping connector. It is intended to help admins set correct expectations before they roll the integration out broadly.

Tickets only for synchronized flows

One-way sync, two-way sync, auto-create, status sync, comment sync, and attachment sync are only available for Zendesk tickets.

Customers and organizations are display-only

Those objects can be manually linked, searched, refreshed, and previewed, but they are not part of the synchronized scheduler pipeline.

Large attachments are skipped

The sync engine intentionally skips files above 10 MB to avoid unreliable transfers inside Forge runtime and payload limits.

Deletions are not mirrored

The connector creates missing comments and attachments on the other side, but it does not delete Jira or Zendesk content when the source content is deleted later.

Closed tickets cannot reopen

If Jira moves after the Zendesk ticket is already closed, the connector records that limitation rather than faking a reopen that Zendesk does not allow by API.

Auto-managed links stay read-only in the issue panel

Users can refresh and open scheduler-managed tickets from Jira, but they cannot manually unlink those auto-created links in the issue panel.

References

Official references

Resource Why it matters
Atlassian Forge documentation Platform documentation for Forge runtime, permissions, storage, deployment, and app modules.
Zendesk Ticketing API introduction High-level Zendesk Support API overview.
Zendesk tickets API Used for ticket reads, updates, comments, status, and scheduler-driven sync behavior.
Zendesk users API Used for customer lookups and customer preview refreshes.
Zendesk organizations API Used for organization lookups and organization preview refreshes.
Zendesk Support search reference Helpful when validating search behavior for tickets and global search syntax.