Skip to main content
Gainsight Inc.

HubSpot Connector

Gainsight NXT

 

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.

Overview

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:

  • Company
  • Contact
  • Deal
  • Owner
  • Product
  • Ticket
  • Email
  • Notes
  • Meeting
  • Calls
  • Task
  • Line Item
  • Feedback Submission
  • Custom Objects

Gainsight provides a few OOB jobs to pull data from HubSpot from Company, Contact, Owner Engagements Objects Call, Email, Note, and Meetings objects. You can pull data from Deal, Ticket, and Product objects, Engagement Task through a custom job. For more information, refer to the Out of the Box Jobs section in this article.

IMPORTANT:

  • Admins can create multiple HubSpot connection in Gainsight, which pulls data from HubSpot  to Gainsight. The data is transferred back to HubSpot via Load to HubSpot Action in Rule. For more information on how to configure Load to HubSpot, refer Load to HubSpot article.
  • 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
Company Company
Owner Users
Contact Person and Company Person
Deal Custom Object
Product Custom Object
Ticket Custom Object
Calls Gainsight Timeline
Notes Gainsight Timeline
Email Gainsight Timeline
Meeting Gainsight Timeline
Task Custom Object
Line Item GS Opportunity Line Item
Feedback Submission Surveys

To configure the HubSpot connection, you must execute the following three tasks:

  1. 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.
  2. (Optional) Configure HubSpot Scope: Personalize the HubSpot access with custom permissions. By default, all required permissions for Gainsight integration are enabled.
  3. (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.
  4. Create Connector jobs: You can create custom jobs to pull data from the Deal, Ticket, and Product objects into Gainsight.  In HubSpot Custom Jobs can be created from all supported objects. For more information, refer to the Create a Custom Job section in this article.

Create Connection

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.

To create a connection with HubSpot:

  1. Navigate to Administration > Connectors 2.0 > Connections.
  2. Click Create Connection. Create Connection dialog is displayed.
  3. From the Connector dropdown list, select HubSpot.
  4. In the Name of the Connection field, enter a Name for the connection.

    HubSpot Connection.jpeg
  5. (Optional) Click Configure HubSpot Scope. The Configure HubSpot Scope dialog appears.
  6. (Optional) Select the additional scopes such as Custom Objects or Feedback Surveys. By default, all required permissions for Gainsight integration are selected.
    Note: For more information on HubSpot scopes, refer to the HubSpot Integration Guides.
  7. (Optional) Click Done and Back to Configuration.
    Config HubSpot Scope.jpeg
  8. Click Authorize to validate the connection. The HubSpot Authorization window is displayed.
    Authorize.jpg
  9. 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).
  10. 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.

OAuth Bridge.jpeg

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.

image.png

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.
  • Calls Timeline Sync : Fetch HubSpot Engagements (Calls) to Gainsight Timeline.
  • Notes Timeline Sync : Fetch Notes Type HubSpot Engagement to Gainsight Timeline.
  • Meeting Timeline Sync : Fetch Meeting Type HubSpot Engagement to Gainsight Timeline.
  • Email Timeline Sync : Fetch Email type from HubSpot Engagement to Gainsight Timeline.

Note:

  • Gainsight allows you to edit OOB jobs as per your requirement.
  • HubSpot Timeline sync will create activity with the first company and associate to remaining companies from HubSpot. The maximun companies that can be associated are 10.

Company Sync

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.

Direct Mappings

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

HubSpot Company Fields Target Fields in Gainsight (Company)
companyId

HubSpot Account  ID_6574308 (Standard field)

Note: Include in identifiers check box is enabled.
Name Name

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.

Direct Mappings

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

HubSpot Contact Fields Target Fields in Gainsight (Person)
Email

Person :: Email

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

Derived Mappings

The following table shows configurations for OOB derived mappings for the Company ID (GSID) field:

Fields Values
Target Field: Company ID (GSID)
Select Source Associated Company ID
Select Target Field Company ID
Source Object Company
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

User Sync

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.

Direct Mappings

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

Fields  Values
firstName First Name
lastName Last Name
email

Username

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

IMPORTANT: Gainsight is gradually rolling out this feature. Please contact the Gainsight support team to have it enabled for your tenant.

Timeline Sync

The HubSpot integration provides the ability to ingest HubSpot Engagements data into Gainsight. Connectors have the following standard jobs to ingest Engagements data into Timeline:

  • Notes Timeline Sync
  • Calls Timeline Sync
  • Meeting Timeline Sync
  • Email Timeline Sync

