Sinergify (Zendesk Jira Connector)

The solution facilitates bi-directional synchronization between Zendesk Support tickets and Jira issues, providing configurable syncing options to control updates between the two platforms.

Installation (Zendesk)

Log into your Zendesk account and navigate to Admin.

Locate the Marketplace under ‘Apps’, and look for ‘Sinergify’ App then click Install.

Authentication (Zendesk)

Please follow the steps below to authenticate the Sinergify Zendesk application via your Jira integration user.

Setting up Application Links in Jira

1. Log into your Jira system as a user with 'Jira Administrator' permissions.

2. Click on the ‘Gear’ (settings) icon.

3. Under the Settings drop-down menu, click ‘System’.

4. Click on the ‘Search Jira admin’ button.

   

5. Enter ‘Application’ in the search bar and click ‘Application links’ from the search results.

   

6. Choose the type of link. Select ‘Direct Application Link’ and then enter the ‘Zendesk URL’ in the Application URL. Select ‘Continue’.

   

7. A new screen will appear to configure the application URL. Select ‘Continue’ again to verify your application URL. The Application URL is in the below format.

   https://your_subdomain.zendesk.com

   

8. Specify an ‘Application Name’ for reference.

   For example, consider the ‘SinergifyZendesk’. Select ‘Generic Application’ as the Application Type. Click on the 'Create incoming link’ checkbox and empty all other options on the form.

   

9. A fresh window will open. Enter the ‘Consumer key’, ‘Consumer Name’, Public Key’. Review the data you've entered, then select ‘Continue’ to confirm and preserve it. If it prompts again, select ‘Continue.’

10. Application Link will be created.

    

Authentication Panel

1. Log in to your Zendesk account and access the ‘Sinergify’ app by navigating from the left panel.

2. A login screen will appear.

   

3. To authenticate on Zendesk, enter the following information and select ‘Save’ once done.

• Jira Instance: Url of Jira Instance.

• Consumer key: The same as what was entered in the application link, for example. ‘SinergifyZendesk’

• Private key:Pair of Public Key entered in the Application Link.

  

4. A warning message appears saying ‘You will lose all the current configuration if it exists. Would you like to continue?.” Click on the ‘Yes’ button if it is your fresh installation.

   

5. A new screen will appear to log into your Jira instance. Once you are logged in, another window will appear asking for the ‘Read’ and ‘Write’ permissions. Select ‘Allow’.

   

6. As soon as you click ‘Allow’, a confirmation pop-up will appear stating that the access has been approved. Close the pop-up window.

   

7. Complete the authentication process by clicking on the ‘Finish’ button.

   

8. As soon as you click the finish button, the authentication screen will appear with the Jira status as ‘Connected.’

   

Project Mapping

Once authentication is done, configure Jira projects on the Zendesk side.

Click 'Next' to transition to the 'Project Mapping' screen or you can click on the Project Mapping tab.

Only those projects for which the integration user has Project-level permissions will be listed here.

Only projects chosen on the 'Project mapping screen' are available for key features such as Create, Search, Link, and Unlink. This ensures precise control over project-related actions.

The checkbox is used for the Syncing action for the particular project.

Once the Projects are decided, choose the specific ‘Issue Types’ for the respective Projects and then click ‘Save’.

Once the Issue Types are saved, select 'Next’ to set up 'Field Mapping'.

Field Mapping

This will allow users to manage mappings between Jira and Zendesk fields seamlessly.

Select the Jira Project from the dropdown to map fields.

Based on the selected project, a comprehensive list of corresponding Jira fields will be displayed.

Map the Jira fields with Zendesk fields based on the selected project. Once done click on the ‘Add’.

Field type syncing compatibility

There are some restrictions on the field types that are compatible with syncing. See the reference below that shows the restricted field types for both platforms.

Restricted Jira Field Type

• multiuserpicker

• userpicker

• user

• datetime

• cascadingselect

• issuelink

• issuetype

• gh-epic-link

  Restricted Zendesk Field Type

• Assignee (Standard Zendesk Field)

• Group (Standard Zendesk Field)

• Credit card

• Regex

• Checkbox

• Lookup relationship

Syncing Target

It enables you to sync updates directly from Zendesk to Jira or vice versa or both. Users have to decide the type of sync according to the business requirements.

1. Jira to Zendesk

   Whenever we update the fields of the Jira issue, linked Zendesk tickets are also updated.

