Skip to main content
Gainsight Inc.

Freshdesk Connector

Gainsight NXT

 

IMPORTANT: Gainsight is upgrading Connectors 2.0 with Horizon Experience. This article applies to tenants which have been upgraded to the Horizon Experience for Connectors 2.0. If you are using Connectors 2.0 with the previous version, you can find the documentation here.

This article explains operations related to Freshdesk, like how to create a connection, create a custom job, merge datasets, and configure job or Job chains in Gainsight.

Note: This document provides general guidance on creating a Connection and setting up Jobs because the business use case of each job is different and needs unique configuration. For detailed information on creating any Job, refer to the Configuration of Connectors in the Additional Resource section at the end of this article.

Overview

Freshdesk is a customer support ticketing software or a helpdesk that allows companies to effectively manage their customer care and support function. Gainsight integration with Freshdesk allows you to sync data from these source objects: Incidents, Companies, Contacts, and Agents.

Business Use case: This integration helps sync the data related to support tickets created using Freshdesk and data points like their status and priority, the number of open tickets, etc. You may use this data for assessing the health of your customers in Gainsight.

Create Connection

Create a connection with Freshdesk to sync data with Gainsight such as incidents, accounts, contacts, and agents.

To create a connection with Freshdesk:

  1. Navigate to Administration > Connectors 2.0 page.
  2. Click Create Connection. The Create connection window is displayed.
  3. From the Connector dropdown, select Freshdesk.
  4. Enter Name and Subdomain of the Connection in the respective fields.
  5. Enter the API Key.
  6. Click Save to create the connection.

Note: You can create Jobs after creating a connection. For more information, refer to the Jobs List Page in the Additional Resource section at the end of this article.

Context Menu Options

Once you authorize the connection, configure your connection with one of the following context menu options, as required:

  • Edit Connection: This option modifies the Freshdesk connection details.
  • Re-Authorize Connection: If the existing connection is revoked or Freshdesk user credentials are changed, use this option to re-authorize the Freshdesk connection and provide the new set of credentials.
  • Revoke Authorization: This option revokes the connection from Gainsight with Freshdesk.
  • Delete Connection: Delete the Freshdesk connection, if the associated Job Chains and data jobs are deleted.

Out of the Box Jobs

Gainsight provides two Out Of the Box (OOB) jobs in the Connectors 2.0 > Jobs tab to sync important data such as Incidents and Agents.These OOB jobs are required for the assessment of data in Gainsight after importing data from external applications. The OOB jobs are automatically created when you create a connection between the external application and Gainsight. The following are the two OOB jobs:

  • Sync Freshdesk Incidents with Gainsight
  • Sync Freshdesk Agents with Gainsight

Sync Freshdesk Incidents with Gainsight

The Incidents OOB syncs Freshdesk Incidents data to Gainsight. To get the data on Freshdesk Incidents created by each Contact or Agent in an Organization, the following configurations are provided:

  1. Four datasets are created on the following four Objects:
    • Incidents
    • Companies
    • Contacts
    • Agents
  2. These datasets are merged and then mapped to the target Gainsight object.
  3. In the Add to Destination, Source fields from the final merged dataset are mapped with the target Gainsight fields through Direct Mappings.
  4. In the Add to Destination, Derived mapping is used to populate the Gainsight GSID of the Contacts and Agents who created the tickets in the target object.

Note:

  • Gainsight strongly recommends you not to uncheck the mapping between Company ID (from the Companies Object) and Source Org ID (from the Case Object) in the Add to Destination as it may fail to load data into Company fields for the respective Incidents.
  • If you are doing historical sync for the Cases Standard job and the data is very huge, i.e., more than 100K records, then kindly reach out to Gainsight support to increase the default job run time to eight hours.

pasted image 0.png

Preparation of Datasets

The following fields are selected in each Freshdesk object while creating a dataset:

