Basic Operations in Data Management
Overview
This article explains the basic operations which you can perform in the Data Management page such as:
- Gainsight Standard Objects
- Create a Gainsight Object Manually
- Create a Low Volume Object Manually
- Add Custom Fields in an Object
- Supported Data Types
- Create a Gainsight Object Automatically Using a CSV
- Edit a Gainsight Object
- Update/Upsert Gainsight Object using Update Keys
- Load data into the Gainsight Object
- Delete data from a Gainsight Object
- Delete an Object and its Fields
Gainsight Standard Objects
Gainsight provides the following types of objects as part of its Data Management:
- Standard Objects
- Custom Objects
- Application Objects
For more information on the Standard Objects, refer Gainsight Objects.
Create a Gainsight Object Manually
To create a Gainsight object:
- Navigate to Administration > Operations > Data Management.
- Click + OBJECT.
- In the Create Object dialog box, 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 (Auto-generated, based on the name entered in Object display name).
- Object description: A description of the object being created.
- Select Manual, to add the fields for this object manually.
- Click NEXT. Add Field screen is displayed.
Create a Low Volume Object Manually
Low Volume Objects are custom objects that can be created by Admins from the data management page to store low volume data which needs to be edited frequently. Admins can create these objects directly from data management page. For more information, refer to the Low Volume Custom Objects article.
Note: These Low Volume objects were formerly called as Transactional objects.
To create a Low Volume custom object:
- Navigate to Administration > Operations > Data Management.
- Click + OBJECT.
- In the Create Object dialog box, 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 (Auto-generated, based on the name entered in Object display name).
- Object description: A description of the object being created.
- Low Volume Object: Select this Checkbox to create the custom object of type Low Volume.
- Select either Manual or Data file upload (CSV) as required.
- Click NEXT. Add Field screen appears.
Add Custom Fields in an Object
To add Custom Fields in an Object:
- Enter the following details in the Add Field screen:
- Display Name: Enter an 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.
- Currency Code: You can view this field, only when the Currency Data type is selected. Select a currency code from the list. For the list of currency codes supported, refer to the Supported Data Types section.
- Default Value: The default value that you would like to insert in the object field. This is a dynamic field whose data type changes automatically, based on the Data type selected above. This field is not displayed when you select the GS ID Data type.
- Decimal Places: This field is displayed only when you select either Currency, Number, or Percentage Data type. Assign the number of decimal places on the values in the field. By default, assigned decimal places is 0.
- Mapping: This field is displayed only when you select either GSID, Date, DateTime, Email or, String Data Type. You can map the current field only to standard fields from Gainsight Objects. You can map the field being created with a suitable standard field so that values in the current field are enabled with hyperlinking. For example, if you map a field to the Gainsight Company Name, then the company name is populated with a hyperlink in the application. If end users click the hyperlink, it navigates to the C360 page for that company.
Standard fields that you can map to are Company Id, Company Name, Relationship Id, Relationship Name, Relationship Type Id, Relationship Type Name, User Email, User Id, User Name, Person Email, Person Name, Person Id, and Company Person Id.
- Category: This field is displayed only when you select either Dropdown list or Multi select dropdown list Data types. You must select a Category for the Drop down list. For more information on Drop down lists, refer to the Dropdown List and Multi Select Dropdown List article.
- Max length: This field is visible only when you select the Rich Text Area Data type. You should specify the maximum length of words supported by this field.
- Description: The description of the object being created.
- Hide in reporting: If you select this checkbox, 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.
- Enable lookup: This checkbox is displayed only when you select either Email, String or GS ID Data type. If selected, this checkbox allows the object to lookup to another object while ingesting data into this object. When you select this checkbox, the following three fields are displayed.
- Object: Select the Source Object from which data will be ingested into this field.
- Field: Once you select an object in the Object field, its corresponding fields are displayed here. select the source field to which lookup is enabled from the current field.
- On Delete: This field allows you to reset the records of this field, when the corresponding lookup record is deleted. This field has three options:
- Cascade Delete: When the lookup record is deleted, the corresponding record in the current object is deleted.
- Set Null: When the lookup record is deleted, the corresponding value in the current field is Set to Null.
- None: When the lookup record is deleted, no action will be taken in the current object.
Conditions for On Delete:
- On Delete option is not enabled until you click the Object Graph in any object. For more information on the Object Graph, refer to the Object Graphs section.
- You can see only None item in the On Delete option while applying MDA join from a:
- Custom field in the User or Person object.
- Custom field of any object to either User or Person object.
- Both of these conditions are imposed to make sure that none of the records are deleted from either User or Person object.
- By default, On Delete option in the existing MDA joins is None from a custom field in any object. On Delete option in the existing MDA joins is set to None from any field to either User or Person object and vice-versa.
- You can select any On Delete option in a custom field of Who ID data type. This option allows you to reset records in this field when the corresponding person lookup record is deleted from the Data Operation page.
- Currently, On Delete functionality does not work even when you can delete records from a custom object (from the data management page) that has lookup to another custom object.
Notes:
- You cannot apply MDA Joins from any standard or system field.
- You can apply MDA joins from any custom field of data type String, GSID, and email.
- Enable self lookup: If you enable this to a field, it allows you to populate GSID from another record by looking up to one or more fields in the same standard object. Admins can use Data import lookup functionality in different connectors to ingest the correct GSID. It creates an MDA join to the GSID of the self object. This is used to create User - Manager hierarchies up to one level and ‘My team’ and ‘Portfolio view’ reports.
Note: Once you enable self lookup, you cannot disable it.
Notes:
- Enable self lookup:
- You can see this checkbox only when you add fields of data type GSID.
- If you enable self lookup, Required and Enable lookup options are disabled.
- The Enable lookup checkbox is displayed only when the String or Email Data type is selected, 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 the Gainsight objects.
- If you do not assign the number of Decimal Places on the Number, Currency, or Percentage type fields, the values in the field will be rounded to simple numbers.
- While importing data into the field:
- If a 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.
- Add another: This checkbox is used to add the current field and to open new dialog to add another field. This helps to create multiple fields in a single instance.
- Click ADD; then click SAVE. Object with one or more fields gets created.
- Once the 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.
- Click ADD FIELD to add a new field in the object.
Supported Data Types
Data Types | Description | Information |
---|---|---|
String | The String data type | Any text. Maximum text length is 255 characters. This data type can be mapped (Join Field data type) to String, SFDCID, and Email. |
Boolean | The Boolean data type | 0 or 1; True or False |
Date | The Date data type |
Stores the date component.
|
DateTime | The DateTime data type |
Stores the date along with time.
|
Number | The Number data type |
A whole number or number with decimal places. Formula Support: Formulas are supported through Formula Builder; they must be set from the Tenant Management. |
SFDC ID | The SFDC ID data type |
When data is being loaded to an Gainsight 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 Gainsight. You can import GSID of a record from one Gainsight object to another through data import lookup while ingesting data through Gainsight Bulk API, Rules Engine, and S3 Connector. For more information, refer to the Data Import Lookup article. | |
The Email data type Info |
When data is being loaded to an Gainsight object with Email as a data type, the application validates the email ID with the following criteria. The email ID must have:
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 Gainsight Standard and custom objects. You can use this data type field in other functionalities as required. For more information, refer to the Dropdown List and Multi Select Dropdown List article. | |
Multi Select Dropdown List | This data type is available for all custom fields in Gainsight standard and custom objects. This is used when a user wants to store multiple values for the same record. For more information, refer to the Dropdown List and Multi Select Dropdown List article. | |
Rich Text Area |
Limitations:
|
|
Currency |
|
|
Percentage |
|
|
Who ID | A field of this data type can be created in any standard or custom object. This field has the ability to dynamically join with the User or Person object to identify a user or person uniquely from the current object. This helps to build reports on the current object and join the selected fields from the Person or User object. | |
What ID URL |
Admins would be able to create a field of this data type in any standard or custom object. This field has the ability to dynamically join with another standard object to fetch the source information. This helps to build reports on the current object and join the selected fields from the standard object. Currently, Gainsight does not support to create a new field of this data type. You can use this Data type to store web site addresses. You can ingest values into these data type fields that start with either http:// or https:// prefix and end with .com, .org, or any other suffix. If you try to ingest values without the prefix or suffix, such values are not ingested. |
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 decimal 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 |
Create 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:
- Navigate to Administration > Operations > Data Management. Click +OBJECT.
- 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 the Data File Upload (CSV) option.
- 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.
- (Optional) You can assign default values to the Target Object fields. If a null value is ingested into the field through any data ingestion channel, the null value will be replaced with the assigned default value into the field.
- Select the Data type for every field.
- Select the Load Data checkbox to ingest data from CSV to the target object. Otherwise, only the schema would be created. Once Load Data is selected, Timezone dialog appears as shown below:
- You can view a clock icon for the fields with Date Data type.
- Click OK.
- Click the Clock icon. Select a Timezone dialog appears.
- Select a Timezone from the dropdown list and click OK. This is to assign a timezone for the Date and DateTime values. These values are then converted into UTC from the selected timezone and are stored in the Gainsight object. If you do not select a timezone, the records are considered to be in the Gainsight Timezone. The Date and Datetime values are then converted into UTC from the Gainsight Timezone and are stored in the Gainsight object.
- Click CREATE. Records from the CSV file will be ingested into the Gainsight object.
If you are using a keyword as a Display name, you get an error message. You must change the display name for the corresponding field.
Edit a Gainsight Object
To edit a Gainsight Object:
- Navigate to Administration > Operations > Data Management > [Click an existing object].
- Click 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 Gainsight 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 Gainsight Object:
- Navigate to Administration > Operations > Data Management.
- [Click on an existing object] > Update Keys.
- Drag-and-drop the desired fields from AVAILABLE KEYS to MAPPED UPDATE KEYS.
- 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 Gainsight Object) 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.
Load Data into the Gainsight Object
Once you have created a Gainsight 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 large files, please consider other methods like loading data via Gainsight Bulk API or Gainsight S3 Connector for data import.
To load data into a Gainsight object:
- Navigate to Administration > Operations > Data Management > [Select the object in which you want to load data].
- Click Import Data > Click Choose file to browse and select a CSV file.
- Click PROCEED TO MAPPINGS; then map the CSV headers 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. You can see a Clock icon for the Date and DateTime field mappings.
- Click the Clock icon. Select a Timezone dialog appears.
- Select a Timezone from the dropdown list and click OK. This is to assign a timezone for the Date and DateTime values. These values are then converted into UTC from the selected timezone and are stored in the Gainsight object. If you do not select a timezone, the records are considered to be in the Gainsight Timezone. The Date and Datetime values are then converted into UTC from the Gainsight Timezone and are stored in the Gainsight object.
- Click VALIDATE. If something is missing or is incorrect, during validation, you can see an error in the page as shown below. Click the link here and download the error file to view the error details. As per the error details, perform the correct field mappings or make changes to the records in the CSV file as required.
Note: Only CSV files that are less than 1 MB can be loaded.
When you rectify the error in the CSV file and reload it. You must validate it again. If there are no further errors, you get a successful message as shown in the following image.
- Click LOAD DATA. Records from the CSV file will be ingested into the Gainsight object.
- In the left pane, click Data. You can now see the data loaded from the CSV file into the Gainsight object.
Delete Data from a Gainsight Object
You can delete records from the custom objects only from the Data Management page. You can delete whole data from a custom object or filter records as required and delete them. To delete data from the Gainsight custom object:
- Navigate to Administration > Operations > Data Management > [Click on an existing object] > Data.
- You can perform either of the following operations:
Delete All: Click Delete All to delete all data from the Custom Object.
Delete specific data: First filter the data that you want to delete and then click Delete, to delete the filtered data.
Delete an Object and its Fields
Admins can delete any unwanted or unused Gainsight custom object and any custom field in the Gainsight standard or custom objects. The specific objects and the fields can be deleted irrespective of whether they have data or not. These objects and fields can be deleted when they do not have any dependencies (it is not being used in any of the consumption areas). To delete a custom object or field, Admins should remove its dependencies first.
To delete a custom object or the custom fields:
- To delete a custom object:
- Navigate to Administration > Data Management > [Select a custom object that you want to delete].
- Click Delete Object. If it has any dependencies, the object cannot be deleted. It shows an error message and asks you to check and remove any dependencies on this custom object.
- To delete a custom field in a standard or custom object:
- Navigate to Administration > Data Management > [Select a standard or custom object that you want to delete fields in it].
- Click the Delete icon on a custom field that you want to delete. If it has any dependencies, the field cannot be deleted. It shows an error message and asks you to check and remove any dependencies on this custom field.
Note: You can see the Delete icon only for the custom fields.
- Click the Dependencies tab in the left pane. You can see all of the dependency features of an object and it fields. For more information, refer to the Check Dependencies on an Object section.
- Check all the features in the list to identify the dependencies on this object.
- If a feature has a dependency, click the Arrow icon on the object. It navigates you to that feature.
- Remove the fields from mappings in the connectors, remove the fields from a report configuration, remove the fields from a Rule setup, remove the field MDA lookups, etc.
- When all of the dependencies on this object are removed, you can delete a custom object and custom fields in the standard or custom objects as shown in the steps 1 and 2.