Skip to main content
Gainsight Inc.

Configure Adoption Explorer Objects

  1. Last updated
  2. Save as PDF 
Gainsight NXT

 

This article explains how admins can set up the source connections to ingest usage data from external sources into the Adoption Explorer objects.

Note: 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.

Overview

Before you configure source connections, create a project and configure project settings according to your business requirement. For information on how to create a new project, refer to the Projects and Project Settings article from Additional Resources.

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 page by clicking the lesser than (<) icon. Click the project name to navigate to the project settings page.

Object_List.png

Configure Adoption Explorer Objects

Configuring Adoption Explorer objects includes the following steps: 

  1. Establish Connection
  2. Select Identifiers
  3. Select Fields
  4. Complete Fields Settings

Establish 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 tab. 

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 a 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 the Connectors 2.0 page. For information on how to set up Gainsight Managed S3 Bucket, refer to the Gainsight S3 Connector article from Additional Resources.    
  • If you are using Salesforce as a data source, ensure 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 from Additional Resources.

To setup a source connection:

  1. Create Source Name
  2. Setup the source connection

Create Source Name

To create the Source Name:

  1. Navigate to Adoption Explorer > Administration.
  2. Click the project name. 
  3. Click the required object from 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. To make changes to an existing source, click the corresponding Edit Source icon. 
  2. In the Add Source field, enter the Source Name of your choice.

Setup Source Connection

After the Source Name is created, the next step is to establish a source from where the usage data can be ingested into the Adoption Explorer project.

Select the required source from the Connection Type field. You can configure one of the following sources:

Note: If an Adoption Explorer object is configured with more than one data source type (multiple sources), the data ingestion will be executed 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.

Amazon S3

To establish the connection with Amazon S3: 

  1. From the Connection Type field, select Amazon S3. 
  2. Choose the applicable S3 Bucket.
    1. If you have selected Gainsight Managed, select the required connection from the Gainsight Connections dropdown list.
    2. If you have selected Gainsight PX Managed, select the required rollup from the PX Custom Files dropdown list.

Note: To ingest additional usage data from Gainsight PX into an existing standard Adoption Explorer project, ensure that you have selected the Import usage data from Gainsight PX checkbox in the Project Settings page. This action cannot be undone.

  1. Enter the File Path from where the Adoption Explorer object will collect the data. 
  2. (Optional) Enable the Use Pattern checkbox to use Date Patterns in the file path.
    1. Select the required Filter Type. 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.

  1. (Optional) If the file is not available, select the Ignore source if file is not present checkbox to ignore the file processing. 
  2. From the Field Separator field, select the applicable data delimiter. 
  3. In the Text Qualifier and Escape Char field, configure the required quote and escape characters respectively. 
  4. From the Compression Type dropdown, select the compression format.
  5. Enter the Available At time and ensure that the file is available in S3 before the entered time.
  6. In the Available After field, enter the number of days after which the field should be picked for ingestion. Ensure the file is available within the entered number of days.
  7. From the Frequency to import data section, select the frequency - either Daily or Weekly -  at which data should be ingested into the project.  

Note: Usage data from Amazon S3 will be ingested into Adoption Explorer objects in 24 hours.

  1. Click Import Metadata to save the details and proceed to the next step.

Gainsight

To establish the connection with Gainsight: 

  1. From the Connection Type field, select Gainsight. 
  2. From the Object Type dropdown, select the appropriate object in which your source data is stored. This enables the MDA Objects field and the underlying options.

Note: System Objects in Gainsight are not shown under Gainsight Data Source.

  1. From the MDA Objects dropdown, select the required object
  2. From the Frequency to import data section, select the frequency - either Daily or Weekly -  at which data should be ingested into the project.  

Note: Usage data from Gainsight will be ingested into Adoption Explorer objects in 24 hours.

  1. Click Import Metadata to save the details and proceed to the next step.

Google Analytics (GA)

Adoption Explorer supports GA4 along with Universal Analytics (UA). If you are tracking analytics for your web or mobile application using GA4, the usage data can be imported to Adoption Explorer objects. Adoption Explorer continues to support properties from the older version of Google Analytics as well. 

