Gainsight administrators can now create and manage the Matrix Data - Objects (formerly known as Subject Areas) using the “Data Management” application.

As an analogy, a Matrix Data - Object and its field can be thought of as a database table and its columns.      

Data Management can be accessed via the Administration > Operations > Data Management link as shown below:

This article describes how to:          

  • Create Matrix Data - Object Manually
  • Create Matrix Data - Object Automatically
  • Edit Matrix Data - Object
  • Update/Upsert Matrix Data - Object using Update Keys
  • Load data into a Matrix Data - Object
  • Check Dependencies on the Matrix Data - Object
  • View Activity Log
  • Create Calculated Fields on the Matrix Data - Object

See Also:

  • Supported Data Types

Navigate to Administration > Operation > Data Management. Object listing page appears.

Prerequisites

Contact Gainsight Customer Support (support@gainsight.com) to enable Redshift if object lookup functionality is required.

Limitations

  • All of the objects, including out-of-the-box objects, (read-only objects) and custom objects are displayed.
  • MDA object fields have a maximum limit of 250 characters.

Permissions

In order to access the Data Management console, and be able to view and load data, a user must have access to the visual Force Page JBCXM.COM.

How to Manually Create Matrix Data - Object

To create a MDA object:

  1. Navigate to Administration > Operations > Data Management. Click +Object.
  2. In the Create Object dialog, enter the following details:
  • Object display name: The easily understandable object display name that you want to create.
  • Object name: System defined object name with a suffix of __gc.
  • Object description: A description of the object being created.
  1. Select Manual and then click NEXT. Create Field screen appears. Enter the following details:
  • Display Name: The easily understandable display name.
  • Field Name: The system defined field name with a suffix of __gc.
  • Data type: The data type of the field being created.
  • Default Value: The default value that you would like to insert in the object field.
  • Mapping: Select either SFDC or Gainsight mapping. Depending on the selection here, either SFDC Mapping or GS Mapping list box appears.
  • SFDC Mapping/GS Mapping: Map the field being created with an SFDC object or Gainsight object, if any.
  • Description: The description of the object being created.
  • Hide in reporting: If you select this, the field will be hidden in the Reporting functionality.
  • Required: By setting this constraint, the field is not allowed to ingest a null value record while importing data.

Notes:

  • The Enable lookup Relation checkbox appears only when the field is of String, SFDC ID, or Email data type and the underlying data store for the objects is AWS Redshift rather than MongoDB. To know if AWS Redshift is enabled as a data store for your objects, please contact Gainsight support (support@gainsight.com).
  • Currently, Gainsight does not support duplicate Display Name.
  • The idea for generating the technical field names is to simplify the formula setup on MDA objects. However, formula setup on MDA objects is not supported.
  • While importing data into the field:
    • If an user sets a default value for the field and the source record is empty/null, then that default value will be ingested.
    • If the default value is not set and the source record is empty/null, then that record will be rejected.
    • Required constraint can only be applied on a field which does not have any null/empty values.
    • It is recommended not to apply the Required constraint on a newly added field.
  1. Add another: This is to add the current field and to open new dialog to add another field. This helps to create multiple fields in a single instance.
  2. Click ADD; then click SAVE. Object with one or more fields gets created.
  3. Once object is created, You can click Delete Object and Edit Object to delete the object and edit the object name respectively. These two options are available only for custom objects only.
  4. Click ADD FIELD to add new fields in any object.

  1. Click ADD FIELD to add the remaining fields of the created object.

Creating an Object Automatically Using a CSV

If a new object that needs to be created has a lot of fields, creating it manually using the Data Management user interface is a cumbersome and error prone process.

If you have a CSV data file that contains field names as headers and some data, the object creation process can be automated as below:

  • Field name is taken from the CSV header file
  • Data type of the field is auto-inferred from the CSV data file
  • Optionally, the data from the file can be imported into the object

