Skip to main content
Gainsight Inc.

Salesforce to Gainsight Real-Time Sync

Gainsight NXT


This article explains how admins can create a Real-Time data job to ingest data from Salesforce to  Gainsight using the Salesforce connector.


Salesforce is a cloud-based Customer Relationship Management (CRM) solution that helps organizations to effectively streamline their sales and marketing operations.

IMPORTANT: To enable Real-time sync for your Salesforce connector, please raise a support ticket.  In the case of high demand, we will coordinate scheduling it for your Gainsight instance appropriately to ensure that we can closely monitor and gather your feedback. You will hear from our Product team once the feature is enabled.

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. Click here for video demo of this feature.

Business Use Case: The Real-Time sync functionality ensures that when a record is updated in Salesforce, the updates come to  Gainsight in real-time. For example, if the opt out attribute for a Contact is updated in Salesforce, this change will reflect in real-time for the Gainsight Person record and will avoid accidental emails sent due to the delay in the sync.

IMPORTANT: If a Salesforce connector job has both Real-time sync fields and scheduled fields, then only Real-time sync fields will be updated in Real-time as part of this feature. The scheduled fields will be updated as per the defined job schedule.

Note: A create event will create a record in real time with just the fields that are marked for Real-time update. The other fields will be updated as a part of the scheduled sync. 

The Real Time functionality will only be available when destination object is either CompanyCompany Person or Cases.

Real-Time Sync Limitations

The following are the considerations and limitations for Real-time sync from Salesforce and Gainsight:

Salesforce Considerations

  • Salesforce has a limit on the number of events that can be passed to external applications, which is defined by your Salesforce subscription. Once you have reached the event limit, Gainsight will not receive any updates from Salesforce until the limit is reset. However, the pending updates will be synced the next day when the limit is reset.


  • The Salesforce event limit is shared with other applications that listen for Salesforce events.
  • Gainsight advises against activating Real-time sync on fields that will be updated in bulk because you risk exceeding Salesforce's event restrictions.

You will see the following error message, once you have reached the event limit in Salesforce:


  • Formula fields/Calculated fields and Rich Text area fields do not support Real-time sync, as Salesforce does not produce events for these fields.

  • Salesforce APIs are only accessed in the following events:

    • Change of Currency ISO Code
    • Text field updates
    • Payload size exceeds the maximum 1 MB message size
  • To allow the fields to be synced in Gainsight, the user who is authorizing the Salesforce connection must be a System Admin for the Salesforce org or the Salesforce user should have the following permissions:

    • View All for the object
    • View All Users
    • View All Data
    • Customize Application
    • Modify Metadata Through Metadata API Functions
    • Modify All Data
    • View Setup and Configuration
    • View Roles and Role Hierarchy
    • View DeveloperName

In case the user does not have the right Salesforce permissions, then the following error message is displayed:

“Object type “PlatformEventChannel” is not supported” from Salesforce.”

  • Salesforce does not generate events for some actions. For example, when a custom picklist field is defined on Contact in a person account org, the field is present on Account with the __pc suffix. Replacing or renaming a value in the custom picklist doesn't generate account change events but only contact change events for the affected records. But if the custom picklist field is defined on Account, the field isn't present on Contact, and only account change events are generated, as expected. For more details, refer to the Salesforce CDC support document.

Gainsight's Limit

  • Gainsight only listens to Create and Update events in Salesforce for Real-time sync.
  • For Cases Object Real-time jobs, when records are updated in Bulk, LastModifieldDate will come as an additional event, due to which Logs will show the total number of events or records in double count.
  • Real-time activities are saved for the last 3 days only, as there is a limit to show ~200 records in the Activities tab.
  • Real-time jobs can be added to the job chain; However, only the scheduled fields will be synced as a result of job chain execution.

Enable Real-Time Sync in Job