Ishan Nagar - Gainsight - Slack 2023-10-26 at 2.55.35 PM.jpg

Configuration Details for Standard Jobs

This section provides information on the details of Timeline Sync Standard jobs. The following image displays the configuration of one of the Timeline Sync Standard Job (Call Timeline Sync):

Ishan Nagar - Gainsight - Slack 2023-10-26 at 2.56.26 PM.jpg

For Standard jobs, the HubSpot object is selected as the source object in the dataset preparation and the following source fields are automatically selected:

Hubspot doc 2.jpg

You can select additional fields as per the requirement and click Done. The fields are added to the source object. 

Gainsight Timeline is automatically set as the target object and the HubSpot source fields are mapped with the Gainsight target fields using the Sync to Timeline configuration, as visible in the below image:

Hubspot doc 3.jpg

By default, the following information is automatically updated for Call Timeline:

  • Activity type for Standard job based on the Extract object.
  • All mandatory fields in Timeline are mapped to the Source Fields in Standard job.

Newly created and updated activities sync to Gainsight Timeline through Sync to Gainsight Timeline:

  1. From the Target Fields dropdown, select the corresponding Source Fields to it respectively. This automatically updates the derived mapping.
  2. (Optional) Click Add Mapping to add further fields to the derived mapping.
  3. Click Done. The Job is prepared.

Hubspot doc 4.jpg

The following table displays the Direct Mapping for HubSpot CALL Timeline Sync, which is for  EMAIL, MEETING, and NOTES Standard Jobs.

Source Fields (HubSpot Engagement) Target Fields (Gainsight Timeline) Description
Record ID External ID Insert the unique id from HubSpot Engagement to Gainsight Timeline as an identifier; this is not editable.
Activity Date Activity Date Update the Activity date from HubSpot Engagement to Gainsight Timeline.
Call notes Note Insert Notes from HubSpot Engagement to Gainsight Timeline
Call Title Subject Insert Title from HubSpot Engagement to Timeline Subject
Attached file IDs Attachment ids This mapping is used to sync attachments from HubSpot Engagement to Gainsight Timeline. If you don't want to sync attachments, you can remove the mapping.

The following table displays the Derived Mapping for HubSpot CALL Timeline Sync, which is similar for EMAIL, MEETING, and NOTES Standard Jobs.

Source Fields (HubSpot Engagement) Gainsight  Fields (GSID fields from Gainsight Timeline) Define Lookup Details Description
Associated Company Ids Company Id

Intermediate Object : Company

Source : Associated Comp Id

Field in Intermediate Object : HubSpot Account ID
Based on the Match by Criteria, CompanyID is resolved in Gainsight Timeline.
Associated Contact Ids External Attendees

Intermediate Object : Company

Source : Associated Contact Ids

Field in Intermediate Object : HubSpotHubspot Account ID
Based on the Match by Criteria, Attendees is resolved in Gainsight Timeline.
Activity Assigned to GS Author ID

Intermediate Object : Avatar_HubSpot Connection_ 2

Source : ActivityAcitivity assigned to

Field in Intermediate Object : HubSpot User ID
Based on the Match by Criteria, Author ID is resolved in Gainsight Timeline.

Screenshot 2023-04-27 at 1.24.05 PM (1).png

Configuration Details of Custom Jobs

On the Jobs page, you can create connector jobs to fetch data from specific HubSpot source objects to Gainsight.

To create a Custom job:

  1. On the Preparation page, drag and drop the required object.
  2. Click the object and select the Sync to Timeline option.

Note: The Sync to Timeline options is only available for HubSpot Engagement and helps insert data directly into Gainsight Timeline objects.

Ishan Nagar - Gainsight - Slack 2023-10-26 at 2.57.02 PM.jpg

To know more about the Custom jobs, refer to the Create a Custom Job section.

Create a Custom Job

In the Jobs page, Admins can create connector jobs to pull data from the specific HubSpot source objects 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.

Add Destination

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.

Direct Mapping

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.

Derived Mapping

You can use derived mappings to populate values into a field through lookup into another field of the same or another object.

Notes:

  • To use Derived Mappings, your Target Object must have at least one field of data type GSID.
  • The Timeline author field will not be resolved for Engagement Sync Manual jobs.

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.

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.

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.

Job Activities

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.

  • Was this article helpful?