Zoho Projects Connector for Jira Documentation
Verified against this connector codebase on March 31, 2026

Complete deployment and usage documentation for Zoho Projects Connector for Jira

This guide explains how to install the app, connect Jira to Zoho Projects, create Smart Connected Items, and use the Jira issue panel for linked Zoho Projects records. It is written against the current Forge implementation in this repository.

Forge app Jira admin page Jira issue panel Zoho Projects
Zoho polling Every 5 minutes

Used for Zoho Projects to Jira updates and optional automatic Jira issue creation.

Jira push events Near real time

Jira issue updates and Jira comments can push eligible changes back to Zoho Projects.

Sync-ready modules Tasks and Issues

Status sync, comments sync, two-way fields, and auto-create are centered on these modules.

Attachment sync UI Not exposed

The current Smart Connected Item setup flow does not expose attachments sync controls.

Fast Path

Quick start in six steps

1

Install the app

Install the connector from Atlassian Marketplace and open its Jira admin page from Settings > Apps.

2

Create a Zoho Self Client

In the Zoho API Console, create a Self Client so you can generate the Client ID, Client Secret, and authorization code.

3

Generate the authorization code

Generate the code with the required Zoho Projects OAuth scopes shown in this guide.

4

Connect from Jira

Enter the Zoho Projects data center, Client ID, Client Secret, and Code in the admin page and save the connection.

5

Create Smart Connected Items

Define display-only, one-way, or two-way behavior for the portal, project, module, Jira project, and issue type you want to support.

6

Use the Jira issue panel

Jira users can link records, open them in Zoho Projects, refresh them, and work with synchronized data where the item mode allows it.

Architecture

How the connector works

Current sync model in this build

The scheduled trigger runs every five minutes. It handles Zoho Projects to Jira field updates for linked records, optional automatic Jira issue creation, status sync, and Zoho-to-Jira comment sync.

Jira to Zoho Projects updates are event-driven. Jira issue updates can push two-way mapped fields and status changes, and Jira comment events can push comments back to Zoho Projects.

Zoho Projects Connector admin page showing the connection form, required scopes help card, and Save connection button.
Connection setup in the Jira admin page, including data center selection and the Zoho Self Client credentials.
Connected Zoho Projects Connector admin page showing the connection summary and Smart Connected Items table.
Connected admin experience with the saved Zoho Projects connection summary and the Smart Connected Items dashboard.

Where configuration is stored

  • Zoho Projects connection settings are stored in Forge app storage and Forge secret storage.
  • Smart Connected Item definitions are stored in Forge app storage.
  • Issue-to-record links are stored per Jira issue in Forge app storage.
  • Latest sync status for synchronized items is stored and shown back in the admin table.

Where users see the linkage

  • Admins see connection status and the Smart Connected Items grid in the admin page.
  • Jira users see link, preview, refresh, and open actions in the Jira issue panel.
  • Zoho Projects records can receive a connector-managed note that references the linked Jira issue.
Terminology

Key terms used in this guide

Display-only Smart Connected Item

A manual, read-focused configuration. Jira users link a Zoho Projects record from the issue panel and see the selected Zoho fields, but no synchronization runs.

One-way Smart Connected Item

A synchronized configuration where mapped Zoho Projects field values flow into Jira. Optional status sync and comments sync can also be enabled when the module supports them.

Two-way Smart Connected Item

A synchronized configuration where mapped fields can flow in both directions between Zoho Projects and Jira, plus optional status sync and comment sync.

Auto-managed link

A link created by the scheduler during automatic Jira issue creation. It is read-only in the issue panel and cannot be manually replaced or removed by the Jira user.

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 Jira Cloud site.

  1. Open Atlassian Marketplace and locate Zoho Projects Connector for Jira.
  2. Select the target Jira Cloud site.
  3. Approve the app installation and review the requested Jira permissions.
  4. Open Jira administration and navigate to the connector admin page.

What the installation gives you

  • A Jira admin page for Zoho Projects authentication and Smart Connected Item setup.
  • A Jira issue panel where users can link, view, refresh, and open Zoho Projects records.
  • A scheduled integration job that runs every five minutes.
  • Jira event handlers for issue updates and Jira comments.
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 credentials used by the connector.
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

1

Open the Zoho API Console

Go to api-console.zoho.com and sign in with the Zoho account that should own the integration client.

2

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.

3

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.

4

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 Jira app lets you select United States, Europe, India, Australia, Japan, China, United Kingdom, Canada, and Saudi Arabia. Use the value that matches the Zoho tenant where your portal and project data live.

Zoho Setup

Generate code and required scopes

Use the full scope set from the app

The connection screen and the app code expect the Self Client code to be generated with the exact Zoho Projects scope bundle below.

Required OAuth scopes