To create an object using a CSV data file:

  1. Navigate to Administration > Operations > Data Management. Click +OBJECT.
  2. Enter the following details:
  • Object display name: The easily understandable object display name that you want to create.
  • Object name: System defined object name with a suffix of __gc.
  • Object description: Enter a description for the object being created.
  • Select Data File Upload (CSV)
  1. Click BROWSE to select the appropriate CSV file. Click NEXT.

The CSV headers are taken as is and Target Object Field Display name, Field name, and Target Object Data Type are created automatically as shown in the image below. You can change the field display name and field name. You can select a different data type, if the automatic matching is incorrect.

Note: You must select the field for which you assign a default value during the data ingestion process (for example, uploading data using a CSV file). Otherwise, the field contains a NULL value.

  1. (Optional) You can assign default values to the Target Object fields.
  2. Select Load Data to ingest data from CSV to target object. Otherwise, only the schema would be created.
  3. Click CREATE.

Editing a Matrix Data - Object

To edit a Matrix Data - Object:

  1. Go to Administration > Operations > Data Management > All Objects > [Click on an existing object] > Schema.
  1. Click on the pencil (Edit) icon to edit a particular field.

Notes:

  • Only editable fields can be edited in an object.
  • The total number of records available in the object is displayed at the top.
  • You can delete any custom object using the DELETE OBJECT button if the object has no dependencies. If there are any dependencies, you should delete the dependencies to delete the custom object.

Update/Upsert Matrix Data - Object using Update Keys

Admins can define the key field(s) that must be used on an object to update or upsert the existing records using the new Update Keys tab. This is primarily introduced to avoid updating the existing data with the wrong key fields (as it can corrupt the entire object data) and ensure that Update / Upsert operations are allowed ONLY when the valid keys are used.

To update a Matrix Data - Object:

  1. Navigate to Administration > Operations > Data Management > [Click on an existing object] > Update Keys.
  2. Drag-and-drop the desired fields from AVAILABLE KEYS to MAPPED UPDATE KEYS.
  3. Click SAVE AND VALIDATE. This defines the Update key(s).

Notes:

  • AVAILABLE KEYS: Displays all fields available in the selected object.
  • MAPPED UPDATE KEYS: After you drag-and-drop fields from AVAILABLE KEYS to MAPPED UPDATE KEYS, it reflects the key fields that you use to identify unique object records during an UPDATE/UPSERT.
  • If MAPPED UPDATE KEYS do not represent a unique record, an error message is displayed when you click SAVE AND VALIDATE.
  • Once Update key(s) are defined, subsequent Update or Upsert operation in the data Ingest (S3 connector , Gainsight Bulk API, or Rules engine > Load to MDA) is allowed only when the same update/upsert keys are used. If the keys are different, the update/upsert process would fail. Therefore, exercise caution while enabling this feature for an existing object. Existing rules will fail if the update keys are different. We strongly recommend that you create a new object, and experiment with this feature.

How to Load Data into Matrix Data - Object

Once you have created a Matrix Data - Object, you can load data into the object. It is designed to load small files (under 1 MB). The purpose is to manually load a small data file and view the object data in the data browser to verify its structure.

For loading larger files, please consider other methods like loading data via cURL and Data Load API or Gainsight S3 connector for data import.

To load data into an MDA object:

  1. Navigate to Administration > Operations > Data Management > [Select the object in which you want to load data].
  2. Click Import Data > Choose file to select the CSV file. Optionally, you can click GENERATE CURL to generate a sample template for inserting data into the object. This sample template needs to be modified as per cURL requirements. For more information, refer to Gainsight's Load API for Matrix Data Store.
  3. Click PROCEED TO MAPPINGS; then map the CSV file fields with that of the object fields. If the field names are the same in both the CSV file and the object, the mappings are done automatically.

4. Click VALIDATE; then click LOAD DATA. If something is missing or is incorrect, during validation, an error is thrown and you will be asked to perform the correct mapping.

Note: Only CSV files that are less than 1 MB can be loaded.

5. In the left pane, click Data. You can now see the data loaded from CSV file to the created object.

Viewing Objects/Schema/Data Columns

