YouTrack Server 2023.3 Help

Zendesk Integration

The integration between Zendesk and YouTrack helps you keep customer communication synced between both tools.

When the integration with Zendesk is enabled and configured in YouTrack, it works as follows:

  • When a new ticket appears in Zendesk, it creates a new ticket in YouTrack.

  • The ticket in YouTrack has a link to the corresponding ticket in Zendesk.

  • Ticket updates are synced both ways: changes from YouTrack are synced to Zendesk, and vice versa.

Prerequisites

To create a new integration with Zendesk, make sure you meet the following prerequisites.

  • Your YouTrack is accessible to inbound connections.

  • The Zendesk user account you use to generate an API token has the Admin role.

Setup

To enable and configure the Zendesk integration, follow these steps:

  1. Create a Helpdesk project in YouTrack.

  2. Generate an API token for your user account in Zendesk.

  3. Connect to a Zendesk site.

  4. Create a mapping between a Helpdesk project in YouTrack and a Zendesk brand.

Create an API Token in Zendesk

To set up an integration with Zendesk, first, you need to create an API token for your user account in Zendesk.

To create an API token in Zendesk:

  1. In Admin Center in Zendesk, click Apps and integrations.

  2. Select Zendesk APIs.

  3. Click the Settings tab and make sure the Token Access option is enabled.

  4. Click the Add API token button.

  5. Copy the API token to enter it in the integration setup dialog.

For more details on creating API tokens, refer to the Zendesk documentation.

The API token in Zendesk

Connect to a Zendesk Site

To set up an integration with Zendesk, you need to connect to your Zendesk site first.

To connect to a Zendesk site:

  1. From the Administration menu in YouTrack, select Integrations > Zendesk integration.

  2. Click the New Zendesk Integration button.

    • The New Integration form opens.

    New Zendesk integration form
  3. Enter the following settings:

    Setting

    Description

    URL

    The URL of your Zendesk site.

    Email

    The email address for the user account you use to connect to Zendesk.

    Token

    The API token that you use to authenticate the Zendesk user account.

    Import script package

    The package that contains the scripts for importing data from Zendesk. The default package is @jetbrains/youtrack-zendesk-client/zendesk-integration-client.

  4. Click the Save button.

    • Your YouTrack is connected to the Zendesk site.

    • In the background, a new import configuration has been added to your YouTrack. When you add a mapping to the Zendesk integration, YouTrack will update the project mapping in the import configuration, and the import will run continuously.

      To check the details of this import configuration, open the Administration menu and select Integrations > Imports page.

      To learn more about imports in YouTrack, see Imports.

Create a Mapping

To configure an integration of a YouTrack project with a brand in Zendesk, set up a mapping.

To create a mapping:

  1. On the Zendesk Integration page, click the New Mapping button.

    • The New Mapping dialog opens.

    The New Mapping dialog
  2. Provide values for the following settings:

    Setting

    Description

    YouTrack project

    The Helpdesk project in YouTrack where tickets from Zendesk will be imported.

    Zendesk brand

    The tickets from this Zendesk brand will be synced with the tickets in YouTrack.

    Status field

    The name of the custom field in YouTrack that stores the ticket status from Zendesk.

    Additional filter

    Additional criteria for choosing which Zendesk tickets are shared with the selected YouTrack project. For filtering, use the Zendesk query language.

    Sync tags

    Enable this option to sync tags between YouTrack and Zendesk.

    Sync custom fields

    Enable this option to sync custom fields and their values between YouTrack and Zendesk.

    Group

    All tickets in YouTrack created from tickets in Zendesk will have default visibility restricted to this user group.

  3. Click the Save button.

    A Zendesk integration mapping
    • A mapping between a YouTrack project and a Zendesk brand is created. The Zendesk integration is set up and active.

    • In the background, the import configuration that connects YouTrack and Zendesk is updated. The project mapping in the import configuration now connects the selected YouTrack project and the Zendesk brand.

      The import configuration between YouTrack and Zendesk is set up and active.

      Zendesk import configuration
    • In the background, the Zendesk client workflow is attached to the YouTrack project.

      Zendesk client workflow

Use the Zendesk Integration

Zendesk Integration in Action

When a ticket appears in Zendesk, YouTrack processes it and determines whether or not it matches the mapping.

A ticket in Zendesk

If the Zendesk ticket matches the settings in the mapping, a corresponding ticket is created in YouTrack.

YouTrack issue

YouTrack creates new tickets as follows:

  • YouTrack stores the current state of the Zendesk ticket in the custom field set in the integration settings.

  • If YouTrack finds a user account matching the original requester's email, this user is set as the ticket reporter. Otherwise, YouTrack creates a new reporter account.

