> For the complete documentation index, see [llms.txt](https://guide.smarttask.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.smarttask.io/integrations/jira-cloud.md).

# Jira Cloud Integration

Sync Jira Cloud issues, fields, and comments with SmartTask so engineering and cross-functional teams can collaborate while continuing to work in their preferred tools.

### Overview <a href="#overview" id="overview"></a>

The Jira integration connects one SmartTask project to one Jira Cloud project and issue type, so your team can work in either tool and see the same work in both.

Once a project is connected, you can:

* **Link tasks and issues.** Each task can be linked to one Jira issue, shown in the task's Apps section.
* **Sync fields.** Name, description, assignee, dates, status, priority and other connected fields stay the same on both sides.
* **Sync comments.** New comments on a linked task or issue appear on the other side.
* **Create automatically.** New Jira issues can become SmartTask tasks, new SmartTask tasks can become Jira issues, or both.
* **Import existing issues.** Bring a Jira project's open issues into SmartTask as linked tasks in one step.

### Before you start <a href="#before-you-start" id="before-you-start"></a>

You need three things before setting up a sync:

* **A Jira Cloud site.** Jira Server and Data Center are not supported.
* **A Jira account** that can see and edit issues in the Jira project you want to connect. SmartTask acts in Jira as this account, so issues and comments it creates show this account as the author.
* **Permission to edit the SmartTask project.** Guests can't set up or change a Jira sync.

You connect your Jira account the first time you set up a sync: SmartTask sends you to Atlassian to sign in and approve access. After that, the connection can be reused for other projects in your organization.

### Set up Jira sync for a project <a href="#set-up-jira-sync-for-a-project" id="set-up-jira-sync-for-a-project"></a>

Setup takes a few minutes and happens in one window. Open it from the project's **Customize** panel, under **Apps**, or from your organization's **Apps** page, under **Jira**.

1. In the SmartTask project, open **Customize**, go to **Apps** and add **Jira**.<br>

   <figure><img src="https://292815748-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Kv3f6dFTu1_4DYGKJPB%2Fuploads%2F8vOfxyF1as3XStLTh06i%2Fchrome_Iz48kpBhZU.png?alt=media&amp;token=a7525fe8-9089-45ac-b65b-560b7d08f9be" alt=""><figcaption></figcaption></figure>
2. **Choose a Jira connection.** Pick an existing one or add a new one and sign in to Atlassian.
3. **Choose the Jira project** whose issues this SmartTask project will sync with.
4. **Choose the issue type**, for example Task or Bug. Only issues of this type are created and synced automatically.
5. **Choose the task creation direction** and, if you want, tick **Import existing issues from Jira**. See Creating tasks and issues below.
6. **Map fields.** Review the suggested field connections and the field sync direction. See Connecting fields below.
7. **Sync comments** if you want comments to flow both ways.
8. Select **Save**.

{% hint style="info" %}
The Jira site and Jira project can't be changed once the sync is saved, because existing links point into that project. To use a different Jira project, remove the sync and set it up again. Everything else can be changed later.
{% endhint %}

{% hint style="info" %}
We support all Jira Software issue types, including Bug, Epic, Story, and Task. We do not support syncing Jira subtasks to SmartTask.
{% endhint %}

### Jira Cloud data sync <a href="#gl-jira-cloud-data-sync" id="gl-jira-cloud-data-sync"></a>

#### What does “two-way sync” mean? <a href="#h_01haq484edhtj1174j6c10r4pz" id="h_01haq484edhtj1174j6c10r4pz"></a>

A two-way sync refers to automatic updates between designated fields in SmartTask and Jira. This is achieved by the ability to automatically create and update a task or issue from SmartTask →Jira, Jira→SmartTask, or SmartTask←→Jira on a project basis.

#### Choosing a one-way or two-way tasl / issue creation sync direction <a href="#h_01haq484ed77tjy4fmthqpcjpa" id="h_01haq484ed77tjy4fmthqpcjpa"></a>

<figure><img src="https://292815748-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Kv3f6dFTu1_4DYGKJPB%2Fuploads%2F0clx2YC6E2npZ5JZDynP%2Fimage.png?alt=media&amp;token=6f8d8cdd-192b-483a-a9d6-ec1964c4740f" alt=""><figcaption></figcaption></figure>

#### Choosing a one-way or two-way field sync direction <a href="#h_01haq484edrvecjwzztt5xfda5" id="h_01haq484edrvecjwzztt5xfda5"></a>

<figure><img src="https://292815748-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Kv3f6dFTu1_4DYGKJPB%2Fuploads%2F0DWVZojPGb1u3jM12D2E%2Fimage.png?alt=media&amp;token=cc5928b4-5a2c-4980-b340-b2010e49b2b7" alt=""><figcaption></figcaption></figure>

### Supported issue types and fields <a href="#gl-supported-types-and-fields" id="gl-supported-types-and-fields"></a>

Each SmartTask project is mapped to sync with a particular Jira Issue type from a Jira project. SmartTask’s Jira Cloud integration supports standard issue types (e.g., Epic, Story) and custom issue types.&#x20;

| SmartTask             | Jira        |
| --------------------- | ----------- |
| Task name             | Summary     |
| Description           | Description |
| Status custom field   | Status      |
| Priority custom field | Priority    |
| Assignee custom field | Assignee    |
| Due date              | Due date    |

#### Unsupported fields in data sync

* We don’t support Timestamp or Dependent drop-down field types in either sync direction. URL, Sprint, Story point estimate fields, and custom field types
* Components
* Versions (Fix Version, Affects Version)
* Labels
* Epic Link (or Epic Name)
* Sprint (from Jira Software boards)
* Story Points / Estimation fields
* Time Tracking fields (Original Estimate, Remaining Estimate, Time Spent)
* Rank / Order
* Linked Issues (blocks, relates to, duplicates, etc.)
* Watchers / Voters
* Any marketplace app custom fields (non-standard Jira field types)

#### Mapping users between SmartTask and Jira

We support field mapping of users, including Assignee, Reporter, and People custom fields on Jira. But there are important limitations to be aware of:

* Users are mapped based on the email addresses used to sign up for SmartTask and Jira.
* In the case where there is no equivalent account, the value is dropped altogether (the assignee will be blank in SmartTask). Therefore, syncing of People-type custom fields should only be used if users are expected to have accounts in both platforms.
* By default, visibility of user email addresses is hidden in Jira organizations. This will need to be changed in user's [profile visibility settings](https://developer.atlassian.com/cloud/jira/platform/profile-visibility/).

### Jira Cloud Comment Sync

#### Comment syncing

Comment sync allows SmartTask and Jira users to collaborate directly from the tool they already use.

When a SmartTask task is linked with a Jira issue, comments can automatically sync between the two platforms. A user can leave a comment in Jira and have it appear in SmartTask, or comment in SmartTask and have it reflected on the corresponding Jira issue.

This helps cross-functional teams collaborate without requiring everyone to work from the same platform.

#### Enabling comment sync

<figure><img src="https://292815748-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Kv3f6dFTu1_4DYGKJPB%2Fuploads%2FOhl7ucyLoB2ZZHqfTwVl%2Fchrome_QUHCSExZmE.png?alt=media&amp;token=71f511b6-835a-4b81-b493-5e6f3d860482" alt=""><figcaption></figcaption></figure>

1. Open the SmartTask project you want to connect with Jira.
2. Open the **Jira Cloud integration settings**.
3. Connect your Jira Cloud account if it is not already connected.
4. Select the Jira project you want to synchronize.
5. Select the Jira issue type.
6. Configure which SmartTask and Jira fields should be synchronized and their sync direction.
7. Enable **Sync comments**.
8. Save the configuration.

#### Using comment sync

Comment sync applies to SmartTask tasks that are linked with Jira issues under the configured project sync.

**Jira → SmartTask**

When someone adds a comment to the linked Jira issue, the comment automatically appears in the corresponding SmartTask task.

**SmartTask → Jira**

When someone adds a comment to the SmartTask task, the comment automatically appears on the corresponding Jira issue.

This allows both teams to participate in the same conversation without changing their existing workflow.

#### Use case examples

**Use case 1: Sprint planning across teams**

The engineering team manages development work in Jira, while the project or delivery manager coordinates the broader project in SmartTask.

The manager can manage priorities, dependencies, timelines, and client commitments from SmartTask. Engineers can continue updating issues and responding to questions from Jira.

Comments synchronize between both systems, keeping everyone aligned without requiring engineers to work in SmartTask.

**Use case 2: Product launch coordination**

The engineering team manages development in Jira, while marketing and product teams coordinate the overall product launch in SmartTask.

Marketing can track whether development activities are progressing against launch deadlines without needing access to Jira. Engineers can continue working from Jira while relevant updates and discussions remain visible to the broader team in SmartTask.

### Import Existing Jira Issues

SmartTask can import existing Jira issues into a SmartTask project and apply the configured synchronization settings to them.

#### When to use issue import

For example, an engineering team may already have an active Jira project containing dozens of issues.

A project manager wants to manage the overall engagement in SmartTask, including engineering work, marketing activities, client deliverables, dependencies, timelines, and other work that does not belong in Jira.

Instead of recreating the engineering tasks manually, the existing Jira issues can be imported into SmartTask. Going forward, relevant updates can stay synchronized between both systems.

#### Importing existing Jira issues

<figure><img src="https://292815748-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Kv3f6dFTu1_4DYGKJPB%2Fuploads%2F8VsJ7OcMOz5a5KCqNwkk%2Fchrome_05PiStUkPs.png?alt=media&amp;token=591578b2-d2da-4108-9fc4-fa37ff8f11b7" alt=""><figcaption></figcaption></figure>

1. Open the SmartTask project you want to connect with Jira.
2. Open the **Jira Cloud integration settings**.
3. Connect your Jira Cloud account if required.
4. Select the Jira project and issue type you want to synchronize.
5. Configure the required field mappings and synchronization directions.
6. Enable **Import existing issues from Jira**.
7. Save the configuration.

SmartTask will import the matching Jira issues and create corresponding SmartTask tasks.

{% hint style="info" %}

#### Important notes

* Only Jira issues matching the configured Jira project and issue type will be imported.
* Imported tasks will perform an initial synchronization of the configured fields.
* Depending on the number of issues, the initial import may take a few minutes.
* After the initial import, SmartTask and Jira will continue synchronizing based on the configured sync rules.
  {% endhint %}

**If the two way field sync has been selected**

A one way sync is performed for all Jira app custom fields in SmartTask but standard fields will not be synced to avoid unexpected data loss.

* The newly created Jira app custom fields should be updated with the latest values from Jira.
* Task name and description should stay unchanged until the user makes changes from SmartTask or Jira per the field map in the data sync setting.

<figure><img src="https://292815748-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Kv3f6dFTu1_4DYGKJPB%2Fuploads%2FCGUWAr9jPJEmmug2ELVP%2Fchrome_WHY5FcWKtT.png?alt=media&amp;token=c70e87c5-2699-4ade-9b25-a0d0578218d9" alt="" width="516"><figcaption></figcaption></figure>