IMPORTANT:

  • Adoption Explorer adheres to Google's Data policy. The information Gainsight receives from Google APIs is used and transferred based on the strict guidelines of the Google API Services User Data Policy, which includes Limited Use requirements.  For more information, refer to the Google API Services User Data Policy document.

  • Gainsight understands the importance of controlling your data, so we don't share it with any external third-party applications or tracking tools. However, to provide the best possible user experience by allowing users to do reporting and analysis on their data. This data is used solely to improve the functionality and performance of the application. 

Prerequisite

To ingest usage data from Google Analytics, ensure that the following APIs are enabled in your Google Platform:

API Scope

The OAuth 2.0 scope https://www.googleapis.com/auth/analytics.readonly provides read-only access to the Analytics API12. This scope allows users to view and manage their Google Analytics data without the ability to edit or manage entities. It is commonly used for applications that require access to Google Analytics data for analytical insights and reporting purposes. This scope enables applications to prompt users for authorization to access their Google Analytics data and receive an access token for making authorized API requests on behalf of the signed-in user.

To establish the connection with Google Analytics: 

  1. From the Connection Type field, select Google Analytics. 
  2. From the GA Projects dropdown, you can either select an existing Google Project that was already authorized, or set up a new project by selecting +Authorize new connections. 

AE_GA Config.png

  1. If creating a new connection, you will be redirected to Google’s Sign In page to  enter the credentials and sign in. 
  2. On successful authorization, the Add New popup appears, where you need to enter the following information:
    1. Project Name
    2. Project
    3. GA Account
    4. Web Property

AE_GA_Config_2.png

Note: You might need to get in touch with your Database Administrator for the required information.

  1. Click Import Metadata to save the details and proceed to the next step.

Note:

  • GA doesn’t support the Weekly ingestion schedule. You can ingest usage data only on a Daily basis.
  • Usage data from GA is available after 48 hours. Hence data will be ingested into the Adoption Explorer objects in 72 hours.

AE_GA_Config_3.png

Salesforce

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 from Additional Resources.

Once you are authorized with a Salesforce source connection:

  1. From the Connection Type field, select Salesforce.  
  2. From the SFDC Objects dropdown, select the object in which your source data is available. 
  3. From the Frequency to import data section, select the frequency - either Daily or Weekly -  at which data should be ingested into the project.  

Note: Usage data from Salesforce will be ingested into Adoption Explorer objects in 24 hours.

  1. Click Import Metadata to save the details and proceed to the next step.

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 create stage permission on the schema. 

To establish the connection with Snowflake: 

  1. From the Connection Type field, select Snowflake. 
  2. From the Connection Name dropdown list, select the required connection from the list of connections that are already setup.
  3. From the Connection Name dropdown, select Add New Connection to set up a new connection, or select the required connection from the list of connections that are already setup.

Note: You can also edit or delete existing connections.

  1. In the Add Connection for SNOWFLAKE popup, add the following information: 
    1. Connection Name
    2. Database Name
    3. Host
    4. Schema
    5. Warehouse
    6. User
    7. Password
       
  2. Click Test Connection to check if the connection details provided would work or not.

Note: In case there are any errors in the provided details, the system displays the respective error message based on the error.

  1. Click Save.
  2. From the Tables Name dropdown list, select the required table or view.
  3. From the Frequency to import data section, select the frequency - either Daily or Weekly -  at which data should be ingested into the project.  

Note: Usage data from Snowflake will be ingested into the Adoption Explorer objects in 24 hours.

  1. Click Import Metadata to save the details and proceed to the next step.

Postgres, MySQL, or Redshift

Adoption Explorer allows you to ingest near real time usage data/telemetry data from external sources such as  Postgres, MySQL, or Redshift. Once the connection is established, you can bring the usage data from these sources to the Adoption Explorer Time Series objects. 

To establish the connection with Postgres, MySQL, or Redshift:

  1. From the Connection Type field, select the appropriate database.  
  2. From the Connection Name dropdown, you can either select an existing connection, or set up a new one by selecting +Add new connections.

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

  1. The Add Connection popup appears, where you need to enter the following information:
    1. Connection Name
    2. Database Name
    3. Host
    4. Schema
    5. Port
    6. User
    7. Password
    8. SSL Enabled