The single issue view shows a link to the corresponding ticket in Zendesk.

link to Zendesk ticket in issue

When you write a comment or change a custom field value in the YouTrack ticket, the change is imported into Zendesk and vice versa. For more details on how the integration works and syncs data, see Technical Details.

If you write an internal comment to a ticket in Zendesk, it appears in YouTrack as a private comment visible to the

Technical Details

Behind Zendesk integration, there are two script packages:

  • An import script pulls changes from Zendesk to YouTrack.

  • A workflow propagates changes from YouTrack to Zendesk.

Direction

Details

Zendesk -> YouTrack

Powered by the @jetbrains/youtrack-zendesk-client/zendesk-integration-client script package

Asynchronous. Changes from Zendesk get pulled to YouTrack periodically in small batches.

All data from Zendesk tickets gets pulled to YouTrack. For the full list of entities and their attributes that YouTrack imports from Zendesk, see Imported Entities.

YouTrack -> Zendesk

Powered by the Zendesk client workflow package.

Synchronous. Changes from YouTrack get pulled to Zendesk immediately.

All changes from YouTrack get pulled to Zendesk with the following exceptions:

  • Zendesk integration doesn't create any new tickets in Zendesk.

  • Zendesk integration doesn't create any new user accounts in Zendesk.

Migrate Zendesk Integration from the Old Scheme

Starting from version 2023.1, we've updated the integration with Zendesk. Previously, the integration was based on sharing agreements between Zendesk and YouTrack. Now, this integration works using workflows and import scripts under the hood.

Once your YouTrack is updated to version 2023.1, the following happens:

  • Sharing-based Zendesk integrations will pause syncing changes between YouTrack and Zendesk until you migrate to the new scheme.

  • Users with the System Admin role in YouTrack will see a warning in their notification center. This warning will prompt them to migrate the Zendesk integration to the new scheme.

    A warning about migrating the Zendesk integration to the new scheme
  • When the YouTrack administrator opens the Administration menu > Integrations > Zendesk Integration page, they will see warnings prompting them to migrate the integration to the new scheme.

    A warning about migrating the Zendesk integration to the new scheme

    For details about how to migrate, see below.

To migrate an integration with Zendesk to the new scheme:

  1. From the Administration menu, select Integrations > Zendesk integration.

  2. Select the Zendesk integration in the list.

    • The details panel for the integration opens.

    A zendesk integration that needs to be migrated to the new scheme
  3. From the details panel, click the re-authorize link to reconnect YouTrack with Zendesk.

    • The connection settings open in the details panel.

    Connection settings for a Zendesk integration
  4. Enter values for the connection settings. For details, see Connect to a Zendesk Site.

  5. Click the Save button.

    • The connection settings for the Zendesk integration are updated.

    To proceed with the migration, you must also update the mapping between a project in YouTrack and a Zendesk brand. YouTrack creates a mapping template based on the previous settings of the Zendesk integration.

  6. Select the mapping from the list.

    • The details panel for the mapping opens.

    Mapping settings for a Zendesk integration
  7. In the details panel for a mapping, click the Migrate button.

    • The migrate mapping dialog opens.

    Migrate mapping dialog
  8. Select the Zendesk brand and additional criteria for filtering tickets that will be synced between Zendesk and YouTrack.

  9. Click the Migrate button.

    • The Zendesk integration is fully migrated to the new scheme and is active.

    • YouTrack starts pulling updates from Zendesk again, including updates made while the integration was inactive.

    • The sharing agreement in Zendesk has been deleted.

    • A new import configuration has been added to your YouTrack.

    • The Zendesk client workflow is attached to the YouTrack project.

Starting from version 2023.1, you can only create Zendesk integrations using the new scheme. All newly created integrations with Zendesk follow the new scheme automatically.

Available Actions

When you select a Zendesk integration from the list, the following actions are available:

Action

Description

Edit

Edit the connection settings.

Delete

Delete the Zendesk integration and all the mappings. Tickets, users, and groups that are already imported remain in YouTrack. The links to Zendesk tickets are removed from tickets in YouTrack.

When you select a mapping from the list, the following actions are available:

Action

Description

Edit

Edit the mapping settings.

Disable

Disable the mapping. The Zendesk integration is paused. No updates are synced between YouTrack and Zendesk.

Enable

Enable the mapping. The Zendesk integration is active again. Updates that were made while the integration was inactive are pulled into YouTrack.

Delete

Delete the mapping. Tickets, users, and groups that are already imported remain in YouTrack.

Last modified: 22 March 2024