Skip to main content
Gainsight Inc.

Salesforce Connector

Gainsight NXT

This article supports Gainsight NXT, the next evolution of the Customer Success platform. If you are using Gainsight CS Salesforce Edition, you can find supporting documentation by visiting the home page, and selecting CS > Salesforce Edition.

Not sure what your team is using? Click here.

 

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 to admins about how to create a connection from Gainsight to Salesforce, create data jobs with or without real time sync, Job Chain, and Out of the Box (OOB) Jobs provided by Gainsight.

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 pull data from Salesforce to Gainsight. You can edit the OOB jobs to enable real time sync or create custom real time jobs. However, you can only create one job with real time sync for each object.   

The following table lists the equivalent Salesforce and Gainsight Objects to which data can be synced from Salesfoce.

Salesforce Object Gainsight Object
Account Company
User User
Contact Person and Company Person
Cases Cases
Any Salesforce Object Custom (Customer defined)

Benefits

  • Access Gainsight NXT through Salesforce Login.
  • Access Gainsight data through Gainsight widget in Salesforce. 
  • Gainsight Integration with Salesforce is bidirectional, which means you can sync data, and activities, tasks, and opportunities between Salesforce and Gainsight.
  • Sync data in real time from Salesforce’s Account, Contact and Cases objects to Gainsight. However, real time bidirectional sync between Salesforce and Gainasight is not available.
  • Create reports on Salesforce data and analyse them in Gainsight. You can 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 sync data from Salesforce, you must execute the following three steps:

  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 organization. For more information 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. For more information 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. For more information 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. 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, authorize the connection and start syncing data from Salesforce to Gainsight through either OOB jobs or custom jobs.

IMPORTANT: You can create only one Salesforce connection in Gainsight. 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.

Prerequisite

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

Create a Connection

To create a connection with Salesforce:

  1. Navigate to Administration > Connectors 2.0 > Connections page.
  2. Click Create Connection. Create Connection dialog is displayed.
  3. In the Connector dropdown, select Salesforce
  4. In the Name of the connection field, enter a unique name of the connection.
  5. In the Salesforce Org type dropdown, select any of the following organization type:
  • 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.
  1. (Optional) Switch the toggle ON if your Salesforce org has a custom domain. You can use this toggle to create a connection to Salesforce org with a custom domain.
  2. (applicable only if the above sub step is executed) In the Custom Domain URL field, enter the URL of your Salesforce org.  
  3. Click Authorize to validate the connection. Salesforce OAuth window is displayed.

unnamed.gif

  1. Complete authorization by entering the required Salesforce org credentials and click Allow in the Salesforce confirmation dialog.

Salesforce login page.png

IMPORTANT:

  • Once you establish a connection to the Salesforce org, you must select Link Gainsight to Salesforce from the context menu of the Salesforce connector to display the current Gainsight org in the connected Salesforce org.
  • When you select this option, you can access Salesforce 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 Salesforce org to Gainsight.
  • For Gainsight NXT with Salesforce Connector, you must install the Gainsight managed package in your Salesforce org setup to link Gainsight tenant to Salesforce. For more information, refer to the Install and Configure Gainsight NXT in Salesforce in the Additional Resources section at the end of this article.

1.png

Multi-Salesforce Connections

Admins can now pull data from two Salesforce instances through Connector jobs. You can create two Salesforce connections in the Connections tab.

IMPORTANT:

  • The first Salesforce connection will have all the OOB jobs available in it. The second Salesforce connection will have only User Sync and Currency Sync as OOB jobs. Admin needs to create custom jobs to load data into respective objects through the second connection.
  • Admin can link any one of the two Salesforce connections via the Link Gainsight to Salesforce option. We will refer to such a connection (which is linked via the  Link Gainsight to Salesforce option) as the linked connection
  • Write back capability to Salesforce that is available in application areas like Renewal Center, Cockpit, Timeline etc. will be available only for the linked Salesforce connection. For more information about how to link Gainsight to Salesforce, refer to the Context Menu Options section.
  • Rules Engine, Data Designer, Renewal Center, Surveys, Cockpit, and Reports will only recognize linked Salesforce connection.
  • It is recommended that SFDC Account Id in Company object is not used as the unique identifier for the unlinked connection. Instead, a custom field could be created in the Company object to store SFDC Account Id.
  • The Link Gainsight to Salesforce option won’t be available for a Salesforce connection if another Salesforce connection is already linked.
    • If there is a need to link Gainsight to another Salesforce account, then the user has to reauthorize the first connection with the credentials for a different Salesforce account and create or modify jobs as per the schema of the different Salesforce account.
    • If Admin tries to unlink a connection and link another connection, it won’t be allowed and an error message will be displayed. In other words, switching of linked connections is not allowed.
    • If Admin tries to delete a connection which was earlier linked, a warning message will be displayed.
    • Given the Admin has deleted a connection which was earlier linked, when they try to link any other connection, then a warning message will be shown and no modification would be done to the jobs in that connection and rest of the OOB jobs won’t be automatically created.
  • Given two Salesforce connections are created and none of those are linked:
    • The Link Gainsight to Salesforce option will be available for both the connections.
    • If Admin links the second connection (which does not have all the OOB jobs), the rest of the OOB jobs won’t be created automatically in the second connection.

