Skip to main content
Gainsight Inc.

Configure Adoption Explorer Objects

Gainsight NXT

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.

 

A few of the images/playable GIFs in this article will soon be updated as part of the Horizon design experience.

Overview

This article is the third item in a series of Adoption Explorer configuration articles. Gainsight recommends you to refer to the initial articles of the series and then start with this article.

This article explains how admins can setup the source connections to ingest usage data from external sources into the Adoption Explorer objects. Before you configure source connections, create a project and configure project settings according to your business requirement. To create a new project, refer to the Projects and Project Settings article.

Once you create a project and configure the project settings, you are navigated to the Object Configuration tab on the project details page. The Objects in Project section lists the objects in the project. You can go-back to the Project listing screen by clicking on the lesser than (<) icon. Clicking on the Project Name navigates you to the project settings page.

Object_List.png

Configure Adoption Explorer Objects

Configuring Adoption Explorer objects includes the following steps: 

  1. Setup connection with external source 
  2. Map Identifiers 
  3. Add fields from data source

Setup Source Connection

Usage Data can be ingested into the Adoption Explorer objects from different external sources. Once the data is ingested and the required functions are applied, these objects can be used to analyze the data in the Dashboard Configuration section. Objects created from an Adoption Explorer project are prefixed with the project name and can be seen in the Gainsight Data Management page. Adoption Explorer objects can also be used in other functionalities of Gainsight such as Reporting and Rules Engine.

You can ingest usage data into the Adoption Explorer objects using the following channels:

  • Amazon S3
  • Gainsight
  • Google Analytics (GA)
  • Salesforce (SFDC)
  • Snowflake
  • Postgres 
  • MySQL
  • Redshift
Prerequisite
  • To use Custom S3 Bucket as a data source, make sure that the custom bucket credentials are readily available, before you start the configuration.
  • To use Gainsight Managed S3 Bucket as a data source, configure Gainsight Managed S3 bucket from Connectors 2.0 page. For information on how to set up Gainsight Managed S3 Bucket, refer to the Gainsight S3 Connector article.    
  • If you are using Salesforce as a data source, make sure that you authorize a connection from your Gainsight org to Salesforce org. For information on how to authorize a source connection, refer to the Authorize Connection article.

To setup a source connection, perform the following:

  1. Create Source Name
  2. Select Source Type
  3. Schedule Frequency
  4. Get Fields
  5. Map Identifiers
  6. Add Fields

Source Name

To create Source Name:

  1. Navigate to Adoption Explorer > Administration.
  2. Click on the project name. 
  3. On the Object Configuration tab, click on the required object in the Objects in Project section.

IMPORTANT: Gainsight recommends configuring source connection for the Company Information first as the External ID field from this object can be used while configuring source connections for the remaining objects.

  1. Click Add Source to create a new source connection (or) click edit for an existing source connection.
  2. Enter the Source Name of your choice.

Source Type

Select the required source from the Source Type dropdown list. You can configure the following sources to ingest usage data into the Adoption Explorer project:

Source Type.png

Amazon S3

If you have selected the Source Type as Amazon S3, follow the below instructions:

  1. Select the S3 bucket between Gainsight Managed and Gainsight PX Managed.

