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 - Articles Impacted due to 6.34 October NXT Release
Due to the v6.34 October, 2022 release, this article has been impacted. Steps, images, and playable GIFs in this article will soon be updated to reflect the latest changes.
For more information about the latest UI changes, 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 how to create a HubSpot connection and a connector job, configure job or job chains, and Out of the Box (OOB) jobs in Gainsight.
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.
After you create a HubSpot connection in the Connectors 2.0 page, Gainsight allows to pull data from the following HubSpot objects into the Gainsight standard and custom objects through connector Jobs:
Gainsight provides a few OOB jobs to pull data from HubSpot from Company, Contact, and Owner objects. You can pull data from Deal, Ticket and Product objects through a custom job. For more information, refer to the Out of the Box Jobs section in this article.
- Admins can only create one Hubspot connection in Gainsight, which pulls data from HubSpot to Gainsight. Bidirectional sync is not supported for the HubSpot connector.
- Gainsight does not support pulling data from HubSpot custom objects.
- You can import data from HubSpot to Gainsight on an hourly basis at the very least.
The following table lists the equivalent Gainsight Objects to which data can be pulled from HubSpot.
|HubSpot Object||Gainsight Object|
|Contact||Person and Company Person|
To configure the HubSpot connection, you must execute the following three tasks:
- Create and Authorize Connection: To pull data from your HubSpot instance, 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: You can 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 Connector jobs: You can create custom jobs to pull data from the Deal, Ticket, and Product objects into Gainsight. For more information, refer to the Create a Custom Job section in this article.
A connection is a link between a Gainsight instance and a specific HubSpot instance. HubSpot Connection allows you to create a connection to the specific HubSpot instance. After a connection to the HubSpot instance is established, authorize the connection and pull 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 connector jobs in this connection.
To create a connection with HubSpot:
- Navigate to Administration > Connectors 2.0 > Connections.
- Click Create Connection. Create Connection dialog is displayed.
- From the Connector dropdown list, select HubSpot.
- In the Name of the Connection field, enter a Name for the connection.
- Click Authorize to validate the connection. The HubSpot Authorization window is displayed.
- Enter the HubSpot credentials and click Log in.
Note: You can authenticate your HubSpot instance with login credentials (username and password), Google, or SSO (Single Sign On).
- 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 instance. If your data resides in multiple HubSpot instances, you must first delete an existing connection (after you pull 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 instance.
- 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 pull 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: Pulls HubSpot Companies with Gainsight Companies.
- Company Person Sync: Pulls HubSpot Contacts with Gainsight Person and Company Person objects.
- User Sync: Pulls 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 the 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|
Note: In User Sync jobs, only the fields from User Object can be selected as Identifiers. Fields from Avatar objects cannot be selected as Identifiers.
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 pull 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 pulled, 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 pull 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
In the Jobs page, Admins can create connector jobs to pull data from the specific HubSpot source objects (Company, Contact, Owner, Deal, Ticket, and Product) to Gainsight.
Limitation: Gainsight does not support Merge and Transform to create an output dataset for HubSpot connector.
For more information on how to create a connector job, refer to the Job List Page article in the Additional Resources at the end of this article.
You can create multiple connector jobs as required. If the connector jobs in a connection are dependent on each other, create a Job chain in the required sequence and configure the schedule for the Job Chain. For more information, refer to the Job Chain Page article in the Additional Resources at the end of this article.
When the final output dataset is ready, add a destination to the output dataset. This enables data pull from the source to the target Gainsight object. For more information on how to add destination, refer to the Jobs List Page article in the Additional Resources at the end of this article.
You must 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 how to add destination, refer to the Jobs List Page article in the Additional Resources at the end of this article.
You can use derived mappings to populate values into a field through lookup into another field of the same or another object.
Note: To use Derived Mappings, your Target Object must have at least one field of data type GSID.
In this stage, you can create lookup mapping in a data sync job. You can create a lookup to the same object, or another standard object, and match up to six columns. Once the required matching is performed, Gainsight IDs (GSIDs) are fetched from the lookup object into the GSID data type fields. For more information on the derived mappings, refer to the Jobs List Page article in the Additional Resources at the end of this article.
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.
Gainsight offers an OOB Job Chain to sync initial data required for analysis, after you create a HubSpot connection. This job chain has the OOB jobs in the following sequence:
- Company Sync
- Company Person Sync
- User Sync
You can create a custom Job Chain on the OOB or custom jobs and schedule as required. For more information on the Job Chain, refer to the Job Chain Page in the Additional Resources section at the end of this article.
Configure Job or Job Chain
You can configure the schedule of a connector job or Job chain as required. For more information, refer to the Configure Job or Job Chain Schedule article 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: You can schedule a HubSpot job with a minimum of an hourly sync capability.
You can view the Execution and Update activities of all the connector jobs in the Activity page. You can 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.