Using the Jira field syncing feature

The field syncing feature enables near real time syncing of data between Zendesk Support and Jira. This provides information sharing between the two systems for better collaboration between support and engineering teams. This is done by mapping Jira issue fields to Support ticket fields.

This article contains the following topics:

• Requirements and limitations
• Setting up field syncing

Related articles:

• Configuring Jira WebHook for field syncing
• Setting up Zendesk Support for Jira integration
• Using the Zendesk for Jira integration

Requirements and limitations

• Supported versions: Jira Cloud, Jira Data Center, and Jira Server 7.0 and newer
• The field syncing feature is case-sensitive. Support field values must exactly match with Jira field values
• Once data is synced, it cannot be removed easily. However, you can disable field syncing all together which disables all field links
• Sync direction can be set on a per-field basis, but only one mapping per field is allowed
• Bidirectional syncing of the same field is not supported
• Field mapping screen displays custom field types from all Jira projects in a single list
• All mapped fields for a particular issue or ticket is updated via a single API call. So if a mapped field is misconfigured, all fields will not be updated
• Two or more Jira issues linked to a ticket will stop the sync

Field type syncing compatibility

There are some restrictions on the field types that are compatible for syncing. For example, a Zendesk decimal field with a numeric display cannot sync with a Jira multi-line text field.

The tables below list field mapping compatibility.

Table 1. Zendesk ticket fields and compatible Jira issue fields

Field title/type	Display type	Compatible Jira issue field type(s)
Priority (default)	Drop-down	Text field (read-only) Select list Text field (single line) Text field (multi-line)
Type (default)	Drop-down	Text field (read-only) Select list Text field (single line) Text field (multi-line)
Date (custom)	Date	Date picker Due date
Decimal (custom)	Number	Number field
Numeric (custom)	Number	Number field
Drop-down list (custom)	Drop-down	Text field (read-only) Select list Text field (single line) Text field (multi-line)
Text (custom)	Single line text	Description Environment Text field (read-only) Select list Summary Text field (single line) Text field (multi-line)
Multi-line text (custom)	Multi-line text	Text field (multi-line)

Table 2. Jira issue fields and compatible Zendesk ticket fields

Field title/type	Display type	Compatible Zendesk ticket field type(s)
Description (default)	Multi-line text	Multi-line text
Due date (default)	Date	Date
Environment (default)	Multi-line text	Multi-line text
Fix versions (default)	Fix versions	Text Multi-line text
Priority (default)	Priority (Note: Only syncs from Jira to Zendesk)	Text Multi-line text Drop-down list
Sprint (default)	Sprint	Text Multi-line text
Status (default)	Status	Text Multi-line text Drop-down list
Summary (default)	Single line text	Text Multi-line text
Date (custom)	Date	Text Multi-line text Date
Number (custom)	Number	Numeric Decimal
Read-only text field (custom)	Read-only text field	Text Multi-line text
Select (custom)	Drop-down	Text Multi-line text Drop-down Type Priority
Text field (custom)	Single line text	Text Multi-line text
Text area (custom)	Multi-line text	Multi-line text

Setting up field syncing

Field syncing is set up using a mapping interface.

Note: Field syncing only affects tickets and issues created after the sync feature is set up. It does not update previously created tickets and issues. However, when a previously created ticket or issue is edited or updated, field syncing is applied.

Zendesk Support and Jira have different field types which adds complexity to the syncing process. It requires following certain rules when creating field mapping to ensure syncing works as expected.

Both system (default) and custom fields are supported. However, only a subset of all available field types are supported. Additionally, there are limitations as to which Jira field type can be synced to a Zendesk Support field type, and vice-versa. For instance, a text field cannot be synced to a datetime field. To prevent misconfiguration, the user interface hides field types that are not supported, and greys out invalid mapping options.

Because data synced fields cannot be unsynced, we recommend that you test your field syncing in a test environment or sandbox. If necessary, you can disable the field syncing feature by removing all field mappings. This stops syncing subsequent data changes.

To configure and to enable field syncing

1. Log in to your Jira account with Admin privileges.
2. In the top navigation bar, select Apps > Manage your apps > Zendesk Support for Jira > Configure > Field Mapping.
3. Use the drop-down menus to select the Jira issue ticket field and Zendesk Support ticket fields you want to map.

   

4. Click Add. The synced fields are added to the Field Mapping list.
5. Repeat for additional mapped fields.
6. When finished mapping fields, click Save & Sync.

Note: While we can setup the Jira WebHook for you on Jira Server, Jira Cloud does not support the same functionality. Please follow the instructions in Configuring Jira Cloud WebHook for field sync to set it up manually.

Many-to-one syncing

You can sync a field from a single Jira issue to multiple Zendesk Support tickets, or a field from a single Support ticket to multiple Jira issues. In this case, the syncing only occurs in one direction, from the single issue or ticket to multiple tickets or issues respectively.

However, syncing a field from multiple linked tickets to a Jira issue field, or from multiple Jira issues to a field on a ticket, is not supported. Configuring field sync this way causes syncing to stop for this particular ticket or issue. To link multiple tickets to a Jira issue and use sync, we recommend implementing a problem/incident concept as described in Working with problem and incident tickets.

The Jira issue key is a special case. If multiple issues are linked to the same ticket, all their keys will appear on the ticket.

Syncing closed tickets

Unlike Jira, Zendesk does not allow closed tickets to be updated. This means that when attempting to sync Jira issues to Zendesk tickets, it may fail if the ticket is already closed. You will be able to see this error on the Zendesk Support for Jira add-on Error Report screen.

Errors

Since syncing is something that happens behind the scenes, errors are displayed on a dedicated screen. The error report screen allows the user to identify and resolve invalid field mappings as well as other configuration issues.