Note: You might need to get in touch with your Database Administrator for the required information.

  1. Click Test Connection to verify the connection details provided. Upon successful verification, the Save button appears. Errors, if any, would be highlighted.
  1. From the Tables dropdown list, select the required table or view.
  2. From the Frequency to import data section, select the frequency - either Daily or Weekly -  at which data should be ingested into the project.  

Note: Usage data from Postgres, Redshift, or MySQL will be ingested into the Adoption Explorer objects in 24 hours.

  1. Click Import Metadata to save the details and proceed to the next step.

Select Identifiers

Once the usage data is ingested into the Adoption Explorer objects, you need to map the identifiers in the Adoption Explorer objects to 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, the Instance ID and Instance Name fields are mandatory.

Identifier Mapping in Company Information Object

To map identifiers:

  1. From the External ID field, select the unique identifier (Company External ID) of the Company.
  2. From the Instance/Location ID field, select the identifier (Instance External ID) that represents the Location/Instance. Click the plus icon if you want to associate additional instances.
  3. Select the Company Name and Instance Name field.
  4. Click Next to proceed. 

AE_Mapping_Company Information.png

Identifier Mapping in Company Time Series Object

To map identifiers:

  1. From the External ID field, select the unique identifier of the Company. You can either:
    1. Select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.
    2. Or, choose the Select External ID from list of fields available in source option and select the Company External ID from the dropdown.

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

  1. From the Instance/Location ID field, select the identifier (Instance External ID) that represents  the Location/Instance. Click the plus icon if you want to associate additional instances.
  2. Select the required Date and Date Format fields.
  3. The Enable aggregation from Daily to Weekly objects field allows you to configure roll ups from person weekly to company weekly time series data. Choose Yes or No for the roll up as required.

Note: This option would not be available while configuring a source for Company Weekly Time Series object.

  1. Click Next to proceed. 

AE_Mapping_Company Time Series.png

Identifier Mapping in Company Entitlement Object

To map identifiers: 

  1. From the External ID field, select the unique identifier (Company External ID) of the Company.

  2. Click Next to proceed. 

AE_Mapping_Company Entitlement.png

Identifier Mapping in Person Information Object

To map identifiers:

  1. From the Person ID field, select the Person External ID field from the dropdown.
  2. From the External ID field, select the unique identifier of the Company. You can either:
    1. Select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.
    2. Or, choose the Select External ID from list of fields available in source option and select the Company External ID from the dropdown.

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 the Get External ID from Company Information option.

  1. From the Instance/Location ID field, select the identifier (Instance External ID) that represents  the Location/Instance. Click the plus icon if you want to associate additional instances.
  2. Select the Person Name field from the dropdown.
  3. Click Next to proceed. 

AE_Mapping_Person Information.png

Identifier Mapping in Person Time Series Object

To map identifiers:

  1. From the Person ID field, select the Person External ID field from the dropdown.
  2. From the External ID field, select the unique identifier of the Company. You can either:
    1. Select Get External ID from Company Information, if your Company External ID field is already mapped in the Company Information object.
    2. Or, choose the Select External ID from list of fields available in source option and select the Company External ID from the dropdown.

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 the Get External ID from Company Information option.

  1. In the Instance/Location ID field, select the identifier (Instance External ID) that represents  the Location/Instance. Click the plus icon if you want to associate additional instances.
  2. Select the required Date and Date Format field.
  3. The Enable aggregation from Daily to Weekly objects field allows you to configure roll ups from person weekly to company weekly time series data. Choose Yes or No for the roll up, based on the requirement. 
  4. Click Next to proceed.

AE_Mapping_Person Time .png

Identifier Mapping in Person Entitlement Object

To map identifiers:

  1. From the Person ID field, select the Person External ID field from the dropdown.
  2. From the External ID field, select the unique identifier of the Company.
  3. Click Next to proceed.  

AE_Mapping_Person Entitlement.png

Select Fields

Once you map the identifiers in the Adoption Explorer object with the identifiers in the data source, you can add the required fields (Measures and Dimensions) from the data source to the Adoption Explorer object. 

