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.
• When enabled, linked records can also show read-only associated Zendesk record groups.

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.

What every item defines

• A name that appears in the Jira issue panel.
• A sync mode: none, one-way sync, two-way sync, or custom sync per mapping.
• 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 associated record display.
• Optional Conditional Sync Rules, status sync, comment sync, and attachment sync.
• Warnings when a Jira issue type is missing safe create-field coverage.

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.

Optional association display

• Admins can enable associated Zendesk records on display-only items.
• The issue panel renders related records as read-only expandable groups.
• Association display does not turn customers or organizations into synchronized records.

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.

Custom Sync per Mapping

• Each mapped field receives its own field owner.
• Zendesk owns writes that field from Zendesk to Jira.
• JSM owns writes that field from Jira to Zendesk.
• Both own keeps that single field synchronized in both directions.

Automation options

• Auto-create can open Jira issues from new Zendesk tickets.
• Associated record display adds read-only context to the issue panel.
• Conditional Sync Rules can control Jira status and decide whether non-matching new tickets are created.

How mappings work

A mapping pairs one Zendesk field with one Jira field. One-way mode writes mapped values from Zendesk to Jira. Two-way mode also lets Jira issue updates push mapped values back to the linked Zendesk ticket.

How custom field owners work

In Custom Sync per Mapping, each row has a field owner. Choose Zendesk owns for Zendesk-to-Jira, JSM owns for Jira-to-Zendesk, or Both own for two-way synchronization on that one field.

When mappings are optional

A synchronized Smart Connected Item can be saved without field mappings when the goal is status-only synchronization, comment-only synchronization, attachment-only synchronization, conditional status movement, or manual linking without auto-create.

Safe ownership choices

Treat the owner as the system of record for that field. Use Both own only for fields where agents are comfortable with the most recent eligible change moving between Jira and Zendesk.

What the rule evaluates

The connector checks one selected Zendesk field on each eligible linked or newly discovered ticket. Operators include equals, does not equal, is empty, and is not empty. Dropdown-style, boolean, date, and text values are driven by the Zendesk field metadata available in the admin page.

What the rule changes in Jira

The admin chooses a Jira status for tickets that meet the condition. A separate not-met Jira status is used only when the non-match creation checkbox is enabled. During scheduled sync, manual linking, refresh, and relevant Jira issue updates, the connector transitions the Jira issue when Jira exposes a valid workflow transition.

What the checkbox controls

Create Jira issue when rule is not met applies only when auto-create Jira issues is also enabled. If checked, a new Zendesk ticket that does not match the condition can still create a Jira issue and use the not-met Jira status. If unchecked, the scheduler skips that new ticket and no Jira issue is created for it.

What the toggle does

When enabled, the Jira issue panel looks up Zendesk records related to the linked record and groups them by relationship type. Ticket examples include requester, submitter, assignee, organization, CCs, followers, problem ticket, follow-up tickets, and incident tickets.

What users see

Users see expandable groups under Associated Zendesk Records. Each returned record shows a compact preview of useful fields and an Open action when the connector can build a Zendesk URL.

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

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.
• Associated Zendesk record groups when the admin enabled association display.

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.

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.
• In Custom Sync per Mapping, only fields owned by JSM or both sides can be pushed from Jira to Zendesk.
• 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.
• Conditional Sync Rules replace generic status sync for the Smart Connected Item.
• 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.