Freshdesk Connector

Last updated
Save as PDF

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:

Navigate to Administration > Connectors 2.0 page.
Click Create Connection. The Create connection window is displayed.
From the Connector dropdown, select Freshdesk.
Enter Name and Subdomain of the Connection in the respective fields.
Enter the API Key.
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:

Four datasets are created on the following four Objects:
- Incidents
- Companies
- Contacts
- Agents
These datasets are merged and then mapped to the target Gainsight object.
In the Add to Destination, Source fields from the final merged dataset are mapped with the target Gainsight fields through Direct Mappings.
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:

Freshdesk Agent object is selected as the source object in the dataset preparation and the source fields are selected.
A filter is added to filter the incidents created by Agents.
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.

Additional Resources

For more information about Connectors, refer to the following articles: