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.

 

Introduction

This article is the third item in a series of Adoption Explorer configuration articles. Gainsight recommends you to refer 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 Projects and Project Settings.

Once you create a project and configure the project settings, you will be automatically navigated to the OBJECTS screen. On the Objects screen, you will see the list of objects as shown in the below image. You can always go-back to the Project listing screen by clicking the Project Name dropdown list, if required.

Project Name Dropdown (1)_c.png

Configure Adoption Explorer Objects

In this section, admins configure:

  1. External Source Connection
  2. Identifier Mapping
  3. Groups/Datasets

Setup Source Connection

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

Currently, you can ingest usage data in to the Adoption Explorer objects using the following channels:

  1. Amazon S3
  2. Gainsight
  3. Google Analytics (GA)
  4. Salesforce (SFDC)
Prerequisite
  1. If you are using Custom S3 Bucket as a data source, make sure that the custom bucket credentials are readily available, before you start the configuration.
  2. To use Gainsight Managed S3 Bucket as a data source, configure Gainsight Managed S3 bucket from Connectors 2.0 page. For detailed instructions on how to setup Gainsight Managed S3 Bucket, refer Gainsight S3 Connector.    
  3. 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 Authorize Connection.

To setup a Source Connection:

Source Name

  1. Navigate to Adoption Explorer > Administration.
  2. Hover to the required project name and click the Objects icon, you will be landed on the Objects page.
  3. Hover to the required object for which you want to establish a source connection. In this example, Company Usage Info object is used.
    Important : You have the ability to select any of the listed objects, to configure a source connection, depending on your business needs. But, it is always recommended to configure Company Usage Info first, because you can use the External ID field automatically from the Company Usage Info object, while configuring source connections for the remaining objects.
  4. Hover to the Company Usage Info object and click + (Add Source) to create a new source connection (or) click Sources to edit the existing source connections.
  5. Enter the Source Name of your choice.

Source Name.gif

Source Type

Select the required Source Type from the dropdown list of following sources:

  1. Amazon S3
  2. Gainsight
  3. Google Analytics (GA)
  4. Salesforce (SFDC)

Source Name (1)_c.gif

Amazon S3

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

  1. Select the Custom or Gainsight Managed S3 Bucket.
  2. Enter the Bucket Name, Access Key and Access Secret, if you have selected the Custom bucket (or) Select the required connection from the Gainsight Connections dropdown list, if you have selected the Gainsight Managed bucket.
  3. File Path: Enter the File Path from where the Adoption Explorer object will collect the data on a daily or weekly schedule.
  4. Use Pattern: Enable the Use Pattern checkbox to use Date Patterns in the file path.
  5. 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 2 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.
  6. Date Patterns: Select the required Date Pattern from the Date Patterns dropdown list.
  7. Date for Sample Data: Enter the sample data date.
  8. Available At: Enter the Available At time and make sure that the CSV file is available in S3 before this time.
  9. Field Separator: helps you in selecting either CSV or TSV files.
  10. Text Qualifier and Escape Char: 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, Bzip2 or plain CSV or TSV files using this option. Select the required Compression Type from the dropdown list.

 Pattern Date.gif

Gainsight

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

  1. MDA Object Type: Select the required 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.
  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.

Gainsight_c.gif

Google Analytics (GA)

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

GA Projects: Select the existing authorized Google project from the dropdown list, in which your source data is available (or) click Authorize New Projects to authorize a new Google project.

1.gif

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 Authorize Connection.

Once you are authorized with a Salesforce source connection, select the Source Type as Salesforce, follow the below instruction:

SFDC Objects: You will see a list of all the Salesforce objects, when you click the SFDC objects dropdown list. Select the required object from the SFDC Objects dropdown list, in which your source data is available.  

Salesforce Source Screen.gif

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 Usage Info object will be ingested daily else source data will be ingested on a weekly basis.

Notes:

  1. Usage data from Amazon S3 will be ingested into Adoption Explorer objects, in 24 hours.
  2. Usage data from Gainsight will be ingested into Adoption Explorer objects, in 24 hours.
  3. 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.
  4. GA doesn’t support the Weekly ingestion schedule. You can ingest usage data only on a Daily basis.
  5. Usage data from Salesforce will be ingested into 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 setup 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 now 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 Usage Info object

  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.

CUI MI.png