ZohoProjects.tasks.CREATE,
ZohoProjects.tasks.UPDATE,
ZohoProjects.bugs.CREATE,
ZohoProjects.bugs.UPDATE,
ZohoPC.files.CREATE,
ZohoPC.files.ALL,
WorkDrive.files.ALL,
ZohoProjects.portals.Read,
ZohoProjects.projects.Read,
ZohoProjects.activities.Read,
ZohoProjects.feeds.Read,
ZohoProjects.status.Read,
ZohoProjects.milestones.Read,
ZohoProjects.tasklists.Read,
ZohoProjects.tasks.Read,
ZohoProjects.bugs.Read,
ZohoProjects.events.Read,
ZohoProjects.forums.Read,
ZohoProjects.clients.Read,
ZohoProjects.users.Read,
ZohoProjects.documents.READ,
ZohoProjects.search.READ,
ZohoProjects.tags.Read,
ZohoProjects.calendar.Read,
ZohoProjects.integrations.Read,
ZohoProjects.projectgroups.Read,
ZohoProjects.entity_properties.Read,
ZohoProjects.custom_fields.READ,
ZohoPC.files.Read,
WorkDrive.workspace.Read,
WorkDrive.files.Read,
WorkDrive.team.Read,
AaaServer.profile.Read

Why these scopes are needed

  • Portal, project, module, and field metadata loading in the admin setup flow.
  • Searching Zoho Projects records from the Jira issue panel link dialog.
  • Reading Tasks and Issues data for display and synchronization.
  • Writing back to Zoho Projects for two-way fields, status sync, and comment sync.

What you paste into Jira later

  • Zoho data center
  • Client ID
  • Client Secret
  • Generated authorization code
Marketplace Admin Guide

Connect in the Jira admin page

Connection form fields

  1. Select the Zoho Data Center Location.
  2. Paste the Client ID.
  3. Paste the Client Secret.
  4. Paste the generated Code.
  5. Select Save connection.

What happens after a successful connection

  • The page switches from the connection form to a connected summary state.
  • The admin page shows the saved data center and client ID.
  • The Create Smart Connected Item button becomes available.
  • You can revoke the saved connection later with Revoke Connection.
Zoho Projects Connector connection form showing the Zoho Data Center Location, Client ID, Client Secret, Code, and Save connection button.
The admin authentication screen used to connect Jira to Zoho Projects.
Marketplace Admin Guide

Create Smart Connected Items

1

Choose the synchronization mode

Start with Create Smart Connected Item, then choose None (Display Only), One-Way Sync, or Two-Way Sync.

2

Select the Zoho source

Pick the Zoho portal, the Zoho project inside that portal, and the Zoho Projects module you want the item to target.

3

Complete the Jira scope and mappings

Display-only items target one or more Jira projects. Synchronized items target a single Jira project and a Jira issue type, then define field mappings plus optional sync settings.

4

Review the dashboard row after saving

The saved item appears in the Smart Connected Items table with its sync mode, Jira scope, Zoho source, enabled options, and latest sync summary.

Create Smart Connected Item dialog showing synchronization mode, portal, project, module, optional name, Jira project, issue type, and the first mapping area.
Smart Connected Item setup for selecting mode, Zoho source, Jira project, Jira issue type, and the first mapping.
Create Smart Connected Item dialog showing multiple mappings plus Status synchronization and Comments synchronization options.
The lower part of the synchronized item flow, where you can add more mappings and enable status sync or comments sync.
Connected admin panel listing saved Smart Connected Items for display-only, one-way sync, and two-way sync.
Example of the connected dashboard after Smart Connected Items have been saved.
Behavior Matrix

Modes and support matrix

Mode Jira scope What users get Practical module support
Display Only One or more Jira projects Manual link from the issue panel and a read-only preview of selected Zoho fields Tasks, Milestones, Timesheets, and Issues can be selected in the current UI
One-Way Sync (Zoho -> Jira) Single Jira project plus Jira issue type Mapped fields update Jira from Zoho; optional auto-create, status sync, and comments sync Use Tasks or Issues for full sync features
Two-Way Sync (Zoho <-> Jira) Single Jira project plus Jira issue type Mapped fields can flow in both directions; optional auto-create, status sync, and comments sync Two-way mapped field sync is currently supported for Tasks and Issues

How to read the dashboard table

The Smart Connected Items table shows the item name, sync mode, Jira scope, issue type, Zoho source, fields or mappings, auto-create status, comments sync status, status sync status, and the latest sync summary.

Configuration Rules

Field mapping rules

Display-only items

  • Select one or more Zoho fields to show in the Jira issue panel preview.
  • No Jira field mapping is required.
  • Manual linking is required before users see a record preview.

Synchronized items

  • Select a Jira project first, then choose the Jira issue type from that project.
  • Create one or more Jira field to Zoho field mappings.
  • The UI supports adding more than one mapping in the same Smart Connected Item.

New synchronized items must target an issue type

New one-way and two-way Smart Connected Items are issue-type scoped. The app loads issue types after you choose the Jira project and requires an issue type before save.

Synchronization

Automatic Jira issue creation

What the option does

When enabled, the five-minute scheduled sync creates a new Jira issue for each new Zoho Projects record that matches the Smart Connected Item, then stores a read-only link in the issue panel.

Recommended use

Use automatic Jira issue creation for standardized intake flows where Tasks or Issues in Zoho Projects should always appear in the same Jira project and issue type.

Module support