Notes:

  • If you select Gainsight Managed, select the required connection from the Gainsight Connections dropdown list.
  • If you select Gainsight PX Managed, select the required rollup from the PX Custom Files dropdown list. Ensure that you have selected the Import usage data from Gainsight PX checkbox in the project settings page to bring additional usage data from Gainsight PX into an existing standard Adoption Explorer project. This action cannot be undone.
  1. File Path: Enter the File Path from where the Adoption Explorer object will collect the data on a daily or weekly schedule.
  2. Use Pattern: Enable the Use Pattern checkbox to use Date Patterns in the file path.
  3. Filter Type: Select the required Filter Type, either EQUALS or STARTS WITH. The date pattern can be specified by the text '${pattern}' anywhere or starts within the file path. 
    Example for EQUALS: If you have organized data in S3 bucket for two dates as “bucket_name/usageinfo_data/2018-10-10/data.csv” and “bucket_name/usageinfo_data/2018-10-11/data.csv”, then you can enter the file path as “bucket_name/usageinfo_data/${pattern}/data.csv”
    Example for STARTS WITH: If you have organized data in S3 bucket as "2019-10-10/bucket_name/usageinfo_data.csv", then you can enter the file path "${pattern}/bucket_name/usageinfo_data.csv" as  Adoption Explorer will automatically replace “${pattern}” with date based on daily or weekly schedule.
  4. Date Patterns: Select the required Date Pattern from the Date Patterns dropdown list.
  5. Custom Date Pattern: Enter the Custom Date Pattern.
  6. Date for Sample Data: Enter the Sample Data date.
  7. Available At: Enter the Available At time and make sure that the CSV file is available in S3 before this time.
  8. Available After: Enter the number of days in the Available After text box, and make sure that the CSV file is available before this time.
  9. Field Separator: This field helps you in selecting either CSV or TSV files.
  10. Text Qualifier and Escape Char: This field helps you to configure CSV or TSV escape and quote characters. Select the Text Qualifier as Double Quote and Escape Char as Single Quote.
  11. Compression Type:  You can configure Gzip, Bzip or plain CSV or TSV files using this option. Select the required Compression Type from the dropdown list. 
Gainsight

If you have selected the Source Type as Gainsight, follow the below instructions:

  1. Object Type: Select the required MDA object type from the dropdown list. If your source data is in Standard Object, select Standard, and if your source data is in Custom object, select Custom.
    Limitation: System Objects in Gainsight are not shown under Gainsight Data Source.
  2. MDA Objects: Select the required Object from the dropdown list. You will see the list of objects based on the selection of the MDA Object Type.
Google Analytics (GA)

If you have selected the Source Type as Google Analytics, follow the below instructions:

  1. From the GA Projects dropdown list, select Authorize New Projects to set up a new connection. The Sign in with Google page appears.
  2. Once you allow access to Authorize the New Project. The Add New page appears. (or) select the existing authorized Google project from the list of projects that are already setup.
  3. In the Add New page, enter the following fields with the required information:

    IMPORTANT: Contact your Database Administrator to obtain the following details: 
    • Project Name
    • Project
    • GA Account
    • Web Property
    • Profile 
  4. Click Save
Salesforce

Prerequisite: If you are using Salesforce as a data source, make sure that you authorize a connection from your Gainsight org to Salesforce org. For detailed instructions on how to authorize a source connection, refer to the Authorize Connection article.

Once you are authorized with a Salesforce source connection:

  1. Select the Source Type as Salesforce.
  2. From the SFDC Objects dropdown list, select the object in which your source data is available.  
Snowflake

The Snowflake source connection allows admins to ingest near real time usage data/telemetry data from Snowflake to the Adoption Explorer Time Series objects.

Prerequisite: Adoption Explorer has the capability to pull data exceeding 5GB using the Snowflake connector, provided you grant the permission of 'create stage' on the schema. 

If you have selected the source type as Snowflake, follow the below instructions:

  1. From the Connections dropdown list, select Add New Connection to set up a new connection. The Add Connection page appears. (or) select the required connection from the list of connections that are already setup.

Note: You can also Edit or Delete the existing connections.

  1. In the Add Connection page, enter the following fields with the required information:

IMPORTANT: Contact your Database Administrator to obtain the following details: 

  • Connection Name
  • Database Name
  • Host
  • User
  • Password
  • Schema
  • Warehouse
  • SSL Enabled 
  1. Click Test Connection to check if the connection details provided would work or not.

Note: If there are any errors in the provided details, the system displays the respective error message based on the error. And, if the provided details are correct, you can see the Save option.

  1. Click Save.
  2. From the Tables dropdown list, select the required table or view.
Postgres, MySQL and Redshift

Admins can ingest near real time usage data/telemetry data from more external sources like PostgresMySQL and Redshift. Once the connection is established, you can bring the usage data from these sources to the Adoption Explorer Time Series objects. 