You can select the columns that you would like to see while viewing an object or schema using the menu icon as shown in the image below.

Deleting Data from a Matrix Data - Object

To delete data from a Matrix Data - Objects:

1. Navigate to Administration > Operations > Data Management > All Objects > [Click on an existing object] > Data.

2. You can perform either of the following operations:

Delete All: You can click Delete All to delete all data from a Matrix Data - Object.

Delete specific data: You can first filter the data that you want to delete and then click Delete to delete the filtered data.

How to Check Dependencies on a Matrix Data - Object

Once the Matrix Data - Objects are created and then referenced in a different part of the application, we wish to restrict the Gainsight Administrators from accidentally modifying or deleting the Matrix Data - Objects as part of the object dependency tracking feature.

Currently, we are tracking the below application areas for dependency:

Relationships

  1. Rules
  2. Reports
  3. Relationships
  4. Data Integrations
  5. Power Lists
  6. Email Templates
  7. S3 Jobs
  8. MixPanel
  9. Bulk API

To identify Rules or Reports that are dependent on a custom object:

1. Navigate to Administration > Operations > Data Management > [Select the object for which you want to check dependencies].

2. Click Dependencies on the left pane to see Rules, Reports, Relationships, Data Integrations, and Power Lists, Email Templates, S3 Jobs, Mixpanel, and Bulk API that are dependent on the custom object you selected.

Dropdown Lists

Dropdown list is a data type for all custom fields in MDA standard and custom objects. By default, Gainsight ships Customer Stage and Customer Status dropdown list categories for standard and system fields of Company object and these cannot be editable. You can create custom dropdown list categories and define items in each category. Once a custom dropdown list is created, you can map it to any custom field in the standard and custom objects. You can create custom fields in the standard and custom objects with datatype as Dropdown List and select required custom dropdown list category.

Example: A Company may want to track the quarterly sales of a product. Admins can create a category with four items Q1, Q2, Q3, and Q4, and map this custom category to a custom field of drop down list type in the standard and custom objects. The custom field can be used in other functionalities as required.

To create a new drop-down list category:

  1. Navigate to Administration > Data Management > Dropdown Lists.
  2. Click +CATEGORY. Create category dialog appears.

  1. Enter the Category Name and Description. Click ADD.

To create items in a category:

  1. Click the Category Name and click +ITEM.

  1. Enter the following in the Add new item dialog:
  • Name: Maximum 50 Characters are allowed.
  • Short Name: Maximum 20 Characters are allowed.
  • Active: Checkbox
  • Item color: Select a color
  • Description: [Optional] Maximum 255 Characters are allowed.
  1. Click ADD. Select Add another to add an item and open new dialog to add another item.

  1. The items can be arranged in an order. You can Sort alphabetically or Rearrange the items with the SORT and REORDER buttons.

Note: When data is loaded into the custom field with datatype dropdown list through any of the ingest channels, it is restricted to load data into the items defined in the custom category.

To create a custom field of dropdown list data type:

  1. Navigate to Administration > Data Management > [Select an object into which you want to create a custom field].

  1. Click Add Field. Add field dialog appears.

  1. Enter the following details:
  • Display Name: The easily understandable display name.
  • Field Name: The system defined field name with a suffix of __gc.
  • Data type: Select Dropdown list.
  • Category: Select the required dropdown list category. This maps the dropdown list category to a custom field.
  1. Click Add. Custom field of dropdown list type is created.

Viewing Activity Log

This section helps you see all changes made to MDA Data Object.

To view activity log:

1. Navigate to Administration > Operations > Data Management > Activity Log.

The Activity Log tab displays log details of each object. In addition, you can click the Details link to get detailed log information of the object for an operation.

Things to Remember

  • Calculated fields can be created using Numeric, Currency, and Percentage data types.
  • Number, Currency, and Percentage can be used in formula fields while building a formula.
  • Fields and Operators can be inserted in the Formula field through the mouse click only.
  • Numeric values, functions, and advanced operators are not supported as of now.

To create a calculated field on a Matrix Data - Object:

1. Navigate to Administration > Operations > Data Management.

2. Click on the desired object for which you want to create a calculated field; then click ADD FIELD.

3. In the pop-up window, enter the following details:

  • Display Name: The display name of the field.
  • Field Name: The Field Name that is automatically generated.
  • Data Type: select Number.
  1. Select Calculated Field; then click CREATE FORMULA. You will be navigated to the Formula Builder window which is enhanced with the complete Field names and Operators, and the addition of the ADVANCED FORMULA option to create complex formulas.

Note: The Calculated Field checkbox appears only if there are at least two Number fields present.

ADVANCED FORMULA builder helps the Admins to create complex formulas like performing arithmetic operations and case statements.

Basic arithmetic operations with constants

  • Examples : A + 10,  A - 1, A*100 , A/100, (A+B)/2

Case statements

Examples:

  • case when A>0 then 1 else 0 end
  • case when A-B>=0 then A-B else C-B end
  • case when A=B then 1 else 0 end
  • case when A is null then 0 else B * (180/7) end
  • case when (A+B+C+D) = 0 then 0 else ((E+F+G+H+I)/(A+B+C+D)*100) end

Note:

  • Ensure that the syntax is correct.
  • Validator for advanced formula is being developed.
  • Once an advanced formula field is set, reverting to a basic formula is not supported as basic formula builder does not support these operations.

5. Click ADD.

Note: Gainsight recommends you to write down your formula on paper. If you get it wrong while building the formula in the Formula field, you will have to start all over again. The formula can be edited from right to left using the close icon. 

6. Click VALIDATE; then click SAVE for the formula created.
 
7. Click ADD to add the calculated field to the object; then click SAVE. The calculated field has a c icon suffixed to it, as shown in the image below.

8. (Optional) You can click on the Pencil icon corresponding with the calculated field to edit the formula, if required.

Things to remember:

  • Field Name can be used in a calculated field or curl command.

The following image shows how Field Names look while configuring a calculated field. For more information about this support related enhancements, refer to the '4. Dropdown list data type' section under Gainsight Data Management (GDM) in the Release Notes Version 5.5 February 2017.

The following image shows how Field Names appear when a curl command is generated. 

Supported Data Types

Data Types Description Information
String The String data type. This data type can be mapped (Join Field data type) to String, SFDCID, and Email.
Boolean The Boolean data type.  
Date The Data data type.  
DateTime The DateTime data type.  
Number The Number data type. Formula Support: Formulas are supported through Formula Builder; they must be set from the Tenant Management. For more information about this support, refer to the '3. Advanced formula builder available in free form editor' section under Gainsight Data Management (GDM) in the Release Notes Version 5.5 February 2017.
SFDC ID The SFDC ID data type.

 
When data is being loaded to an MDA object with SFDC ID as a data type, the application checks and converts 15 digit IDs to 18 digit SFDC ID. If the SFDC ID value is not a 15 digit or an 18 digit record, data would be rejected. SFDC ID field can contain NULL.

This data type can be mapped (Join Field data type) to string and SFDCID.
GS ID   A 36 digit unique GSID is assigned for identification of each externally exposed “Object” and “Record” from Gainsight. It is assigned automatically to each record in MDA. You can import GSID of a record from one MDA object to another through data import lookup while ingesting data through Gainsight Bulk API, GS Connect, and S3 Connector. For more information, refer to Data Import Lookup.
Email The Email data type.

Info

When data is being loaded to an MDA object with Email as a data type, the application validates the email ID with the following criteria.

The email ID must have:

1. At least one @ in the email address.

2. There should be at least one character before and after @