Freshdesk Incidents Fields Freshdesk Company Fields Freshdesk Contact Fields Freshdesk Agent Fields
ID ID ID ID
Updated at Updated at Updated at Updated at
Description Name Email Email
Status      
Priority      
Subject      
Email      
Name      
Requester      
Source      
Responder ID      
Company ID      

Fields and Criteria in the Merges

The following are the fields and merge criteria selected in the following objects merge:

  • Incidents+Companies:
    Join Type: Left
    Incidents Companies
    ID, Updated At, Description,Status, Priority, Subject, email, name, Requester, Source, responder_id, Company_ID ID, Updated At, Name
    Merge Criteria: Incidents : Companies = Company ID : ID
  • Companies+Incidents+Contacts:
    Join Type: Left
    Incidents+Companies Contacts
    ID, Updated At, Name, Incident ID, Incident_updated_at, Description, Status, Priority, Subject, Email, Incident_Name, Requester, Source, Responder_ID, Company_Id ID, Updated_At, Email
    Merge Criteria: Incidents+Companies : Companies = Requester : ID
  • Companies+Incidents+Contacts+Agents:
    Join Type: Left
    Organizations+Users+Tickets Agents
    ID, Updated At, Name, Incident ID, Incident_updated_at, Description, Status, Priority, Subject, Email, Incident_Name, Requester, Source, Responder_ID, Company_Id, Contact_ID, Contact_updated_ID, Contact_Email ID, Updated_At, Email
    Merge Criteria: Companies+Incidents+Contacts : Agents = Responder_ID : ID

Transform

The following fields are selected in the Transform dataset:

Companies+Incidents+Contacts+Agents+Case Fields:

Companies+Incidents+Contacts+Agents Case Fields
ID, updated_at, name, incident_id, incident_updated_at, description, Subject, Company_Id, contact_id, contact_updated_at, contact_Email, agent_id, agent_updated_at, agent_email Transformed_status, transformed_priority

 

Add to Destination Configuration

The following are the details of Direct Mapping and Derived Mapping:

Direct Mappings

The following table explains the Direct Mapping between the final Merged dataset (Incidents+Companies+Contacts+Agents) and the target Gainsight object (Case):

Final Merged Dataset fields Gainsight Case Object fields
incident_id External Id
Note: Include in Identifiers check box is selected.
updated_at Created Date at Source
description Case Description
trasnformed_priority Case Priority
transformed_status Case Status
Subject Case Subject
Company_Id Source Org ID
incident_updated_at Modified Date at Source
Derived Mappings

In the Derived Mapping tab, the following table explains the values that are selected for the Derived mapping configurations:

Fields Values
Target Field: Requester ID (GSID)
Source Field contact_Email
Select the intermediate object Person
Field in Intermediate Object Email
When Multiple Matches Occur Mark record with an error
When No Matches Are found Insert Null Value(s)
Gainsight Field Requester ID
Target Field: Company ID (GSID)
Source Field name
Select the intermediate object Company
Field in Intermediate Object Name
When Multiple Matches Occur Mark record with an error
When No Matches Are found Reject Record
Gainsight Field Company ID
Target Field: Assignee ID (GSID)
Source Field agent_email
Select the intermediate object User
Field in Intermediate Object Email
When Multiple Matches Occur Mark record with an error
When No Matches Are found Insert Null Value(s)
Gainsight Field Assignee ID

Note: Cases Sync Job will ingest all records even if the organization is not present against an Incident. To exclude these records, kindly apply a filter where organizations are not null.

For more information on how to configure the data jobs, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Sync Freshdesk Agents with Gainsight

The Agents OOB job syncs active Freshdesk agents to Gainsight. To get the data on Freshdesk Incidents created by each Agent in an Organization, the following configurations are provided:

  1. Freshdesk Agent object is selected as the source object in the dataset preparation and the source fields are selected.
  2. A filter is added to filter the incidents created by Agents.
  3. In the Add to Destination, Freshdesk source fields are mapped with the Gainsight target fields.