If you have selected the source type as Postgres, MySQL or Redshift follow the below instructions:

  1. From the Connections dropdown list, select Add New Connection to set up a new connection. The Add Connection page appears. (or) select the required connection from the list of connections that are already setup.

Note: You can also Edit or Delete the existing connections.

  1. In the Add Connection page, enter the following fields with the required information:

IMPORTANT: Contact your Database Administrator to obtain the following details: 

  • Connection Name
  • Database Name
  • Host
  • Port
  • User
  • Password
  • SSL Enabled
  1. Click Test Connection to check if the connection details provided would work or not.

Note: If there are any errors in the provided details, the system displays the respective error message based on the error. And, if the provided details are correct, you can see the Save option.

  1. Click Save.
  2. From the Tables dropdown list, select the required table or view.

Schedule Frequency

Select the required frequency: either Daily or Weekly from the dropdown list. If you have selected the schedule frequency as daily, the source data for this Information object will be ingested daily else source data will be ingested on a weekly basis.

Notes:

  • Usage data from Amazon S3 will be ingested into Adoption Explorer objects, in 24 hours.
  • Usage data from Gainsight will be ingested into Adoption Explorer objects, in 24 hours.
  • Usage data from GA is available after 48 hours, so in Adoption Explorer if any GA source is configured, data will be ingested into the Adoption Explorer objects in 72 hours.
  • GA doesn’t support the Weekly ingestion schedule. You can ingest usage data only on a Daily basis.
  • Usage data from Salesforce will be ingested into Adoption Explorer objects, in 24 hours.
  • Usage data from Postgres will be ingested into the Adoption Explorer objects in 24 hours.
  • Usage data from Redshift will be ingested into the Adoption Explorer objects in 24 hours.
  • Usage data from MySQL will be ingested into the Adoption Explorer objects in 24 hours.
  • Usage data from Snowflake will be ingested into the Adoption Explorer objects in 24 hours.

If an Adoption Explorer object is configured with more than one data source type (multiple sources), schedule will happen at the farthest availability time of the data source. For example, if a Company Time Series (Daily) Object is configured with S3 and GA sources, schedule will happen in 72 hours, as 72 hours is the farthest availability time.

Get Fields

Once you set up the source configuration, click Get Fields to enable the Map Identifiers section.

Map Identifiers

Once the usage data is ingested into the Adoption Explorer objects, admins can map the identifiers in the Adoption Explorer objects with the identifiers in the Source. The identifier mapping varies based on the Object type.

Note: If you have selected the Instance Level Data checkbox on the Project Settings page, then the Instance ID and Instance Name are mandatory.

Identifier Mapping in Company Information object

To map identifiers:

  1. External ID: Unique identifier which identifies a Company. Select the Company External ID field from the dropdown list.
  2. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.
  3. Select the Company Name field from the dropdown list.
  4. Select the Instance Name field from the dropdown list.

MapIdentifiers_Company Information.png

Identifier Mapping in Company Time Series object

To map identifiers:

  1. External ID: is a unique identifier which identifies a Company. Select the Company External ID field from the dropdown list (or) you can also select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.

Note: If the external source has only Instance level data, then you can map your Instance level data to Company level data by getting External Id from Company Information object using Get External ID from Company Information.

  1. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.
  2. Select the required Date field from the dropdown list.

MapIdentifiers_Company TimeSeries.png

Identifier Mapping in Company Entitlement object

To map identifiers:

  1. External ID: is a unique identifier which identifies a Company. Select the Company External ID field from the dropdown list (or) you can also select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.

Note: If the external source has only Instance level data, then you can map your Instance level data to Company level data by getting External Id from Company Information object using Get External ID from Company Information.

  1. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.

MapIdentifier_Company Entitlement.png

Identifier Mapping in Person Information object

To map identifiers:

  1. Person ID:  Select the Person External ID field from the dropdown list.
  2. External ID: is a unique identifier which identifies a Company. Select the Company External ID field from the dropdown list (or) you can also select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.