2. Zendesk to Jira

   Whenever there is an update on the fields of Zendesk tickets, the fields of linked Jira issues are also updated.

3. Two-way

   When the target is set to two-way, any update made on either side will update the linked record on the other side.

4. None

   When the target is set to None, auto-syncing will not update the field on the linked records.

Picklist Value Mapping

You can also decide the mapping of picklist values between Zendesk and Jira, which is applicable only for picklist-type fields. To do this, select the Data Mapping icon next to the delete button.

Select the Zendesk picklist value that should map with the Jira picklist value as per business requirements. Select Map once the mapping is done. See the reference screenshot below.

Sync

It is mandatory to click the Sync button after making the changes. Once done select ‘Save’.

View Mode

Whenever the user clicks on the view mode checkbox then the mapped Jira field will not be included on the Create Jira form, this field will be used on the detail screen to see the details.

Only the fields with the view mode checkbox true will be shown on the Jira issue detail screen. There are four types of fields that are shown by default on the Linked Jira issue detail page. Below are the names of the fields that are stored by default.

1. Issue Type

2. Summary

3. Status

4. Priority

   Below is an example of the fields in Zendesk tickets.

   

   In the field mapping section, you can add more relevant fields and check the view mode checkbox as per requirements. This can help to see more details about the Jira issue while not necessarily putting it on the Create Jira screen for Zendesk users. See the screenshot below.

   

   Once you click on save, these fields will also be available on the Jira issue detail page.

   To view these details, click on the detail icon as shown below.

   

   The following page will appear to see the Jira issue details.

   

Points to Remember

Display fields on the Create Screen: When setting up field mapping to display fields on the Create screen, consider the following scenarios:

Handle the fields on the Jira issue Detail screen: When setting up field mapping to display fields on the detail screen, consider the following scenarios, fields marked with * is the required action.

Auto-syncing of the fields: When setting up field mapping for auto-syncing, consider the following scenarios:

Installation (Jira)

Log in to your Jira Instance as an Admin.

Select Apps, and under the drop-down menu, select Find new apps.

Enter the Sinergify (Zendesk-Jira)Connector in the Search for Apps input box and press Enter. Select Get App, and the application will be installed in the background. Follow the below steps once the app is installed.

Authentication (Jira)

1. In the Apps drop-down, select Manage your apps.

   

2. In the left panel, select ‘Authentication’ under ZENDESK PLUGIN.

   

3. Click on the ‘Add New Instance’ Button. A new screen will appear with the Login Status ‘Not Connected’.

   

4. Enter the Zendesk login instance URL along with the Client Key (consumer key) and Client Secret (consumer secret) of your Zendesk app.

5. In the Zendesk Admin Center, open the Apps and Integrations section in the sidebar or search for Zendesk API, then select APIs > Zendesk APIs.

   

6. Click the OAuth Clients tab on the Zendesk API page, and then click ‘Add OAuth client’ under the OAuth client list.

   

7. To Add an OAuth client, fill out the following fields. See the reference screenshot below:

• Client Name: Enter a name for your app. For example, Sinergify Zendesk Integration.

• Description: Optional. This is a short description of your app.

• Company: Optional. You can add the company name for reference.

• Logo: Optional. This is the logo that users will see when asked to grant access to your application.

• Unique Identifier: The field is auto-populated with a reformatted version of the name you entered for your app. You can change it if you want.

• Redirect URLs: Enter the browser URL of the Sinergify Jira plugin Authentication screen.

  

8. After the page refreshes, a new pre-populated Secret field appears on the lower side. This is the ‘client_secret’.

   

9. Copy the Secret value and store it safely as the secret code won’t be visible again after you click ‘Save’ or Leave the page.

   

10. Click ‘Save’.

11. Use the unique identifier and the secret value in the authentication screen on Jira as the Client Key and Client Secret, respectively. Once done click on ‘Login to Zendesk’.

    

12. This will open a new window for authorization. Click ‘Allow’ to allow your Jira Instance to access via the logged-in Zendesk Account.

    

13. The authentication screen on Jira will now reflect the status ‘Connected’.

    

14. The Disable button results in the deactivation of the instance. This action renders the functionality associated with the instance non-operational, with the status ‘Not Connected’.

15. The Delete button involves the permanent removal of the instance; upon clicking this button, all configurations linked to the instance will be deleted from both Zendesk and Jira Instances.