When a Salesforce connection is established, you can edit Company, Cases, Person, and Company Person OOB jobs to enable Real-Time sync for any OOB jobs. You can also create custom real-time jobs to sync data from Salesforce to Gainsight in the Jobs tab. Real Time Enabled labels will be shown for objects for which Real-Time sync is available. The label will be hidden for the object, if there is an existing Real-time job including the object. There can be only 1 job for an object with Real-Time sync enabled.


To enable Real-Time sync for any job:

  1. In the global navigation pane, type Connectors 2.0 in the search field.
  2. Select Connectors 2.0 under the Administration.
  3. Click Jobs tab.
  4. Click Create Job. Create Job window is displayed.
  5. In the Name of the Job field, enter a unique name of the job.
  6. Click Next. Preparation step is displayed

Connectors 3.0 2023-03-02 at 10.29.52 AM.jpg

  1. In the Data Source dropdown menu, select the Salesforce connection. All the supported Salesforce objects are displayed. The objects for which Real-Time sync is available will have the label Real Time Enabled.
  2. Drag and drop any object from the left pane to the Preparation screen.Object details page is displayed.
  3. Select the required fields, whose values need to be synced in Gainsight.
  4. (Optional) In the Display Name field, you can modify the field name.
  5. Select the Sync in Real Time checkbox, if you want updates in Salesforce to sync in real-time to Gainsight.
  6. (Optional) Navigate to the Filters tab and add in filters as per your requirement. For more information about adding filters, refer to the Filters section in the Jobs List page article.
  7. Click Save. Refer to the next Add to Destination section for further instructions.


Filter in Real-Time Sync Job

The Real-Time sync job supports filters that enable filtered data from Salesforce to be synced with Gainsight in real-time.

Currently, this support is extended to Account, Contact, and Cases objects or Real-Time Sync.

To add a Real-Time filter:

  1. Navigate to Real-Time Enabled Job > Object Details Page > Filters.
  2. Click Add Filter.
  3. From the Field, select the field you want to filter on.
  4. From the Operator dropdown, select the operator.
  5. From the Value field, select the appropriate value.
  6. Select the Real-Time Enabled checkbox to apply Real-Time Filters to it.


  • To add more filters, click the + icon.
  • To delete a filter, click the x icon.
  • Based on the type of operator selected, the expression is automatically updated in the Advanced Logic- Real Time Sync field.
  • A maximum of 10 filter conditions can be added to the Salesforce Real-Time job.

Real-Time Enable Filter.jpg

  1. Click Done. The Real-Time filter is applied to the job.

Add to Destination

You can add a destination to the output dataset to sync data from the source to the target Gainsight object.

To add destination:

Click the three dots menu of the object and select Add Destination. Add to Destination page is displayed with the following three tabs:

unnamed (1).png

Real-Time Fields

This tab is only displayed if you select Sync in Real Time for any fields from the source object. You must map the source real-time field with the target field in the Direct Mapping section. If you have selected a field in the source object which has a lookup to another field, then you must map the field in the Derived Mapping section.

Note: The Identifier fields can only be set as a part of the Scheduled fields. However, they are also synced in real-time along with Required fields.

To map real-time fields:

  1. In the Gainsight Object field, select the target object in Gainsight.
  2. In the Direct Mapping section,
    1. In the Target Field, select equivalent target fields to source fields.
    2. (Optional) Click Derived Mapping to expand and map the fields if they have lookup to another field in Gainsight. For more information on how to configure lookup, refer to steps 5 to 15 in the Scheduled Fields section of this article.
  3. Click Listening To Events to expand. In this section, you can choose the change events to capture from Salesforce and the subsequent action to be made in Gainsight.
    For example, if you want to sync updates to Contacts in Salesforce to create or update the corresponding Gainsight Person records. By default, we will list both Create and Update events from Salesforce to create and update records in Gainsight. The defaults can be modified to suit your use case.
  4. Click Advanced Settings to change the default settings.
    1. In the For all records “Created” in Salesforce in Gainsight field, select any of the following:
  • Create: Creates new records in Gainsight and does not update existing records.
  • Create and Update: Creates new records a matching record does not exist in Gainsight, else will update the existing record.
  • Do Nothing: Gainsight will ignore this event.

