Skip to main content
Gainsight Inc.

Salesforce Connector

IMPORTANT NOTE: 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 how to create a connection from Gainsight to Salesforce, create a data job, and configure job or Job chains in Gainsight. You can learn about Out of the Box (OOB) Jobs and Job Chain provided by Gainsight in the Salesforce Integration. You can sync data from any SFDC object to Gainsight Standard or Custom objects. To learn more about Gainsight objects, refer to the Gainsight Data Management in the Additional Resources section at the end of this article.

Note: This document provides general guidance on creating a Connection, configuration of OOB jobs, and setting up custom Jobs because the 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 Resources section at the end of this article.

Overview

Salesforce is a cloud-based Customer Relationship Management (CRM) solution that helps organizations to effectively streamline their sales and marketing operations.

Gainsight integration with Salesforce allows you to sync data from Salesforce objects to Gainsight. The following table lists the equivalent Gainsight Objects to which data is synced from Salesforce.

Salesforce Object Gainsight Object
Account Company
User User
Contact Person and Company Person
Any Salesforce Object Custom Object

Benefits

  • Access Gainsight NXT through Salesforce Login.
  • Access Gainsight data through Gainsight widget in Salesforce.
  • Gainsight Integration with Salesforce is bidirectional, which means sync data, and activities, tasks, and opportunities from Gainsight to Salesforce to Gainsight and vice-versa.
  • Create reports on Salesforce data, analyse them in Gainsight and take necessary actions on the critical issues to achieve Customer Success.
  • Provide business solutions offered by Gainsight on Salesforce data like Renewal Management, Customer Health Scoring, Usage data analytics using Adoption Explorer, Configure Surveys and Programs, etc.

To configure the Salesforce connection, execute three tasks as explained below:

  1. Create and Authorize Connection: Create Connection establishes a connection between Gainsight and Salesforce. Authorizing Connection task authorizes Gainsight to access data from your Salesforce org. To learn more about this process, refer to the Create a Connection section.
  2. (Optional) Modify OOB jobs: This task allows admins to modify the out of the box configurations for OOB jobs. To learn more about this process, refer to the Out of the Box Jobs section.
  3. Create Data sync jobs: This task allows admins to create new data sync jobs per requirement. To learn more about this process, refer to the Create a Custom Job section.

Connection

A connection is a link between a Gainsight org and a specific Salesforce org. You can create a connection either to your Salesforce Production org or Sandbox org. Salesforce Connection also allows you to create a connection to Salesforce org which is configured to a custom domain. After you establish a connection to your Salesforce org, you can authorize the connection and start syncing data from Salesforce to Gainsight through either OOB jobs or custom jobs.

Prerequisite

The SFDC user whose credentials are being used to connect with Salesforce from Gainsight, should have API access in SFDC.

Create a Connection

To create a connection with Salesforce:

  1. Navigate to Administration > Connectors 2.0 > Connections page.
  2. Click Create Connection. The Create Connection dialog appears.
  3. Select Salesforce in the Connector dropdown list.
  4. Enter Name of the Connection.
  5. Select the Salesforce Org type from the dropdown list:
    • Production: When you select this org type, the Authorization window navigates to the login.salesforce.com (if no custom domain is configured) for Authorization.
    • Sandbox: When you select this org type, the Authorization window navigates to the test.salesforce.com (if no custom domain is configured) for Authorization.
  6. (Optional) Switch the toggle ON if your Salesforce org has a custom domain.
  7. (applicable only if the above sub step is executed) Enter the Custom Domain URL of your Salesforce org.  You can use this toggle to create a connection to Salesforce org with custom domain.
  8. Click Authorize to validate the connection. Salesforce OAuth window appears.
  1. Complete authorization by entering the required Salesforce org credentials.

Salesforce login page.png

  1. Click Allow in the Salesforce confirmation dialog.

aloow access.png

Note: If you have already stored your Salesforce credentials in your browser, you are directly prompted to select the stored username.

SF loggin.png

IMPORTANT: You can create only a single connection in Salesforce Connector. A connection can be associated to only a single Salesforce org. If your data resides in multiple Salesforce orgs, you must first delete an existing connection (after you sync the data) and then create a new connection.