This data type can be mapped (Join Field data type) to String and Email.
Dropdown List   This data type is available for all custom fields in MDA Standard and custom objects. You can use this data type fields in other functionalities as required. By default, Gainsight ships Customer Stage and Customer Status dropdown list categories for standard and system fields of Company object and these cannot be editable. 
Currency  
  • The help icon for Currency Code that appears when the Currency data type is selected displays the currencies supported.

  • You can enter a number, number with thousand separator, number with currency symbol appended, or number with currency code appended. For example, 1000, $1000, 100,000, or USD1000.

  • If the data includes currency symbol/currency code, such as "USD 100", "$ 100", "100 USD", or "100 $", there should not be any space before or after the currency symbol or code.

  • Only thousand separator comma is supported. For example, 100,000.

  • If the data includes a thousand separator; for example, 10,324,342, the data should be enclosed within double quotation marks ("10,324,342"). Otherwise, it will be considered as data for the next columns.

  • Formula Support: Formulas are supported through Formula Builder; they must be set from the Tenant Management. For more information about this support, refer to the '3. Advanced formula builder available in free form editor' section under Gainsight Data Management (GDM) in the Release Notes Version 5.5 February 2017.
  • Report Filters: To search for a specific value in the report, use only the number. For example, to search for $10, enter 10. 

  • Usage in CoPilot: If the user is using a currency value in the Email Template as a token, and the record value is 12, the $ symbol will not automatically appear in the email. For example, you must add the currency symbol ($<token>) before the token in the email body for the email to display as $12. 

  • A table below shows how the currency numbers will be formatted in various areas of Gainsight.
Percentage  
  • You can enter values with a percentage symbol. For example, 10%.

  • You can enter 0.1 as a value that will be automatically calculated as 10%.

  • You can enter percentage values with decimals. For example, 98.33%.

  • Formula Support: Formulas are supported through Formula Builder; they must be set from the Tenant Management. For more information about this support, refer to the '2. Advanced formula builder available in free form editor' section under Gainsight Data Management (GDM) in the Release Notes Version 5.5 February 2017.

  • Report Filters: To search for a specific value in the report, use only the number. For example, to search for 10%, enter 10. 

  • Usage in CoPilot: If the user is using a percentage value in the Email Template as a token, and the record value is 12, the % symbol will not automatically appear in the email. For example, you must add the percentage symbol (<token>%) after the token in the email body for the email to display as 12%. 

  • A table below shows how the percentage numbers will be formatted in various areas of Gainsight.

The following table shows how the currency numbers are stored in various areas of Gainsight.

Currency type at Object level (GDM) Data Ingest Format MDA Storage Format Format in Reporting Format in Formula Fields
USD $1,000 1000 $1,000 1000
INR ₹55.25 55.25 ₹55 55.25
USD USD100 100 $100 100
USD 100$ 100 $100 100

The following table shows how the percentage numbers are stored in various areas of Gainsight.

Data Ingest Format MDA Storage Format Format in Reporting Format in Calculated Fields
0.1 0.1 10% 0.1
10% 0.1 10% 0.1
 

MDA Standard Objects

All customers are provisioned with standard objects namely Company, User, Relationship, and Relationship Type. These standard objects can be viewed under Data Management, as shown in the following image. A set of standard fields with predefined mappings are shipped by Gainsight. Customers can add custom fields, update schema of custom fields, and implement Read and Join tasks (from Reporting, CoPilot and Scorecards). Gainsight Connect helps to import the data from Salesforce to MDA standard objects. Admins can import data into standard objects from a CSV file through S3 Connector and Gainsight Bulk API. Once data is imported into standard fields, Admins cannot delete it. Admins can view the standard objects in the Administration > Operations > Data Management location.

Note: The standard objects are visible in the Rules Engine under the source only when there is a MDA join on Standard Objects. MDA standard objects include Picklist, User, Company, Relationship Type, and Relationship. You can import data in these objects using Gainsight ConnectS3 Connector, and Gainsight Bulk API.

These Standard objects will have the following:

  Schema Editability? Data Editability?
Standard Objects Yes Yes
Standard Fields No Yes
Custom Fields Yes Yes

System Fields

  • GSID: Auto generated and unique

  • Created Date: System generated

  • Modified Date: System generated

No No

 

Data can be ingested into the standard objects using the following options:

  1. Gainsight Connect

  2. S3 Connector

  3. Gainsight Bulk API