> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Keep your team's projects and tickets up-to-date with fresh customer data

## Supported syncing

| Sync Type | Description | Supported Sync Modes | API documentation |
| - | - | - | - |
| **Issues** | Sync data from any source to Jira issues or Product Discovery ideas | Upsert, Update, Insert | [Issues](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-group-issues) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to Jira

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button. Select **Jira** and click **Continue**. You can then authenticate Hightouch to Jira by entering your **Jira Domain**, **Username**, and **API Token** from your Jira account:

* the **Jira Domain** is the text before `.atlassian.net` in the URL,
* **Username** is the email you use to login to Jira,
* and if you don't already have an **API Token**, you can create one in your Jira account by navigating to **Account Settings** > **Security** > **Create and manage API tokens**.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-jira-setup.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1b9e54d6f7eb082434435608b2dc3c11)

## Sync configuration

Once you've set up your Jira destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and the Jira destination you want to sync to.

### Syncing issues and ideas

Hightouch supports syncing to Jira [issues](https://support.atlassian.com/jira-software-cloud/docs/what-is-an-issue/) and [Product Discovery ideas](https://support.atlassian.com/jira-product-discovery/docs/what-is-an-idea/). If you want to sync to Product Discovery ideas, select a [**Product Discovery Project**](https://www.atlassian.com/software/jira/product-discovery) in your sync configuration and use [Insert](#supported-syncing) mode.

#### Record matching

Upsert and Update mode are only supported for Jira issues. They require you to create a **custom
field** in Jira to use for record matching in Hightouch. This field needs to be set to the [**Text Field (read only)**](https://support.atlassian.com/jira-cloud-administration/docs/custom-fields-types-in-company-managed-projects/#Advanced-custom-field-types) type.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-jira-customfield-mapping.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f21985adec17ba40669a0a4e205c29f0)

To create a **custom field** in Jira:

* Navigate to **Settings** > **Issues** > **Custom Fields**.

  ![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-jira-create-customfield-1.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4a7f7d20074869a4c614bcb5be893fd9)

* Click **Create custom field** and select the [**Text Field (read only)**](https://support.atlassian.com/jira-cloud-administration/docs/custom-fields-types-in-company-managed-projects/#Advanced-custom-field-types) field type.

  ![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-jira-create-customfield-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a7f0a952bc6106ca85bd82814fe87188)

> [!TIP]
>
> Ensure all issue fields and custom fields that you want to sync to are
> included on your project's screen. To add custom fields to the
> screen, navigate to the custom field, click the three-dot menu and then **Associate to Screens**.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-jira-add-screen.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d39c2378b973ce10fb3668e8cec58a45)

#### Field mapping

You can map model columns to all Jira issue fields that are available to the **Project** and **Issue Type** you selected in your sync configuration. To sync successfully, ensure the **Description** field is in [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) and that these other fields are of these types:

* `parent` > `id`
* `priority` > `name` (for example, Highest, High, Medium, Low, or Lowest)
* `creator` > `accountId`
* `assignee` > `accountId`
* `reporter` > `accountId`

> [!NOTE]
>
> Hightouch doesn't currently support syncing to [Status fields](https://confluence.atlassian.com/adminjiraserver/defining-status-field-values-938847108.html), so this needs to be done manually in the Jira dashboard. Please [reach out to us](#pylon-chat)  if you're interested in this feature.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-jira-fieldmappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4d8d78c608b777f4963389d7aaffc45e)

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).