Note: If the external source has only Person and Instance level data, then you can map your Person and Instance level data to Company level data by getting External Id from Company Information object using Get External ID from Company Information.

  1. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.
  2. Select the Person Name field from the dropdown list.

MapIdentifier_Person.PNG

Identifier Mapping in Person Time Series object

To map identifiers:

  1. Person ID:  Select the Person External ID field from the dropdown list
  2. External ID: is a unique identifier which identifies a Company. Select the Company External ID field from the dropdown list (or) you can also select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.

Note: If the external source has only Person and Instance level data, then you can map your Person and Instance level data to Company level data by getting External Id from Company Information object using Get External ID from Company Information.

  1. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.
  2. Select the required Date field from the dropdown list.

MapIdentifiers_Person TimeSeries.png

Identifier Mapping in Person Entitlement object

To map identifiers:

  1. Person ID:  Select the Person External ID field from the dropdown list
  2. External ID: is a unique identifier which identifies a Company. Select the Company External ID field from the dropdown list (or) you can also select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.

Note: If the external source has only Person and Instance level data, then you can map your Person and Instance level data to Company level data by getting External Id from Company Information object using Get External ID from Company Information.

  1. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.

Map PE.png

Add Fields

Once you map the identifiers in the Adoption Explorer object with the identifiers in the data source, you are now allowed to add the required fields (Measures and Dimensions) from the data source to the Adoption Explorer object. All the data pertaining to the fields added will be ingested into the Adoption Explorer object when the schedule runs.

Configure Fields

To configure fields:

  1. Click + Group to create a new group (or) click Field Configurations to edit the existing group (dataset), you are navigated to the Field Configuration page.
  2. Enter the Group Name of your choice. The Group Name entered here will be used while configuring Usage Reports in the Dashboard Configuration page.
  3. Drag-and-drop the required fields (Measures and Dimensions) from the selected data source.
  4. Enter the Target Name of your choice. Target Name is an alias for the Source Name. The Target Name will be used in Dashboard Configuration and other areas in the Adoption Explorer project.
  5. Select the field Type, either Measure or Dimension.
  • Measure: Data that are counted or measured using a numerically defined method are called Measures. Ex: Total Page Views, Total Unique Events, Total Time on a Page, etc.
  • Dimension: represent text rather than numbers. It consists of a set of characters that can also contain spaces and numbers. Ex: Company Name, ID, Page Title, Event Category, etc.
  1. Select the DataType of the fields.
  2. For Field Options, refer to the Field Options section.
  3. Click Add.

Note: Once the fields are added to the group, you can create custom measure and dimensions from the Fields page, using the ingested measures and dimensions. For more information on how to create custom measure and dimensions, refer to the Configure Derived Fields article.

Field Options

Using Field Options, you can assign a default value to the selected field, enable leaderboard and enable validations/filters. By enabling validations and applying filter conditions, you can filter out the unwanted data while ingesting data from external sources.

To configure Field Options:

  1. Select the required field.
  2. Click the Settings/Gear icon.
  3. Default Value: Enter the default value for the selected field. While scheduling data ingestion from source to Adoption Explorer objects, this value is used when the field value is empty/missing.
  4. Rollup Function: Select the required default Aggregation Function from the Default Rollup Function dropdown list, to auto-rollup data from Person Daily Time Series to Person Weekly Time Series object.
  5. Person to Company Rollup: Select the required function from the Person To Company Rollup dropdown list, to auto-rollup data from Person Time Series fields to Company Time Series (Daily and Weekly) objects.

Notes

  • You can convert only the source fields in Person Time Series object to Company Time Series objects and not the derived fields.
  • By default, the source fields in Person Time Series object with Dimension data type are converted to Company Time Series object.
  1. Enable Leaderboard:
    1. Select the Enable Leaderboard checkbox to enable the leaderboard. Selecting this checkbox will create a derived field in the Weekly Time Series object, and this action will allow you to create a leaderboard usage report on the newly created derived field, from the Dashboard Configuration page.
    2. Enter the Leaderboard Name of your choice.  
    3. Enter the required number of days in the Rank Upto Last N Days field.
    4. Select the order, either ASC or DESC from the Order By Direction dropdown list.
    5. Select the default aggregation type from the Default Aggregation dropdown list.