Context Menu Options

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

  • Edit Connection: Use this option to modify the Salesforce connection details.
  • Authorize/Re-Authorize Connection: If the existing connection is revoked or Salesforce org credentials are changed, use this option to re-authorize the Salesforce connection and provide the new set of credentials.

    Note: If you change the password of the Salesforce org then the connection from Gainsight with Salesforce is revoked.
     
  • Configure Company Resolution: By default, this option maps Account ID field with Salesforce to SFDC Account ID field in Gainsight. Modify the mapping, as required. Widgets use this mapping to map SFDC Account with Gainsight Company.
  • Link Gainsight to Salesforce: Once you establish a connection to Salesforce org, you must select this option to display the current Gainsight org in the connected Salesforce org. When you select this option, access SFDC objects in the Gainsight Rules Engine and Reporting applications. It is not required to select this option, if you only want to sync data from SFDC org to Gainsight.

    Note: You need to install the Gainsight managed package in your Salesforce org setup for Link Gainsight Tenant to Salesforce org to work properly. For more information, refer to the Install Gainsight in the Additional Resources section at the end of this article. .
  • Delete Connection: Delete the Salesforce connection, if the associated Job Chains and data jobs are deleted.

Context Menu.png

Out of the Box Jobs

After the Salesforce connection and authorization successfully completed, Gainsight provides OOB jobs in the Jobs page to sync important data such as Account, User and Contacts, which are required for the assessment of data in Gainsight. Following are the three OOB jobs and their mapping details:

  • User Sync: This job syncs Salesforce Users with Gainsight.
  • Company Sync: This job syncs Salesforce Accounts with Gainsight Companies.
  • Company Person Sync: This job syncs Salesforce Contacts with Gainsight Person and Company Person objects.

User Sync

This job syncs data from the Salesforce User object and inserts it into the Gainsight User object. User sync is primarily required to grant Salesforce users access to Gainsight NXT. This job is named as User Sync_ Connection name. (here User Sync_Connect to SFDC). In the User Sync OOB job, the following configurations are provided out of the box:

  • SFDC User object is selected as the source object in the dataset preparation and the following source fields are selected.
  • Filters are added to sync Standard and Active users from Salesforce with Gainsight
  • Gainsight User is selected as target object and the Salesforce source fields are mapped with the Gainsight target fields through the Add Destination configuration.

Following are the fields and their Direct Mapping in the Add to Destination:

Salesforce User FieldsTime Zone Target Fields in Gainsight (User)
First Name First Name
Last Name Last Name
Email Email
Time Zone Time Zone
Username Username
Note: Include in Identifiers check box is selected.
Locale Locale
Title User Title
User ID Avatar_SalesforceConnection::Sfdc User Id

Upsert key is used to resolve incoming Salesforce users with the existing Gainsight users. Based on the Upsert key selection, either new Gainsight users are created from the incoming Salesforce users, or associated with the existing users.

This configuration is useful if new users that you are trying to sync through the Salesforce connector may have already been added to Gainsight either through Slack or User Management. If a matching record already exists in Gainsight, the incoming Salesforce user will automatically be associated with that user. If there are multiple matching records found for the Upsert Key criteria, you can navigate to User Management > Avatars > Salesforce Avatar Type to manually associate to one user record. After user records are synced, if multiple records are found matching the upsert key criteria, an error file is generated that directs you to the User Management page to manually resolve to one record.

Following are few use cases to apply configuration for Upsert Key, but you can always configure Upsert Keys as required:

  • If a user is already added through Slack to Gainsight, you can sync Salesforce Users through Salesforce Connector with Email as Upsert key.
  • If a user is already added through the User Management page (Manual or CSV), you can sync Salesforce Users through Salesforce Connector with Name or Email as Upsert key.

Derived mappings

The following table shows configurations for OOB derived mappings for the Manager field:

Fields Values
Target Field: Manager (GSID)
Select Source Manager ID
Source Object User
MATCH BY SOURCE Manager ID
MATCH BY TARGET SFDC User ID
When Multiple Matches Occur Use any one match
When No Matches Are found Insert Null Value(s)
Select Target Field Manager

Company Sync

This job imports data from the Salesforce Account object and inserts it into the Gainsight Company object. By default, this job has a dependency on the User Sync job. Modify the dependent job, as required. This job is named Company Sync_Connection name (here Company Sync_Connect to SFDC).  In the Company Sync OOB job, the following configurations are provided out of the box:

  • SFDC Account object is selected as the source object in the dataset preparation and the following source fields are selected.
  • Gainsight Company is selected as target object and the Salesforce source fields are mapped with the Gainsight target fields through the Add Destination configuration.

Following are the fields and their Direct Mappings in the Add to Destination:

Salesforce Account Fields Target Fields in Gainsight (Company)
Account ID SFDC Account ID
Note: Include in Identifiers check box is selected.
Account Name Name
Employees Employees

Note: Select any other mapping as the Upsert key or even have multiple mappings as Upsert keys, if required. It is mandatory to configure at least one mapping as an Upsert key.

Company Person Sync