Automatic Jira issue creation currently supports Zoho Projects Tasks and Issues in this build.

Synchronization

Status sync

Direction and timing

Jira issue status changes can push to Zoho Projects immediately on issue update events, and Zoho status changes can flow back to Jira on the five-minute scheduler.

How matching works

The connector does not require the two workflows to be identical. It looks for the closest safe alternative status between Jira and Zoho Projects.

Module support

Status sync currently supports Zoho Projects Tasks and Issues.

Synchronization

Comments sync

Jira to Zoho Projects comments

When comments sync is enabled, new Jira comments are pushed to the linked Zoho Projects record immediately through the Jira comment event trigger.

Zoho Projects to Jira comments

The five-minute scheduler pulls new Zoho Projects comments into the linked Jira issue when comments sync is enabled for the Smart Connected Item.

Module support

Comments sync currently supports Zoho Projects Tasks and Issues.

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 Jira issues, projects, fields, comments, and workflow context.
Forge write:jira-work Creates issues, updates fields, posts comments, and updates issue state in Jira.
Forge read:issue:jira Supports issue-level reads used by the issue panel and sync flows.
Forge write:issue:jira Supports issue-level updates used by the sync flows.
Zoho Projects Generate Code scopes listed above Supports metadata loading, record search, reads, status updates, comments, and mapped-field writeback.
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 Projects record preview when a record is already connected.
  • Open in Zoho Projects, Refresh, and for manual links, Unlink.
  • Sync mode context so the user knows whether the item is display-only, one-way, or two-way.

What determines visibility

The issue panel only shows Smart Connected Items that apply to the current Jira issue context. Display-only items are scoped by Jira project, while synchronized items are scoped by Jira project plus issue type.

Jira issue view showing the Zoho Projects Connector panel before linking, with Link buttons for the available mapped items.
Not linked yet: the issue panel shows the matching Smart Connected Items and a Link action for each item that can be connected to a Zoho Projects record.
Jira issue view showing the Zoho Projects Connector panel after linking, with mapped values plus Open in Zoho Projects, Refresh, and Unlink actions.
Linked state: the issue panel shows the mapped Zoho Projects values and exposes Open in Zoho Projects, Refresh, and for manual links, Unlink.
Jira User Guide

Link records from the issue panel

1

Open the link flow

When a Smart Connected Item is not linked yet, the issue panel shows a Link action.

2

Search Zoho Projects by name or title

The link modal searches the selected portal, project, and module after the user types at least 2 characters, then shows matching Zoho Projects records to choose from.

3

Link the selected record

After the record is chosen, the app stores the link against the current Jira issue and refreshes the panel preview.

4

Refresh or unlink later

Manual links expose Refresh and Unlink. Refresh reloads the linked record preview, while Unlink removes the stored relationship.

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 Projects 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 Projects record and refresh the preview, but cannot manually unlink or replace the record.

Jira User Guide

Manual refresh behavior

Refresh is available for manual and auto-managed links

The issue panel exposes Refresh for both manual links and scheduler-created links so the user can pull the latest Zoho Projects record preview immediately.

What refresh does

It reloads the current record preview and re-applies the connector's normal linked-item behavior for that issue and Smart Connected Item.

What refresh does not replace

It does not disable the scheduled sync. The five-minute scheduler continues to run as normal for synchronized Smart Connected Items.

Operations

Troubleshooting guide

The Jira admin page cannot authenticate to Zoho Projects

Verify the selected data center, Client ID, Client Secret, and Code. Confirm the code was generated from the correct Self Client and that the required OAuth scopes were included.

A Smart Connected Item does not appear in the issue panel

Confirm the item applies to the current Jira project. For one-way and two-way items, also confirm the current issue matches the configured Jira issue type.

No Jira issues are being auto-created

Confirm the Smart Connected Item is synchronized, auto-create is enabled, the selected module is supported for auto-create, and the scheduler has had time to run.

Status or comment changes are not appearing quickly from Zoho Projects

Zoho Projects to Jira updates are scheduled, not instant. Wait for the next five-minute cycle or use Refresh from the issue panel to pull the latest record preview sooner.

The link dialog finds no Zoho Projects records

Make sure the user typed at least two characters, the correct portal/project/module was configured in the Smart Connected Item, and matching records exist in that Zoho Projects source.

Operations

Known limits in this connector build

Five-minute scheduler cadence

Zoho Projects to Jira updates and automatic issue creation are driven by the five-minute scheduled trigger.

Sync feature focus

Full synchronized behavior is centered on Zoho Projects Tasks and Issues in the current build.

Display-only modules are broader

Milestones and Timesheets can be selected in the UI, but synchronized features are narrower.

No attachment sync control in the admin flow

The current Smart Connected Item setup UI does not expose an attachments sync option.

Synchronized item scope

Each new synchronized Smart Connected Item targets one Jira project, one Jira issue type, and one Zoho source.

Manual search requires input

The issue panel link dialog requires at least two characters before it searches Zoho Projects records.

Operations

Official references

Atlassian Forge manifest reference Atlassian Forge Jira events reference Atlassian Forge app management reference Zoho API Console Zoho Projects REST API documentation