To add the fields: 

  1. In the Select Fields section, select all the required fields that need to be ingested into the Adoption Explorer.
  2. To view live data for the selected fields, click the Preview icon.  

All data pertaining to the fields selected will be ingested into the Adoption Explorer object when the schedule runs.

Create Field Group

Along with selecting the required fields that need to be ingested, you can also create logical groups for better management. 

Note: You can only create groups if your source connection is Google Analytics.

To create a field group:

  1. Click Create Field Group. 
  2. Enter a name for the group which will be used while configuring Usage Reports in the Dashboard Configuration page.
  3. Select the required fields (Measures and Dimensions) to be added to the group. You can search for the required fields or include all fields using the Field Name checkbox. 

Note: You can add multiple groups based on the requirement. 

Complete Field Settings

In the Complete Field Settings page, you can configure the display name, default value, and other settings related to the fields that are to be ingested. 

For each field, update the following information: 

  1. 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.
  2. Select any of the following field Type:
    • Measure: Data that can be counted or measured using a numerically defined method are called Measures. For instance, Total Page Views, Total Unique Events, Total Time on a Page, and so on.
    • Dimension: Data that represents text rather than numbers. It consists of a set of characters that can also contain spaces and numbers. For instance, Company Name, ID, Page Title, Event Category, and so on.
  3. From the DataType field, select the applicable data type.
  4. In the Use for Group By column, indicate whether the field should be included or excluded from group by for aggregation. This option is only available for fields with Type as Dimension.
  5. The Settings icon under Field Options helps you configure validations and other information for the fields. For more information, refer to the Field Options section.
  6. Click Save to register all the configurations.

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 from Additional Resources.

Field Options

Field Options helps you to 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 unwanted data while ingesting data from external sources.

To configure Field Options:

  1. Click the Settings icon of the required field.
  2. In the popup that appears, enter the following information, as applicable:

Field

Description

Notes

Aggregation Functions

Default Aggregation function required for extraction of records from the source

  

Decimal Places

Decimal places to which each record value is rounded off.

Applicable only for fields with Data Type as Number.

Default Value

The default value for the selected field. While ingesting data, this value will be used if the field value is empty/missing.

  

Rollup Functions

Default Aggregation function to auto-rollup data from Person Daily Time Series to Person Weekly Time Series object.

Applicable only for fields with Data Type as Number. 

Person to Company Rollup

Function to auto-rollup data from Person Time Series fields to Company Time Series (Daily and Weekly) objects.

Applicable only for fields with Data Type as Number. 

Date Format

Default format for date and time.

Applicable only for fields with Data Type as DateTime.

Time Zone

Default time zone for the field.

Applicable only for fields with Data Type as DateTime.

Notes: 

  • You can only convert the source fields in Person Time Series objects to Company Time Series objects and not the derived fields.
  • By default, the source fields in Person Time Series objects with Dimension data type are converted to Company Time Series objects.
  1. Enable Leaderboard:
    1. Select the Enable Leaderboard checkbox to create a derived field in the Weekly Time Series object. This allows 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 (ascending) or DESC (descending) 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 Dashboard Configuration page 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 Report 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 a 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 in the Validations field and enter the value(s), as required.
  2. Click Save.

IMPORTANT:

If you have configured Google Analytics (GA) as 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 from Additional Resources.
  • In a group, you can add a maximum of 7 Dimensions and 10 Measures. If the need arises for 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.

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 Reports, 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. Expand the required object and 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.

Once the required fields are selected, you can view the tracked fields after 7 days while creating Usage Reports, provided a scheduled RUN has already happened

Once the Adoption Explorer Objects are configured, you can create Derived Fields using the ingested measures and dimensions. For information on how to create Derived Fields, refer to the Configure Derived Fields article from Additional Resources. For information on how to create a usage dashboard, refer to the Configure Dashboards article from Additional Resources.

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.

Download Archived Data

Admins can download the historical usage data that is archived in Adoption Explorer for all the available time series objects or the selected time series object(s).

IMPORTANT: 

  • Admins can download the data that has been archived in the last 180 days.
  • Adoption Explorer allows you to download archived data for four times in a month.