Skip to main content
Gainsight Inc.

Configure Adoption Explorer Objects

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 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. For more information on how to create a new project, refer to the Projects and Project Settings article.

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.

Object.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. These objects can be used to analyze the data in the Layouts section, and these objects are also available in the other functionalities of Gainsight. Ex: Rules Engine and Reporting.

Currently, you can ingest usage data into the Usage Info and Time Series objects using the following channels:

  1. Amazon S3
  2. Gainsight
  3. Google Analytics (GA)
  4. Salesforce (SFDC)
  5. Snowflake
  6. Postgres 
  7. MySQL
  8. Redshift

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 to the Gainsight S3 Connector article.   

To setup a Source Connection:

Source Name

To create Source Name:

  1. Navigate to Administration > Adoption Explorer.
  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, the 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 Type

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

  1. Amazon S3
  2. Gainsight
  3. Google Analytics (GA)
  4. Salesforce
  5. Snowflake
  6. Postgres, MySQL and Redshift
Amazon S3

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

  1. In the Gainsight Managed S3 Bucket, select the required connection from the Gainsight Connections dropdown list.
  2. File Path: Enter the File Path from where the Adoption Explorer object will collect the data on a daily or weekly schedule.
  3. Use Pattern: Enable the Use Pattern checkbox to use Date Patterns in the file path.
  4. 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.
  5. Date Patterns: Select the required Date Pattern from the Date Patterns dropdown list.
  6. Custom Date Pattern: Enter the Custom Date Pattern.
  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. 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.
  10. Field Separator: helps you in selecting either CSV or TSV files.
  11. 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.
  12. 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 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 setup a new connection. Sign in with Google page appears.
  2. Once you allow the access to Authorize the New Project. 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

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

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.

Snowflake

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

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

  1. From the Connections dropdown list, select Add New Connection to setup a new connection. 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.
  2. 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 
  3. Click Test Connection to check 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.
  4. Click Save.
  5. 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 Postgres, MySQL, 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 and Redshift follow the below instructions:

  1. From the Connections dropdown list, select Add New Connection to setup a new connection. Add Connection page appears. (or) select the required connection from the list of connections that are already setup.
  2. 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
  3. Click Test Connection to check 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.
  4. Click Save.
  5. 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 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. GA doesn’t support the Weekly ingestion schedule. You can ingest usage data only on a Daily basis.
  4. Usage data from Salesforce will be ingested into Adoption Explorer objects, in 24 hours.
  5. Usage data from Postgres will be ingested into the Adoption Explorer objects in 24 hours.
  6. Usage data from Redshift will be ingested into the Adoption Explorer objects in 24 hours.
  7. Usage data from MySQL will be ingested into the Adoption Explorer objects in 24 hours.
  8. 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 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

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.

Map CUI object.png

Identifier Mapping in Company Time Series (Daily/Weekly) 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 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 Entitlement (Daily/Weekly) 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 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.

Map CE object.png

Identifier Mapping in Person Usage Info 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 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.

Identifier Mapping in Person Time Series (Daily/Weekly) 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 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.

Identifier Mapping in Person Entitlement (Daily/Weekly) 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 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.

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.

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.
  4. 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.
  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 is comprised of a set of characters that can also contain spaces and numbers. Ex: Company Name, ID, Page Title, Event Category, etc.
  6. Select the DataType of the fields.
  7. For Field Options, refer the section Field Options.
  8. Click Add to save the configuration.

Note: Once the fields are added to the group, you can create custom measures and dimensions from the Fields Screen, using the ingested measures and dimensions. For more information on how to create custom measures 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 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:
    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. 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:
    • 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 section on the newly created derived field, from the Layouts screen.
    • Enter the Leaderboard Name of your choice.  
    • Enter the required number of days in the Rank Upto Last N Days field.
    • Select the order, either ASC or DESC from the Order By Direction dropdown list.
    • 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 section 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 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.
  2. 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.
  3. 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. For more information 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 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.

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 Time Series (Daily/Weekly)
  • Person Usage Info
  • 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 simple way so that you can track the trend of this data week over week easily. The fields that are tracked for weekly snapshots 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 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 Time Series 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 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 now allowed to create Derived Fields using the ingested measures and dimensions, if required. For more information on how to create Derived Fields, refer to the Configure Derived Fields article. For more information on how to create Layouts, refer to the Configure Layouts article.

Additional Resources:

  • Was this article helpful?