Salesforce Connector
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.
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:
- Navigate to Administration > Connectors 2.0 > Connections page.
- Click Create Connection. The Create Connection dialog appears.
- Select Salesforce in the Connector dropdown list.
- Enter Name of the Connection.
- 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.
- (Optional) Switch the toggle ON if your Salesforce org has a custom domain.
- (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.
- Click Authorize to validate the connection. Salesforce OAuth window appears.
- Complete authorization by entering the required Salesforce org credentials.
- Click Allow in the Salesforce confirmation dialog.
Note: If you have already stored your Salesforce credentials in your browser, you are directly prompted to select the stored username.
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.
- 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/Unlink 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. Once a link is established, you can also unlink your Gainsight org with Salesforc org.
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.
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.
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 |
| 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.
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 |
|
|
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 |
|
|
Select Target Field |
Assignee ID |
|
Source Object |
User |
|
MATCH BY SOURCE |
|
|
MATCH BY TARGET |
|
|
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 |
|
|
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) |
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:
- User Sync
- Company Sync
- 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.
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.
Additional Resources
For more information about Connectors, refer to the following articles: