Gainsight

Send your event data from RudderStack to Gainsight CS.

Gainsight CS is Gainsight’s customer success product. It gives you a complete, 360-degree view of your customers and helps you understand their product behavior based on the data around their interactions and usage trends. With Gainsight CS, you can also analyze your company’s activity with every customer and leverage the insights to improve interaction with them.

RudderStack lets you send your event data from a variety of sources to Gainsight CS.

warning
This integration is developed for the Gainsight CS NXT Edition.
info
Find the open source transformer code for this destination in the GitHub repository.

Getting started

To send your events to Gainsight CS via RudderStack, you will first need to add it as a destination in the RudderStack dashboard.

First, check if the source platform is supported by Gainsight CS by referring to the table below:

Connection ModeWebMobileServer
Device mode---
Cloud modeSupportedSupportedSupported
info
To learn more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you’ve confirmed that the source platform supports sending events to RudderStack, follow these steps:

  • From your RudderStack dashboard, add the source and select Gainsight from the list of supported destinations.
  • Assign a name to this destination, and click Next. You should then see the following screen:

Connection screen for Gainsight

You will need to enter the following settings under Connection Settings:

  • Access Key: This key is required for the identify and group calls. To generate the access key in Gainsight, go to Administration - Connectors 2.0 - Connectors tab and click Gainsight API.
info
For more information on generating the Gainsight Access Key, refer to their support page.
  • Domain or Subdomain Name: Subdomain or custom domain is a required field to work with the Gainsight API. required to work with the Gainsight API.
info
More information on setting up a Gainsight custom domain can be found in their support page.
  • Gainsight Event Settings: This setting is related to the Gainsight Events Framework.
success
Refer to the Track section of this documentation for more details.

Identify

RudderStack creates a Person object in Gainsight for the identify call. Gainsight uses the Email field as an identifier and it is mandatory to merge the object. Hence, for an identify call, the email field is mandatory.

For the default fields in Gainsight Person object, the camelCase notation is used in the RudderStack payload traits.

The mapping of the RudderStack traits to the Gainsight Person object fields is as shown:

Gainsight Person FieldRudderStack Trait Name
Emailemail
Namename
FirstNamefirstName
MiddleNamemiddleName
LastNamelastName
LinkedinUrllinkedinUrl
Locationlocation
ExternalRecordID__gcexternalRecordId
EmailOptOutemailOptOut
DynamicResolutionKeydynamicResolutionKey
Commentscomments
Timezonetimezone
MasterRecordIDmasterRecordId
MasterAvatarTypeCodemasterAvatarTypeCode

An example of the identify call in RudderStack is as shown:

rudderanalytics.identify(
  "sample-user-id",
  {
    email: "user@email.com",
    firstName: "John",
    lastName: "Doe",
    comments: "example identify call",
  },
  () => console.log("identify callback")
)
info
Custom fields are supported for identify. Refer to the section below for details.

Custom Fields

You can create custom fields in the Gainsight schema for a Person object as shown in the image below:

gainsightcs-custom-field-person

Then, you can add the RudderStack trait name for the Gainsight custom field mapping in the RudderStack dashboard as shown:

gainsightcs-field-map-person

info
When you add custom fields in the Gainsight schema, __gc is automatically suffixed at the end. Therefore, you need to provide the field name including the __gc suffix in the RudderStack dashboard as shown above.

Group

The group call associates a person with a group. RudderStack’s group call creates a Company object if it is not present or updated with the provided traits. The Name field in is used as the unique identifier.

info
For making a group call, email is a mandatory field in context.traits of the RudderStack event payload.

The mapping of the RudderStack traits to the Gainsight Company object fields is as shown:

Gainsight Company FieldRudderStack Trait Name
Namename
Employeesemployees
Arrarr
BillingAddressbillingAddress
Summarysummary
Csmcsm
CustomerlifetimeInMonthscustomerLifetimeInMonths
Industryindustry
LifecycleInWeekslifecycleInWeeks
ManagedAsmanagedAs
Mrrmrr
OriginalContractDateoriginalContractDate
ParentCompanyparentCompany
RenewalDaterenewalDate
Stagestage
Statusstatus
Tagstags
TickerSymboltickerSymbol
Usersusers
SfdcAccountIdsfdcAccountId
IndustryNewindustryNew

An example group call is as shown below:

rudderanalytics.group(
  "sample-group-id",
  {
    name: "Example Company",
    employees: 1000,
    industry: "Software",
  },
  () => console.log("group callback")
)
info
Custom Fields are supported for the group call. For details, refer to the section below.

Custom Fields

To send custom properties to Gainsight CS via RudderStack, you first need to create custom fields in the Gainsight schema for the Company object, as shown in the following image:

gainsightcs-custom-field-company

Then, you can add the RudderStack trait name for the Gainsight custom field mapping in the RudderStack dashboard:

gainsightcs-field-map-company

info
When you add custom fields in the Gainsight schema, __gc is automatically suffixed at the end. Therefore, you need to provide the field name including the __gc suffix in the RudderStack dashboard as shown above.

Track

The track call is used to work with the Gainsight Events Framework. The Gainsight Events Framework lets you create events which can then be used in the Programs and Rules Engine.

Gainsight events are identified with Event Name and Event Version. The events are grouped under Topics. Note that there can be multiple events under a topic.

To start sending events, you will first need to register as a Publisher in Gainsight by going to Administration - Events and clicking on Register as Publisher. This generates a unique shared secret required for working with Gainsight Events Framework.

info
More information on the Gainsight Events Framework can be found in their support page.

Provide the required event settings in the RudderStack dashboard as shown:

gainsight-event-main-settings

The required settings are:

  • Shared Secret: This is a required field. Go to Administration - Events and click Register as Publisher to get this key.
  • TenantId: The Tenant ID of the Publisher is a required field. You can copy this ID by going to Administration - Application Settings.
  • Contract ID: This field is optional. If a user subscribes to a contract, only those subscribers associated with this contract will get the event.
  • Topic Name: This is a required field. The events are grouped under topic.

The Contract ID an be provided in the RudderStack dashboard or in the track payload as externalId. If both are present, RudderStack gives higher precedence to the externalId .

The following is an example of sending contractId via a track call:

rudderanalytics.track(
  "Ticket Closure",
  {
    name: "John Doe",
    status: "resolved",
  },
  {
    externalId: [
      {
        type: "gainsightEventContractId",
        id: "sample-contract-id",
      },
    ],
  },
  () => console.log("track callback")
)

Using RudderStack’s track call with Gainsight Events

info
Both the event name and version are needed to use track with Gainsight Events.

First, create a new event under a particular topic in Gainsight:

gainsightcs-event-map-sample

Then, provide this event name and the version mapping in the RudderStack dashboard as shown:

gainsightcs-event-map-sample

You are now ready to send events to Gainsight using the track method.

An example of a track call is as shown:

rudderanalytics.track(
  "Ticket Closure",
  {
    name: "John Doe",
    status: "resolved",
  },
  () => console.log("track callback")
)
info
To send Gainsight Events to more than one topic, we recommend creating new Gainsight destinations in the RudderStack dashboard for each topic.

Questions? Contact us by email or on Slack