Note: Create and Update is selected by default in the above field.

  1. In the For all records “Updated” in Salesforce in Gainsight field, select any of the following:
    • Update: Updates the matching record in Gainsight. Will not create a record if a matching record is not found.
    • Create and Update: Creates new records a matching record does not exist in Gainsight, else will update the existing record.
    • Do Nothing: Gainsight will ignore this event.

      Note: Update is selected by default in the above field.
  2. Click Save.


Scheduled Fields

This section consists of both Direct Mapping and Derived Mapping of fields. In the Direct Mappings section, you need to map source fields with the target fields in Gainsight and include Identifiers. In the Derived Mapping section, select the target fields to populate values in them through lookup into other fields of GSID data type. For more information, refer to the Scheduled Fields section in the Jobs list page article.


In the Summary tab, you can view the brief summary of real-time Direct Mapping, Scheduled Direct, and Derived Mappings.

unnamed (2).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

You can configure the schedule of a data job, so that data is pulled into Gainsight from Salesforce.

Notification Frequency

This option is enabled only for Salesforce Connector, which has Real-Time sync capability from Salesforce to Gainsight. To set the frequency of notifications to be received, click either:

  • Real Time Notification: Sends notifications instantly as the job is executed.
  • Batch Notification: Sends collective notifications based on the time frame selected.

unnamed (3).png

For more information, refer to the Configure Job or Job Chain Schedule link in the Additional Resources section at the end of this article.

Real-Time Activities

A Real-time activity is created when a Real-time enabled job within Salesforce Connector is executed. When you select the Real Time Activities in the Activity tab, the following job details is displayed:

  • Date: Displays the start date and time of the Real-time job.
  • Job Name: Displays the name of the Real-time job.
  • Event: Displays the type of event.
  • Destination: Displays the name of the target object in which the data is updated in Gainsight.
  • Data Source: Displays the name of the source object in Salesforce.
  • Status: Displays the status of the Real-time job.
  • Comments: Displays the number of success, failed and ignored records.

unnamed (4).png

Admins can click three-vertical dots menu of each Real-time activity to perform the following operations:

  • View Job Activity: This option helps to view all the fields updated as part of the Real-time job run. Click View Logs in the Job Activity page to view all the fields updated as part of the job run.

Salesforce_Real_Time_Syc 1.jpeg

  • Edit Job: This option helps to update the Real-time job.
  • Download Logs: This option helps to download the log file (Json format).


Real-Time Sync Job Common Errors

The following are some of the common errors in Real-Time sync jobs:

  • Gainsight allows for a maximum of three Real-Time sync jobs, one for each supported source object (Account, Contact and Cases).
  • Delete events are not synced into Gainsight by Real-Time sync, but they are captured under Real Time Sync Activities. For example, if you delete a record from an external system, Gainsight does not delete the same record, but you can view the details of the Deleted event in Activity tab.
  • When the data type for a source field is changed, the change is not reflected in Gainsight but the event is captured under Real Time Sync Activities.
  • If the Authorization for the source Salesfroce connection has expired, the Real-Time sync jobs will be deactivated. To activate them again, you must re-authorize the connection from the Connections tab.
  • Due to a technical limitation, specific fields cannot be used as Identifiers in the Real-Time sync job. If such fields are used as Identifiers in the job, the Real-Time sync will be deactivated until the fields have been unchecked as Identifiers. In the Jobs list page, an information icon is displayed for such real-time sync jobs. For example, Last Activity, Last Viewed Date from Accounts.


  • For Real-Time sync jobs, a maximum of ten Identifiers or Required fields, or a combination of them, can be utilized.


  • Was this article helpful?