Identifier Mapping in Company Timeseries (Daily/Weekly) object

  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 Usage Info, if your Company External ID field is already mapped in the Company Usage Info 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 Usage Info object using Get External ID from Company Usage Info.
  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 required Date field from the dropdown list.

identifier Mapping in Company Timese.gif

Identifier Mapping in Company Entitlement (Daily/Weekly) object

  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 Usage Info, if your Company External ID field is already mapped in the Company Usage Info 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 Usage Info object using Get External ID from Company Usage Info.
  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.

Identifier Mapping Entitlements_Company.png

Identifier Mapping in Person Usage Info object

  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 Usage Info, if your Company External ID field is already mapped in the Company Usage Info 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 Usage Info object using Get External ID from Company Usage Info.
  3. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.
  4. Select the Person Name field from the dropdown list.

Person Usage Info_Idenrifier Mapping.gif

Identifier Mapping in Person Timeseries (Daily/Weekly) object

  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 Usage Info, if your Company External ID field is already mapped in the Company Usage Info 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 Usage Info object using Get External ID from Company Usage Info.
  3. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.
  4. Select the required Date field from the dropdown list.

Person Timeseries_Identifier Mapping.gif

Identifier Mapping in Person Entitlement (Daily/Weekly) object

  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 Usage Info, if your Company External ID field is already mapped in the Company Usage Info 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 Usage Info object using Get External ID from Company Usage Info.
  3. Instance/Location ID: is the identifier in a Company, which identifies the Location/Instance. Select the Instance External ID field from the dropdown list.

Identifier Mapping Entitlements_Person.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.

To create a Group/Dataset:

Configure Fields

To configure fields:

  1. Click + Group to create a new group (or) click Field Configurations to edit the existing group (dataset), you will be 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 Sections in Layouts.
  3. Drag and drop the required fields (Measures and Dimensions) from the selected data source.

+Group.gif

  1. Enter the Target Name of your choice. Target Name is an alias for the Source Name. The Target Name will be used in Layouts and other areas in Adoption Explorer project.
  2. 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 is comprised of a set of characters that can also contain spaces and numbers. Ex: Company Name, ID, Page Title, Event Category, etc.
  3. Select the DataType of the fields.
  4. For Field Options, refer the section Field Options.
  5. Click Preview to view the dataset.
  6. Click Add to save the configuration.

Target, Field and Datatype Name.gif

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

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 noise 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 Field:
    1. Enter the default value for the selected field. While scheduling data ingestion from source to Adoption Explorer objects, by default, this value will be used when the field value is empty/missing.
  4. Default Rollup Function: Select the required default Aggregation Function from the Default Rollup Function dropdown list, to auto-rollup data from Person Daily Timeseries to Person Weekly Timeseries object.
  5. Person to Company Rollup Function: Select the required function from the Person To Company Rollup Function dropdown list, to auto-rollup data from Person Timeseries fields to Company Timeseries (Daily and Weekly) objects.

    Notes
    • You can convert only the source fields in Person Timeseries object to Company Timeseries objects and not the derived fields.
    • By default, the source fields in Person Timeseries object with Dimension data type are converted to Company Timeseries object.

AE_1.gif

  1. Enable Leaderboard:
    1. Select the Enable Leaderboard checkbox to enable the leaderboard. Selecting this checkbox will create a derived field in the Weekly Timeseries object, and this action will allow you to create a leaderboard usage section on the newly created derived field, from the Layouts screen.
    2. Enter the Leaderboard Display 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 Timeseries Objects.
  • Currently, the Layouts screen allows you to create a Leaderboard usage section only on the Person Timeseries Weekly object.

Leaderboard_Source.gif

  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 Layouts screen.
    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.

Associate Entitlement.gif

  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 outside the popup window to save the configuration.

Records with Criteria.gif

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 Dimensions & Metrics Explorer.
  • In a Group, you can add a maximum of 7 Dimensions and 8 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.

GA Limitations.gif

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 Usage Info
  • Company Timeseries (Daily/Weekly)
  • Person Usage Info
  • Person Timeseries (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 Timeseries 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 Usage Info 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 Timeseries objects.
  3. Select the fields you wish to track from the Company/Person Object and/or Company Usage Info/Person Usage Info 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 Timeseries objects.

Snapshot Fields Selection.gif

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.

Snapshot in Usage Section.gif

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

Additional Resources:

  • Was this article helpful?