Note:

  • In Agents Sync job, only the fields from Agent object can be selected as Identifiers. Fields from Avatar objects cannot be selected as Identifiers.
  • The Match Criteria or Resolution key will be set as identifier.

pasted image 0 (1).png

The following are the fields and their mapping in the Add to Destination:

Source Agent Fields Target Fields in Gainsight (User)
id Avtar_<<connection name>>:: Freshdesk User
contact.active Avtar_<<connection name>>::Active
contact.email Username
Note: Include in Identifiers check box is selected.
contact.name Name
updated_at NA

For more information on how to configure the data jobs, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Create a Job

Create jobs from the Jobs page to sync Freshdesk incidents, accounts, contacts, and agents with Gainsight. You can create a dataset from one source object, likewise you can create as many as you need to create a Job. For more information how to create a job, refer to the Jobs List Page in the Additional Resource section at the end of this article.

Notes:

  • While importing the ticket data through a data job, the maximum of 300 pages with 9000 tickets data can be returned in response.
  • By default, tickets that are created in the last 30 days will be returned in response. To return older tickets, use the updated_since filter.
  • (Optional) You can create multiple data jobs as required. If the data jobs in a connection are dependent on each other, create a Job chain in a sequence and configure schedule to the Job Chain. For more information, refer to the Job Chain Page in the Additional Resource section at the end of this article.
  • Gainsight doesn’t support fetching all records from a multi-picklist data type field. Only the first value from an array or multi-picklist data type will be imported into Gainsight if you map the field using direct mapping.

Merge Datasets

Merge two or more datasets together and create an output dataset. For example, you can merge Incidents and Contacts datasets to know the list of Contacts creating the Incidents and number of Incidents created by each contact. For more information on Merge, refer to the Jobs List Page in the Additional Resource section at the end of this article.

Transform Data 

In the Preparation step of a connector job, admins can Transform data and Add Case Fields to get more meaningful insights from the customer data. 

Example Business use case: The Transform function provides the capability to create or modify new case fields. The new case fields can be used to modify the external field as per the consumption requirement in Gainsight’s data model. Case fields can be defined to populate different values for different case conditions. For example, External picklist values such as New, Open, and Closed can be modified to Active and Inactive to match Gainsight’s picklist values.

For more information on Transform Data, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Add Destination

Once the final output dataset is prepared, you can add a destination to the output dataset to sync data from the source to the target Gainsight object. For more information on Add Destination, refer to the Jobs List Page in the Additional Resource section at the end of this article.

Direct Mappings

In the Direct Mapping, you should map fields from the output dataset to the target object in the field mappings. Data sync happens from the source fields of the external system to the target fields of Gainsight, based on the configured field mappings. For more information on Direct Mapping, refer to the Jobs List Page in the Additional Resource section at the end of this article.

Note: Gainsight doesn’t support fetching all records from a multi-picklist data type field. Only the first value from an array or multi-picklist data type will be imported into Gainsight if you map the field using direct mapping.

Derived Mapping

This is optional and you must configure the derived mappings only if you want to populate values into the target fields of data type GSID. GSID values are populated from the same or another object through lookup. In this stage, you can create Lookup mapping in a data sync job. You can have a lookup to the same object or another standard object and match up to six columns. Once the required matching is performed, you can fetch Gainsight IDs (GSIDs) from the lookup object into GSID data type fields. For more information on the derived mappings, refer to the Jobs List Page in the Additional Resource section at the end of this article.

Note: To use Derived Mappings, your Target Object must have at least one field of data type GSID.

Configure Job or Job Chain

You can configure the schedule of a data job or Job chain as required. For more information, refer to the Configure Job or Job Chain Schedule in the Additional Resource section at the end of this article.

If you create a Job Chain by adding multiple Jobs in a sequence and add a schedule to the Job Chain, the schedule of the individual jobs is not honored.

Job Activities

You can view the Execution and Update Activities of all the data jobs in the Activity page. You can also download the logs of the job execution from this page. For more information, refer to the Activity Page in the Additional Resource section at the end of this article.

  • Was this article helpful?