This job imports data from the Salesforce Contact object and inserts it into the Gainsight Person and Company Person objects. By default, this job has a dependency on the Company Sync job. This job is named Company Person Sync_ Connection name. (here Company Person Sync_Connect to SFDC). In the Company Person Sync OOB job, the following configurations are provided out of the box:

  • SFDC Contact object is selected as the source object in the dataset preparation and the following source fields are selected.
  • Gainsight Person and Company Person are selected as target objects and The Salesforce source fields are mapped with the Gainsight target fields through the Add Destination configuration.

Following are the fields and their mapping in the Add to Destination:

Salesforce Contact Fields Target Fields in Gainsight (Person)
First Name Person :: First Name
Last Name Person :: Last Name
Email Person :: Email
Note: Include in Identifiers check box is selected.
Contact ID External Contact ID
Account ID External Account ID

Upsert keys for the mapping between the Salesforce Contact object and the Gainsight Person object are determined by the Person Resolution Key configuration. Fields selected in the Person Resolution Key configuration must be selected as Upsert Keys in the Company Person Sync Job > Field Mappings section.

One or multiple upsert keys are used for the identification of people in Gainsight and which cannot be edited. For more information on the Person Resolution Key configuration, refer to the People Management in the Additional Resources section at the end of this article. .

Derived mappings

The following table shows configurations for OOB derived mappings:

Fields Values
Target Field: Company ID (GSID)
Select Source Account ID
Source Object Company
MATCH BY SOURCE Account ID
MATCH BY TARGET SFDC Account ID
When Multiple Matches Occur Mark record with an error
When No Matches Are found Reject Record
Select Target Field Company ID
Target Field: Manager (GSID)
Select Source Reports to ID
Source Object Company Person
MATCH BY SOURCE Reports to ID
MATCH BY TARGET External Contact ID
MATCH BY SOURCE Account ID
MATCH BY TARGET External Account ID
When Multiple Matches Occur Use any one match
When No Matches Are found Insert Null Value(s)
Select Target Field Manager

Currency Sync

Currency Sync Job is created only when Multi-Currency is enabled in the org from the Currency Management page. This job is required to sync currency information such as supporting currencies and conversion rates from Salesforce to Gainsight. In the Currency sync job, data from the CurrencyType (Salesforce source object) is imported to the GS Currency Coefficient (Gainsight target object). 

Following are the fields and their Direct Mappings in the Add to Destination:

 Salesforce CurrencyType Fields Gainsight Currency Coefficient Fields
Conversion Rate Conversion Rate
Currency ISO Code

Currency Code

Note: Include in Identifiers check box is selected.

Corporate Currency Corporate Currency

 

Create a Custom Job

From the Jobs page, create jobs to sync data from any Salesforce source object with Gainsight. Create one dataset from one source object to create a Job. For more information, refer to the Preparation of Connector Jobs in the Additional Resources section at the end of this article.

Note: (Optional) Create multiple data jobs as required. If the data jobs in the connection are dependent on each other, create a Job chain in a sequence and configure the schedule for the Job Chain. For more information, refer to the Job Chain Page in the Additional Resources section at the end of this article.

Limitation: Gainsight does not support Merging two datasets together to create an output dataset.

Add Destination

Once the final output dataset is prepared, 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 Preparation of Connector Jobs in the Additional Resources section at the end of this article.

Direct Mappings

In the Direct Mapping, 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, per field mappings. For more information on Direct Mapping, refer to the Preparation of Connector Jobs in the Additional Resources section at the end of this article.

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, 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, fetch Gainsight IDs (GSIDs) from the lookup object into GSID data type fields. For more information on the Derived mappings, refer to the Preparation of Connector Jobs in the Additional Resources 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

Configure the schedule of a data job as required. For more information, refer to the Configure Job or Job Chain Schedule in the Additional Resources 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.

Configure Job Chains

Gainsight offers an OOB Job Chain SFDC_Company Person Sync for the OOB jobs. This job chain has the OOB jobs in the following sequence:

  1. User Sync
  2. Company Sync
  3. Company Person Sync

This Job Chain is provided as Company Sync job has dependency on User Sync job and Company Person Sync job on Company Sync job. You can configure the schedule of this Job chain as required.

job chain.png

Create a custom Job Chain on the OOB or custom jobs and schedule as required. For more information, refer to the Job Chain Page and Configure Job or Job Chain Schedule in the Additional Resources section at the end of this article.

Job Activities

View the Execution and Update Activities of all the data jobs in the Activity page. Download the logs of the job execution from this page to help troubleshoot the configuration issues. For more information, refer to the Activity Page in the Additional Resources section at the end of this article.

  • Was this article helpful?