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

ScreenClip.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 in to the Usage Info and Timeseries objects using the following channels:

  1. Amazon S3
  2. Gainsight
  3. Google Analytics (GA)
  4. Salesforce (SFDC): Usage data from SFDC will be ingested into Adoption Explorer objects, in 24 hours

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.   

To setup a Source Connection:

Source Name

To create Source Name:

  1. Navigate to Administration > Usage Domain Model > 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

Overview (1).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. The date pattern can be specified by the text '${pattern}' anywhere in the file path. Ex: 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”. 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. 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. Field Separator: helps you in selecting either CSV or TSV files.
  9. 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.
  10. 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.

Get fields.png

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.

Source Gainsight.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.

GA sfdc (1).gif

Salesforce

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 sfdc.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 the 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.  

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.

SFDC MI.png

Identifier Mapping in Company Timeseries (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.

SFDC Identifier Mapping in Company Timeseries.gif

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.
  2. 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.
  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.

SFDC Compant Ent.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.

SFDC Identifier Mapping Person.gif

Identifier Mapping in Person Timeseries (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.

SFDC Identifier Mapping in person weekly.gif

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.

SFDC Person ent.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.

SFDC 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.

SFDC group edit.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 UMD objects, by default, this value will be used when the field value is empty/missing.
  4. Enable Leaderboard:
    • 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.
    • Enter the Leaderboard Display 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 Timeseries Objects.
  • Currently, the Layouts screen allows you to create a Leaderboard usage section only on the Person Timeseries Weekly object.

Enable Leaderboard New UI.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 new UI.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 new UI.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 new UI.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

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.

  • Was this article helpful?