Notes:

  • Leaderboard can be enabled only on Measures/Derived Measures available on Time Series Objects.
  • Currently, the Layouts screen allows you to create a Leaderboard usage report only on the Person Time Series Weekly object.
  1. Associate Entitlement:
    1. Select the Associate Entitlement checkbox to associate this field to an entitlement. Selecting this checkbox will create a derived field in the same object, and this action will allow you to create a usage section on the newly created derived field, from the Dashboard Configuration page.
    2. Enter the Target Field Name of your choice.
    3. Select the field you want to entitle with, from the Entitled To dropdown list.
    4. Select the default aggregation type from the Default Aggregation dropdown list.

Note: Leaderboard fields will always be calculated on Weekly basis, whereas Entitlement depends on the source field configuration, either Daily/Weekly.

  1. Records with following criteria are valid:
    1. Select the Records with following criteria are valid checkbox to enable validation.
    2. Select the criteria and enter the value(s), as required.
  2. Click Save.

IMPORTANT:

If Google Analytics (GA) is your data source:

  • Adoption Explorer automatically creates one Default Group, and you can only edit the Field Options for the selected fields in the default group.
  • GA allows only certain measures and dimensions group combinations. To learn more on the combination of dimensions and measures, refer to the Dimensions & Metrics Explorer article.
  • In a Group, you can add a maximum of 7 Dimensions and 10 Measures, and if you still want to add additional fields, configure another group.
  • Before saving the Group, Adoption Explorer validates whether the selected group of dimensions and measures are valid or not, using Google APIs.

Here, the above configuration is explained by considering one Adoption Explorer object, and this configuration remains same for all the Adoption Explorer objects listed below:

  • Company Information
  • Company Time Series (Daily/Weekly)
  • Person Information
  • Person Time Series (Daily/Weekly)
  • Company Entitlement
  • Person Entitlement

Weekly Snapshot

After the Source Connections are configured, you can now create a Weekly Snapshot, based on your business requirements. Weekly Snapshot provides an easy way to snapshot information of Company / Person data every week in the most simplistic way so that you can track the trend of this data week over week easily. The fields that are tracked for weekly snapshot are snapshotted on a weekly basis and are stored in the Company/Person Weekly Time Series objects. Using these snapshot fields, you can build usage sections, and then add the layout to the C360 page for the CSMs to derive more insights.

Note: Admins can track the required fields from Gainsight’s Company/Person objects and Adoption Explorer’s Company/Person Information objects.

To create a Weekly Snapshot:

  1. Hover on the required project, and click the Objects icon.
  2. Click Snapshot on the Company/Person Weekly Time Series objects.
  3. Select the fields you wish to track from the Company/Person Object and/or Company Information/Person Information objects.

Notes

  • Company/Person Object here means the Gainsight’s Company/Person Object.
  • Fields that are tracked for weekly snapshotted on a weekly basis and are stored in the Company/Person Weekly Time Series objects.

After selecting the required fields, a week after this configuration, you can see the tracked fields while creating usage sections, provided a scheduled RUN has already happened.

Once the Adoption Explorer Objects are configured, you are allowed to create Derived Fields using the ingested measures and dimensions. For information on how to create Derived Fields, refer to the Configure Derived Fields article. To create usage dashboard, refer to the Configure Layouts article.

Archive Usage Data in Objects

Admins can improve the performance of usage reports by archiving historical usage data. Configure and turn ON the rule to archive data in Adoption Explorer Objects at regular intervals.

Notes:

  • The archive rule runs on a fixed schedule at 03:30 AM (UTC) on every Saturday.
  • Admins cannot modify the schedule for archive rules. 
  • If the status of the Project is set to Inactive for more than seven days, the archive rule is deactivated automatically.
  • Gainsight currently supports storing 30 GB of Adoption Explorer usage data per Gainsight instance.

Additional Resources