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 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 HubSpot, create a data job, configure Job or Job chains in Gainsight. Most importantly, you can learn about Out of the Box (OOB) Jobs and Job Chain provided by Gainsight in the HubSpot Integration.
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.
HubSpot is an inbound marketing software platform that helps companies attract visitors, convert leads, and close customers. HubSpot offers a full stack of software for marketing, sales, and customer service, with a completely free CRM at its core.
Gainsight allows you to sync data from the following HubSpot objects into the Gainsight standard and custom objects:
Sync data from the HubSpot objects, Company, Contact, and Owner to Gainsight objects, Company, Company Person, and User respectively through Gainsight’s OOB Job configurations. If you want to sync data from any other HubSpot object to a Gainsight object, you must configure a new custom job configuration.
For more information about Gainsight objects, refer to the Gainsight Data Management in the Additional Resource section at the end of this article.
The following table lists the equivalent Gainsight Objects to which data can be synced from HubSpot.
|HubSpot Object||Gainsight Object|
|Contact||Person and Company Person|
|Any HubSpot Object||Custom Object|
To configure the HubSpot connection, you must execute the following three tasks:
- Create and Authorize Connection: To sync data from your HubSpot org, create a connection and authorize the connection to establishes a link between Gainsight and HubSpot. For more information, refer to the Create Connection section in this article.
- (Optional) Modify OOB jobs: Edit the out of the box Job’s configurations as per your requirement. For more information, refer to the Out of the Box Jobs section.
- Create Data sync jobs: Create new data sync jobs per your requirement. For more information, refer to the Create a Custom Job section in this article.
A connection is a link between a Gainsight org and a specific HubSpot org. HubSpot Connection allows you to create a connection to the specific HubSpot org. After a connection to the HubSpot org is established, authorize the connection and sync data from HubSpot to Gainsight through either OOB jobs or custom jobs
Create and Authorize Connection
This section explains how to create a connection to HubSpot from Gainsight. You need HubSpot login credentials to establish a connection between HubSpot and Gainsight.
Note: Gainsight allows you to create only one connection, but you can create multiple data jobs in this connection.
To create a connection with HubSpot:
- Navigate to Administration > Connectors 2.0 > Connections.
- Click Create Connection. Create Connection dialog appears.
- In the Connector dropdown list, select HubSpot.
- In the Name of the Connection, enter a Name for the connection.
- Click Authorize to validate the connection. The HubSpot Authorization window appears.
- Enter the following details:
- In the Email address field, enter your HubSpot Email address.
- In the Password field, enter your HubSpot account password.
- Click Log in.
Note: You can authenticate your HubSpot Account with either Google or SSO (Single Sign On), as required.
- Select the required HubSpot Account for integration. (If you have multiple accounts in HubSpot).
Note: If you have already stored your HubSpot credentials in your browser, you are directly prompted to select the HubSpot Account that you want to authorize to.
IMPORTANT: You can create only a single connection in HubSpot Connector. A connection can be associated with a HubSpot org. If your data resides in multiple HubSpot orgs, you must first delete an existing connection (after you sync the data) and then create a new connection.
Context Menu Options
In the Connections tab, click the content menu to see the following options:
- Edit Connection: Modify the HubSpot connection details.
- Re-Authorize Connection: Re-validate the HubSpot connection by a new set of credentials, if you have changed the password of your HubSpot org.
- Revoke Connection: Revoke existing Gainsight connection to your HubSpot instance to remove permission to access your HubSpot instance.
Note: If you revoke a Gainsight connection to a HubSpot instance, then the existing HubSpot jobs will not work.
- Delete Connection: Deletes the HubSpot connection permanently.
Out of the Box Jobs
After the HubSpot connection and authorization successfully completed, Gainsight provides OOB jobs in the Jobs page to sync important data such as Companies, Users and Contacts, which are required for the assessment of data in Gainsight. Following are the three OOB jobs and their mapping details:
- Company Sync: Syncs HubSpot Companies with Gainsight Companies.
- Company Person Sync: Syncs HubSpot Contacts with Gainsight Person and Company Person objects.
- User Sync: Syncs HubSpot Users with Gainsight.
Note: Gainsight allows you to edit OOB jobs as per your requirement.
This job imports data from the HubSpot Company object and inserts it into the Gainsight Company object. This job is named Company Sync_ Connection name. (here Company Sync_HubSpot Connection). In the Company Sync OOB job, the following configuration are provided out of the box:
- The HubSpot Company 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 HubSpot 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:
|HubSpot Company Fields||Target Fields in Gainsight (Company)|
HubSpot Account ID_6574308 (Standard field)Note: Include in identifiers check box is enabled.
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 is named Company Person Sync_Connection name. (here Company Person Sync_HubSpot Connection), by default has a dependency on the Company Sync job. It imports data from the HubSpot Contact object and inserts it into the Gainsight Person and Company Person objects. In the Company Person Sync OOB job, the following configurations are provided out of the box:
- The HubSpot 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 HubSpot 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:
|HubSpot Contact Fields||Target Fields in Gainsight (Person)|
Person :: EmailNote: Include in identifiers check box is enabled.
|First Name||Person :: First Name|
|Last Name||Person :: Last Name|
|vid||Hubspot Contact ID|
|Associated Company ID||Hubspot Account ID|
Upsert keys for the mapping between the HubSpot 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.
There can be one or multiple upsert keys used for the identification of people in Gainsight and you cannot edit them. 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.
The following table shows configurations for OOB derived mappings for the Company ID (GSID) field:
|Target Field: Company ID (GSID)|
|Select Source||Associated Company ID|
|Select Target Field||Company ID|
|MATCH BY SOURCE||Associated Company ID|
|MATCH BY TARGET||Hubspot Account ID|
|When Multiple Matches Occur||Mark record with an error|
|When No Matches Are Found||Reject Record|
This job syncs data from the HubSpot Owner object and inserts it into the Gainsight User object. This job is named as User Sync_ Connection name. (here User Sync_HubSpot Connection). In the User Sync OOB job, the following configuration are provided out of the box:
- HubSpot Owner object is selected as the source object in the dataset preparation and the following source fields are selected.
- Gainsight User is selected as target object and the HubSpot 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:
UsernameNote: Include in Identifiers check box is selected
|ownerId||Avatar_HubspotConnection > Hubspot User Id|
Upsert key is used to resolve incoming HubSpot owners with the existing Gainsight users. Based on the Upsert key selection, either new Gainsight users are created from the incoming HubSpot owners, or associated with the existing users.
This configuration is useful if new users that you are trying to sync through the HubSpot connector may have already been added to Gainsight either through Slack or User Management. If a matching record already exists in Gainsight, the incoming HubSpot user will automatically be associated with that user.
If there are multiple matching records found for the Upsert Key criteria, then navigate to User Management > Avatars > HubSpot 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:
If a user is already added through Slack to Gainsight, you can sync HubSpot Users through HubSpot Connector with Email as an Upsert key.
If a user is already added through the User Management page (Manual or CSV), you can sync HubSpot Users through HubSpot Connector with Name or Email as Upsert key.
Create a Custom Job
From the Jobs page, create jobs to sync data from the specific HubSpot source objects (mentioned above) 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 a 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.
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 Preparation of Connector Jobs in the Additional Resources section at the end of this article.
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 Preparation of Connector Jobs in the Additional Resources section at the end of this article.
In the Direct Mapping, map the fields from the output dataset to the target Gainsight object in the field mappings. Data sync happens from the fields of the source system to the target fields of Gainsight, based on the configured 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.
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. Create a lookup to the same object or another standard object and match up to six columns. Once the required matching is performed, it fetches Gainsight IDs (GSIDs) from the lookup object into GSID data type fields. For more information on the derived mappings, refer to the , refer to the Preparation of Connector Jobs in the Additional Resources section at the end of this article.
IMPORTANT: To use Derived Mappings, Target Object must have at least one field of data type GSID.
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.
Configure Job Chain
Gainsight offers an OOB Job Chain HUBSPOT_Company Person Sync for the OOB jobs. This job chain has the OOB jobs in the following sequence:
- Company Sync
- Company Person Sync
This Job Chain is provided as the Company Person Sync job has dependency on the Company Sync job. You can configure the schedule of this Job chain as required.
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.
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 in the Additional Resources section at the end of this article.
For more information on Connectors, refer to the following articles:
- Data Platform and Connectors
- Connectors List Page
- Jobs List Page
- Preparation of Connector Jobs
- Job Chain Page
- Configuration of Job or Job Chain Schedule
- Activity Page
- Gainsight Data Management
- Configuration of Connectors
- People Management