A sample flow has been explained below:

Multi-sfdc flow.png

Context Menu Options

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

  • Edit Connection: You can 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, you can 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 Salesforce Account ID field in Gainsight. You can modify the mapping, if required. Widgets use this mapping to map Salesforce 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, you can access Salesforce 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 Salesforce 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 article.

  • Refresh Metadata: Admins can manually refresh the Salesforce data by clicking Refresh Metadata. Admins must manually refresh the metadata to see the new custom Gainsight Object or fields added in Salesforce.

Note: The Salesforce metadata will be automatically stored and refreshed every seven days

  • Delete Connection: You can delete the Salesforce connection, if the associated Job Chains and data jobs are deleted. However, the associated data with the connection is not deleted in Gainsight.

2.png

Out of the Box Jobs

After the Salesforce connection and authorization is 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 Person and Company Person objects in Gainsight.
  • Currency Sync: This job syncs currency information such as supporting currencies and conversion rates from Salesforce to Gainsight.
  • Cases Sync: This job syncs cases/tickets information from Salesforce to Gainsight.
  • Company Teams: (optional) This job syncs company teams data from Salesforce to Gainsight. For more information about the OOB job, refer to the Salesforce Connector Job section in the Teams article.

Note: Gainsight offers few OOB Jobs for Renewal Center, which will be created for customers who have Renewal Center enabled in their org. For more information about Renewal Center OOB jobs, refer to the Salesforce Connector Jobs for Renewal Management article.

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. In the User Sync OOB job, the following configurations are provided out of the box:

  • Salesforce User object is selected as the source object in the preparation and the 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.

Add to Destination

In the Scheduled Fields tab, you can see Direct Mapping and Derived Mapping of the fields.

Direct Mapping

The following are the fields and their direct mappings:

Salesforce User Fields 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

Note: In the User Sync jobs, only the fields from User Object can be selected as Identifiers. fields from Avatar objects cannot be selected as Identifiers.

Derived mappings

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

Fields Values
Select Source Manager ID
Select Target Field Manager
Source Object User

MATCH BY SOURCE

Manager ID

MATCH BY TARGET

Salesforce User ID

When Multiple Matches Occur

Use any one match

When No Matches Are found

Insert Null Value(s)

Upsert Key

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.

The 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 the Salesforce Connector with Email as the Upsert key.
  • If a user is already added through the User Management page (Manual or CSV), you can sync Salesforce Users through the Salesforce Connector with Name or Email as Upsert key.

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. You can modify the dependent job, if required. In the Company Sync OOB job, the following configurations are provided out of the box:

  • Salesforce Account object is selected as the source object in the 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 to Destination configuration.

Add to Destination

In the Scheduled Fields tab, you can see Direct Mapping of the fields.

Salesforce Account Fields Target Fields in Gainsight (Company)

Account ID

Salesforce Account ID

Note: Include in Identifiers check box is selected.
Account Name Name
Employees Employees

Note: You can 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.

3.png

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 Salesforce). In the Company Person Sync OOB job, the following configurations are provided out of the box:

  • Salesforce 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.

Add to Destination

In the Scheduled Fields tab, you can see Direct Mapping and Derived Mapping of the fields.

Direct Mapping

The following are the fields and their direct mapping:

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

There can be one or multiple upsert keys used for the identification of people in Gainsight and these cannot be edited. For more information on the Person Resolution Key configuration, refer to the People Management article.

Derived mappings

The following table shows configurations for derived mappings:

Fields Values
Select Source Account ID

Select Target Field

Manager

Source Object

Company

MATCH BY SOURCE

Account ID

MATCH BY TARGET Salesforce 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)

Currency Sync

Currency Sync Job is created only when Multi-Currency is enabled in the org from the Currency Management page. This job syncs 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). 

The 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

Opportunity Sync

This OOB job syncs data from the Salesforce Opportunity object to Gainsight’s GS Opportunity object. For more information about Opportunity job, refer to the Salesforce Connector Jobs for Renewal Management article

Cases Sync

This job syncs cases/tickets information from Salesforce to Gainsight.

Add to Destination

In the Scheduled Fields tab, you can see Direct Mapping and Derived Mapping of the fields.

Direct Mapping

The following are the fields and their direct mapping:

Salesforce Case Fields Target Fields in Gainsight (Case)

Case Number

External Id

Note: Include in Identifiers check box is selected.

Case Type

Case Type

Description

Case Description

Priority

Case Priority

Subject

Case Subject

Status

Case Status

Account ID

Source Org ID

Last Modified Date

Modified Date at source

Case Id

External System Id

Derived Mapping

The following table shows configurations for derived mappings:

Fields

Values

Select Source

Email

Select Target Field

Assignee ID

Source Object

User

MATCH BY SOURCE

Email

MATCH BY TARGET

Email

When Multiple Matches Occur

Mark record with an error

When No Matches Are found

Insert Null Value(s)

Select Source

Email 1

Select Target Field

Requester ID

Source Object

Person

MATCH BY SOURCE

Email 1

MATCH BY TARGET

Email

When Multiple Matches Occur

Mark record with an error

When No Matches Are found

Insert Null Value(s)

Select Source

Name

Select Target Field

Company ID

Source Object

Company

MATCH BY SOURCE

Name

MATCH BY TARGET

Name

When Multiple Matches Occur

Mark record with an error

When No Matches Are found

Insert Null Value(s)

Create a Custom Job

In the Jobs page, you can create jobs to sync data from any Salesforce to Gainsight. You can sync data from one Salesforce object to Gainsight Object through jobs, however you can create multiple data jobs to sync data from all Salesforce objects.

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.

Note: If the Field name is changed in Salesforce, then you must remove and re-add that field in Connector jobs for the change to take effect.

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

For more information on how to create custom jobs, refer to the Job List Page article in the Additional Resources section at the end of this article.

Job Chain

The Job Chain feature helps simplify the process of scheduling a group of related Jobs that you need to run in a particular sequence. This sequence is based on the scheduled time of the Job Chain. For example, if Job A and B are in a sequence, ‘Job B‘ automatically starts as soon as ‘Job A’ completes, and there is no need to schedule a job separately.

Note: 

  • If a Job is added in a Job Chain, then the individual job schedule is ignored and the Job Chain’s schedule is considered and the jobs are run as per the sequence of the jobs in the Job Chain.
  • Real time sync jobs do not honor Job Chain’s schedule. 

Business Use Case: If Admins want to sync tickets data into cases object in Gainsight, they need to sync the users data before syncing tickets data. This is required so that important ticket information like assigned and requester are populated in the respective fields without any error.

For more information on the Derived Mappings, refer to the Job Chain page in the Additional Resources section at the end of this article.

Gainsight offers an OOB Job Chain Salesforce_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.

4.png

You can 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 articles.

Configure Job or Job Chain

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 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.

Note: Real time sync jobs do not honor Job Chain’s schedule. 

Job Activities

You can view the Execution and Update Activities of all the data jobs in the Activity page. You can also download the error logs of the jobs from this page. For more information, refer to the Activity Page article.Configure Job

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.

Real-Time Sync

Gainsight's integration with Salesforce allows you to pull data from Salesforce to Gainsight. You can edit OOB jobs including Accounts, Contacts and Cases objects to enable Real-Time sync or create custom jobs with Real-Time sync enabled. However, you can only create one job with Real-Time sync enabled for each object. For more information, refer to the Salesforce Real-Time Sync Job article.

Gainsight Widget in Salesforce

Team View empowers your cross-functional team with rich customer data and collaboration capabilities within their primary system. Team View takes the tactical knowledge gathered by customer facing teams, and makes it visible for everyone else, including sales and executive teams. The Team View widget is mainly designed for users who have at the very least a Viewer license. Team View provides customer information from Gainsight without ever leaving the account, case, or opportunity page in Salesforce. You can use this information to gain immediate insights into customer health, discover renewal opportunities, prepare for customer meetings, and more.

Admins can embed a Gainsight NXT widget in Salesforce Sales or Service Cloud to start improving the customer experience through better cross-functional alignment.

For more information about Gainsight Widget, refer to the Team View Overview article

  • Was this article helpful?