Used for Zoho -> Jira updates and optional automatic Jira issue creation.
Verified against this connector codebase on March 30, 2026
Complete deployment and usage documentation for Marketplace admins and Jira users
This guide explains how to install the app from Atlassian Marketplace, connect it to Zoho Desk, create Smart Connected Items, and use the Jira issue panel for linked Zoho records. It is written for the current Forge implementation of the Zoho Desk Connector for Jira.
Forge app
Jira admin page
Jira issue panel
Zoho Desk
Jira issue, comment, and attachment events push eligible changes back to Zoho.
Larger files are skipped to stay inside runtime and payload limits.
The app can add a Zoho-side link note/comment that names the Jira issue and sync behavior.
Fast Path
Quick start in six steps
Install the app
Install the connector from Atlassian Marketplace and open its Jira admin page from Settings > Apps.
Create a Zoho Self Client
In the Zoho API Console, create a Self Client to obtain the Client ID and Client Secret used by the connector.
Generate the authorization code
Use the connector's required Zoho Desk scopes when you generate the code in Zoho API Console.
Connect from Jira
Enter the Zoho Desk data center, Client ID, Client Secret, and Code into the app admin page and save the connection.
Create Smart Connected Items
Define display-only, one-way, or two-way behavior for the Zoho module and Jira project / issue type combination you need.
Use the Jira issue panel
Jira users can link records manually, open them in Zoho, refresh them on demand, and work with synchronized data.
Architecture
How the connector works
Current sync model in this build
The scheduled trigger runs every five minutes. It handles Zoho -> Jira field updates for linked records, optional automatic Jira issue creation, status sync, comment sync, and attachment sync.
Jira -> Zoho updates are event-driven. Jira issue update events can push mapped fields and status changes. Jira comment events push comments. Jira attachment events push attachments.
Where configuration is stored
- Zoho connection settings are stored in Forge app storage and Forge secret storage.
- Smart Connected Item definitions are stored in Forge app storage.
- Jira issue to Zoho record link registrations are stored in Forge app storage.
- Legacy records are migrated automatically and preserved as compatibility data.
Where users see the linkage
- Jira users see the linked record preview in the issue panel.
- Admins see latest sync state, linked record counts, and scheduler error details in the admin grid.
- Zoho users can see a connector-created Jira link note/comment on the related record.
Terminology
Key terms used in this guide
Display-only Smart Connected Item
A manual, read-focused configuration. Jira users link a Zoho record from the issue panel and see selected Zoho fields. There is no automatic issue creation and no scheduled data sync.
One-way Smart Connected Item
A synchronized configuration where mapped Zoho field values flow into Jira. Optional status, comment, and attachment features can also be enabled for linked records.
Two-way Smart Connected Item
A synchronized configuration where mapped fields can flow both directions, and optional status, comment, and attachment features can be enabled for linked records.
Auto-managed link
A link created by the scheduler during automatic Jira issue creation. Jira users can refresh and open the Zoho record, but they cannot unlink or replace it manually.
Marketplace Admin Guide
Install the app from Atlassian Marketplace
Who should perform the installation
Installation should be completed by a Jira site administrator or another Atlassian administrator who is allowed to install apps on the target cloud site.
- Open Atlassian Marketplace and locate Zoho Desk Connector for Jira.
- Select the target Jira Cloud site.
- Approve the app installation and review the requested Jira scopes.
- Open Jira administration and navigate to the connector admin page.
What the installation gives you
- A Jira admin page for Zoho authentication and Smart Connected Item setup.
- A Jira issue panel where users can link, view, refresh, and open Zoho records.
- A scheduled integration job that runs every five minutes.
- Jira event handlers for issue updates, comments, and new attachments.
| Stage | Typical responsible admin | Why that level is needed |
|---|---|---|
| Install the app in Jira Cloud | Atlassian site administrator | Marketplace app installation is usually restricted to site administrators. |
| Create the Zoho Self Client and Generate Code | Zoho administrator or integration owner with API Console access | Needed to create the OAuth client and obtain the authorization code and refresh token path. |
| Authenticate and configure Smart Connected Items | Jira administrator | Needed to open the connector admin page and define project-specific Jira behavior. |
Zoho Setup
Create the Zoho Self Client
Open the Zoho API Console
Go to api-console.zoho.com and sign in with the Zoho account that should own the integration client.
Create a Self Client
Choose Add Client, then select Self Client. The connector uses that client to exchange the authorization code for access and refresh tokens.
Save the Client ID and Client Secret
Copy the generated Client ID and Client Secret. You will paste both values into the Jira admin page later.
Generate the authorization code
Open the Generate Code tab for the Self Client and generate the code with the required scopes shown in the next section.
Choose the correct Zoho data center
The connector supports us, eu, in, au,
jp, cn, uk, ca, and sa. The
data center selected in Jira must match the Zoho environment used for the Self Client and generated code.
Zoho Setup
Generate Code and required Zoho scopes
Paste this full scopes value into Zoho API Console
Desk.search.READ,Desk.tickets.CREATE,Desk.tickets.READ,Desk.tickets.UPDATE,Desk.contacts.READ,Desk.contacts.UPDATE,Desk.tasks.READ,Desk.tasks.UPDATE,Desk.basic.READ,Desk.settings.READ,Desk.settings.UPDATE,Desk.events.READ,Desk.events.UPDATE,Desk.articles.READ,Desk.articles.UPDATE,Desk.calls.READ,Desk.calls.UPDATE,Desk.settings.ALLThe Jira admin screen for this connector shows the same scopes block in the disconnected connection view so admins can copy it into Zoho API Console when generating the code.
What those scopes are used for
Desk.tickets.*supports reading tickets and creating or updating ticket data.Desk.contacts.*supports linked contact lookup and updates.Desk.tasks.*,Desk.events.*, andDesk.calls.*support related desk modules.Desk.settings.*supports module and field metadata discovery used in the admin page.Desk.search.READsupports issue-panel record search.
Authorization code handling
The code is required during the initial connection flow. The connector exchanges it for an access token and refresh token, then reuses the stored refresh token when it needs a new access token later.
Marketplace Admin Guide
Connect in the Jira admin page
Fields shown on the connection form
- Zoho Desk data center
- Client ID
- Client Secret
- Code
Once connected, the admin page shows the current data center, stored client ID, API domain, and a Revoke Connection action.
What revoke and reconnect do
- Revoking clears the stored Zoho credentials and hides Smart Connected Items from the disconnected view.
- Reconnecting restores the Zoho connection and re-enables the admin grid and issue-panel behavior.
- Stale auth-related sync errors are cleared automatically after a successful reconnect.
Admin experience after connection
The Smart Connected Items section is intentionally hidden until a valid Zoho connection is present. That prevents admins from editing sync definitions while the app is disconnected.
Marketplace Admin Guide
Create Smart Connected Items
What the admin grid shows
- Name and sync mode
- Jira scope and issue type
- Zoho source module
- Field or display mapping summary
- Auto-create, comments, attachments, and status toggles
- Latest sync timestamp, linked record count, and scheduler error details
What the create / edit flow collects
- Mode: display only, one-way, or two-way
- Name
- Jira project
- Jira issue type for synchronized items
- Zoho source module
- Display fields or Jira-to-Zoho field mappings
- Optional auto-create, status, comments, and attachment settings
Legacy items
Migrated legacy items remain visible in the admin page with a Legacy compatibility badge so admins can identify upgraded configurations. That badge is intentionally kept out of the Jira issue panel to reduce noise for end users.
Marketplace Admin Guide
Modes and behavior matrix
| Behavior | Display only | One-way | Two-way |
|---|---|---|---|
| Manual link from issue panel | Yes | Yes | Yes |
| Automatic Jira issue creation | No | Yes, when enabled and the module supports polling | Yes, when enabled and the module supports polling |
| Mapped field sync direction | No mapped field sync | Zoho -> Jira | Zoho <-> Jira |
| Status sync | No | Optional | Optional |
| Comments sync | No | Optional | Optional |
| Attachments sync | No | Optional | Optional |
| Issue type required | No | Yes | Yes |
Important nuance
The sync mode primarily controls mapped field behavior. Status, comments, and attachments are separate optional capabilities that can be enabled on synchronized items and then operate according to their own sync logic.
Marketplace Admin Guide
Field mapping rules
How the mapping step works
The editor loads Jira fields for the selected project and issue type, then loads Zoho fields for the selected module. You map the Jira field to the Zoho field that should drive or receive the value.
- Display-only items choose visible Zoho fields instead of field mappings.
- Synchronized items save a normalized mapping model for later scheduler and trigger use.
- Status sync can use a dedicated Zoho status field chosen in the editor.
How Jira issue creation is protected
During automatic issue creation, the connector fetches Jira create metadata and only sends fields that are valid on the create screen. If a mapped summary is empty, the connector falls back to a title built from the Zoho record.
- Blank optional fields are omitted from the create payload.
- Remaining mapped fields are applied after create through the normal Jira update flow.
Marketplace Admin Guide
Automatic Jira issue creation
When it runs
Automatic issue creation is processed by the five-minute scheduled trigger for synchronized Smart Connected Items where Auto Create is enabled.
- A Jira project and issue type must be configured.
- The item must not be display-only.
- The Zoho module must support polling in this connector build.
Polling-supported modules in this build
Tickets
Contacts
Accounts
Calls
Events
Tasks
Time Entry
Products
Contracts
Creation baseline
The scheduler only considers records that appear after the stored auto-create baseline for the Smart Connected Item. If you enable auto-create later, older historical Zoho records are not retro-created as Jira issues unless they fall after that saved baseline.
Connector Configuration
Status sync
Zoho -> Jira status behavior
The scheduler compares the Zoho status text against the Jira issue status and attempts the best Jira transition when the states do not align closely enough.
Jira -> Zoho status behavior
Jira issue update events can push status changes back to Zoho when status sync is enabled for the linked item.
Field selection matters
The admin editor lets you choose the Zoho field used for status sync. If you do not select one, the
connector falls back to the generic Zoho status field.
Connector Configuration
Comments sync
Zoho -> Jira comments
The scheduled sync can create or update Jira comments from Zoho comments on the linked record when the item has comments sync enabled.
Jira -> Zoho comments
Jira comment events can create or update Zoho comments on the linked record when the item has comments sync enabled.
Zoho linkage note
The connector also creates a dedicated Zoho comment when a Jira link is established manually or automatically. That note is meant to give Zoho users visible linkage context directly on the record.
Connector Configuration
Attachments sync
Zoho -> Jira attachments
The scheduled sync can pull eligible Zoho attachments and add them to the linked Jira issue. Ticket attachment discovery includes the direct ticket attachments and ticket thread attachments.
Jira -> Zoho attachments
Jira attachment creation events can upload new issue attachments back to the linked Zoho record when the item has attachments sync enabled.
Attachment size limit
Files larger than 10 MB per attachment are skipped intentionally in this build.
Reference
Permissions and scope reference
| Platform | Permission or scope | Purpose |
|---|---|---|
| Forge | storage:app |
Stores Zoho connection settings, Smart Connected Items, and issue-to-record links. |
| Forge | read:jira-work |
Reads projects, issues, fields, comments, transitions, and attachments. |
| Forge | write:jira-work |
Creates issues, updates fields, posts comments, transitions statuses, and uploads attachments. |
| Forge | manage:jira-project |
Supports project and configuration operations needed by the admin experience. |
| Forge | read:jira-user |
Supports Jira user-aware reads during admin setup and sync behavior. |
| Zoho Desk | Generate Code scopes listed above | Supports record search, record reads, module metadata, and write operations back into Zoho. |
Jira User Guide
Issue panel overview
What Jira users see
- The Smart Connected Items that apply to the current Jira project and issue type.
- The linked Zoho record preview when a record is already connected.
- Open in Zoho, Refresh, and sometimes Unlink actions.
- Status sync information when status sync is enabled for that item.
What determines visibility
The panel only shows Smart Connected Items that apply to the current Jira issue context. Display-only items appear for the selected Jira project. Synchronized items are scoped by project and issue type.
Jira User Guide
Link, search, refresh, and unlink records
Open the link flow
When a record is not yet linked, the user can click Link from the issue panel.
Search by name / title or enter a direct record ID
The search dialog lets the user type to search Zoho records. The final link action can also use a direct Zoho record ID.
Refresh on demand
Once linked, the user can refresh the record preview from the issue panel to pull the latest Zoho values without waiting for the next scheduled cycle.
Unlink when the link is manual
A manual link can be removed from the panel. The connector then removes the stored relationship and stops syncing that item for the issue.
Jira User Guide
Auto-managed links
When they appear
Auto-managed links appear when the scheduler automatically creates a Jira issue from a new Zoho record for a synchronized Smart Connected Item with auto-create enabled.
Why the panel treats them differently
These links are owned by the automation flow. The user can still open the Zoho record and refresh the preview, but cannot manually unlink or replace the record from the issue panel.
Jira User Guide
Manual refresh behavior
Refresh is available even for scheduler-created links
The issue panel exposes Refresh for both manual links and auto-managed links. This lets a user pull the latest Zoho field preview immediately instead of waiting for the next five-minute scheduler run.
What refresh does
It reloads the live Zoho record preview and, for synchronized items, applies the connector's normal Zoho-to-Jira sync logic for that linked item.
What refresh does not replace
It does not disable the scheduled sync. The scheduler still runs as normal every five minutes for all synchronized items.
Jira User Guide
What changes in Zoho when Jira users work in Jira
| Jira action | Zoho effect | Condition |
|---|---|---|
| Edit a mapped issue field | Updates the mapped Zoho field | Two-way mapped field sync must be enabled for the linked item |
| Change issue status | Updates the selected Zoho status field | Status sync must be enabled |
| Add or edit a Jira comment | Creates or updates a Zoho comment | Comments sync must be enabled |
| Add a Jira attachment | Creates a Zoho attachment-backed record artifact | Attachments sync must be enabled and the file must be within size limits |
Jira User Guide
Visible Jira link note in Zoho
What the connector writes
When a link is created manually or automatically, the connector can create a Zoho comment that states the record is linked to a Jira issue. The note includes the Jira issue key, Jira URL, issue ID, Smart Connected Item name, Zoho source, sync mode, link type, enabled actions, and linked timestamp.
Why it exists
This gives Zoho users an immediate visual signal that the record is now associated with a Jira issue, without requiring a custom field or custom app UI inside Zoho Desk.
Operations
Troubleshooting guide
The Jira admin page cannot authenticate to Zoho
Verify the data center, Client ID, Client Secret, and Code. Confirm the code was generated from the correct Self Client and that the required Zoho Desk scopes were included.
A stale auth-related sync error still appears after reconnect
In the current build, a successful reconnect clears stale auth-related Smart Connected Item sync errors automatically. Refresh the admin page after reconnect to confirm the old auth-expired error is gone.
Smart Connected Items load, but no Jira issues are auto-created
Confirm the item is synchronized, auto-create is enabled, the target module supports polling, and the Zoho records were created after the saved auto-create baseline for that item.
Field, comment, or attachment changes from Zoho take time to appear in Jira
Zoho -> Jira updates are scheduled, not instant. The scheduled trigger runs every five minutes, so changes typically appear on the next cycle unless a user refreshes the linked item from the issue panel.
Jira comments or attachments are not appearing in Zoho
Confirm the relevant sync option is enabled, the issue is linked to the intended Smart Connected Item, and the file size is within limits for attachments.
Operations
Known limits in this connector build
Five-minute scheduler cadence
Zoho -> Jira updates and automatic issue creation are driven by the five-minute scheduled trigger.
10 MB attachment ceiling
Attachments larger than 10 MB are intentionally skipped.
No deletion mirroring
Comment deletions and attachment deletions are not mirrored across Jira and Zoho in this build.
Synchronized item scope
Each synchronized Smart Connected Item targets one Jira project, one Jira issue type, and one Zoho source.
Module behavior can vary
The admin page loads Zoho modules dynamically from the tenant, but practical sync behavior still depends on the fields, comments, attachments, and statuses exposed by the selected module.
Legacy compatibility is preserved
Upgraded legacy configurations are preserved and surfaced in the admin page, but they may have broader historical scope than brand-new synchronized items.
Operations