Gainsight Bulk API is a channel to load data into the MDA objects and is an enhanced feature to the existing data loading through cURL commands. This helps to reduce the complexity in using Gainsight cURL commands and to provide a better user Interface. It allows the user to load data based on Job ID which reads the fields mapping information from the job defined.
Admins can load data into MDA standard and custom objects using Gainsight Bulk API.
Following are the advantages of Bulk API over existing data load through cURL:
- Job creation and maintenance is easy
- Data import into standard objects is available
- Field Mapping available in the UI
- Ability to set up Data import Lookup with multiple field mapping
- Update Keys functionality for Update/Upsert operations
- Notification emails for Success and Failure of data import
- Track in detail Execution Logs and Audit Logs
To access the GS Bulk API, navigate to Administration > Connectors 2.0 > Connectors. You can see all of the connectors in the Connectors tab and jobs performed through Bulk API and their execution logs in the Data Jobs and Logs tabs respectively.
This article describes how to:
- Create a Connection
- Ingest Data into the MDA Object from a CSV file
Create a Bulk API Connection
Before loading data into an object through GS Bulk API, admins should create a Connection. The system allows users to create one connection per tenant. Under one connection, Admins can perform multiple jobs to ingest data into the objects. To create a connection:
- Click the Connections and Create Connection icon.
- Enter Connection Name and click Generate Access Key. New Access Key is generated.
- Copy the Access Key and save to use it later. Click Create. A Connection is successfully created.
Ingest Data into MDA Objects from a CSV file
Here we ingest records from CSV file CompanyDetails.csv into MDA custom object Year 2017 Company Records. The names, records, and Access Key used in this document are just for reference only. Records in the CSV file with the headers Name, SFDCID, Industry, Employees, Original Contract Date, and Renewal Date are shown below:
Make sure that the formats of the Date and DateTime values in the CSV file are supported in the MDA. For the list of supported formats in the MDA, refer Gainsight Data Management.
Admins can create multiple jobs to ingest data into the objects. To create a Job:
- Click Create a Data ingest Job icon.
- Three sections, Job Details, Field Mappings, and cURL API appears.
Job Details section
- Enter a unique Job Name in the Job Details section.
- In the Notification recipients, enter:
- Success recipients: If a job has partial/full data import success, a success notification email is sent to the email ID entered here.
- Failure recipients: When all records fail to import, a failure notification email is sent to the email ID entered here.
- Click Save. System will validate for any job with same name. If it finds a duplicate job name, It will show an error Job name already exists. You always need to assign a unique job name.
Field Mappings section
- Go to Field Mappings section and enter the following details:
- Select Target Object into which you want to ingest data. For example, select custom object Year 2017 Company Records. Once a job is saved with specific Target Object, it cannot be changed before ingesting data.
- Click Browse to select a source CSV file from the local machine and to upload. Select CompanyDetails.csv file to upload. Make sure that the CSV file has headers. The CSV file is uploaded in this section to select mapping between CSV headers and MDA object fields. You can ingest data from the CSV file of size upto 80 MB.
- Select the appropriate Data Load Operation. Here we are performing Insert data load operation. For Update and Upsert operations, click the + button to set key fields which will be used as identifiers.
- CSV Properties: Select appropriate CSV Properties. Recommended CSV properties:
- Character Encoding: UTF-8
- Separator: , (Comma)
- Quote Char: “ (Double Quote)
- Escape Char: Backslash
- Header Line: 1 (Mandatory)
- Multi select separator: ; (Semicolon)
- Gainsight Bulk API always supports the files which are encoding with UTF-8 only.
- A separator is used to separate the values of different fields in a CSV. User should use same separator in the job configuration which is used in the CSV file to upload. By default , (comma) is selected as separator but users can change it as required.
- Quote Character is used to import a value (along with special characters) specified in the Quotation while importing data. It is recommended to use same Quote Character in the job configuration which is used in the CSV file to upload. By default, Double Quote is selected in the job configuration but users can change to Single Quote as required.
- Escape character is used to include special character in the value. By default, Backslash is used as Escape Character before special character in the value. It is recommended to use Backslash in CSV file to avoid any discrepancy in the data after loading.
- Multi select separator is used to separate the multiple values of a field of data type multi select dropdown list. User should use same Multi select separator in the job configuration which is used in the CSV file to upload. By default ; (Semicolon) is selected as separator but users can change it as required.
- Click Fetch Mappings. A success message showing Fields Fetched Successfully appears.
- In the Mappings tab:
- Map the target object fields with the source CSV fields appropriately.
- While mapping the fields, select a data type for a field in the source. It shows all the fields in the target object with the corresponding possible data types. Select the required field in the target object. The table below shows the source data types with the corresponding possible target data types:
|Source Data Type||Target Data Type|
|String||String, SFDC ID, Dropdown list, Email, GSID, Rich Text Area, Multiselect Dropdown List|
|Number||Number, Percentage, Currency|
Example: If you select a Number type field in the source, it will show the fields in the target object with Number, Percentage, and Currency data types. You can select the field in the target object as required.
Complex data types (Ex: Multiselect dropdown list) in the target object can be mapped from their base data types (Ex: String) in the source CSV fields as shown in the table.
- While mapping Date and DateTime fields between the Source CSV field and the Target MDA object:
- Click the Clock icon. Select a Timezone dialog box 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 MDA 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 MDA object. For more information on Timezone standardization, refer Timezone Standardization at Gainsight.
- Click Add to map more object fields with the CSV headers.
- In the Derived Mappings tab, click Add. Data import lookup configuration dialog appears. This is to lookup to the same or another MDA standard object and match fields to fetch Gainsight IDs (GSIDs) from the looked up object and populate in the target field. Derived mappings can be performed only for target fields of GSID data type.
There are two types of lookups: Direct and Self. Direct lookup enables admins to lookup to another MDA standard object and fetch GSIDs of the records from the lookup object. Self lookup enables admins to lookup to the same standard object and fetch GSID of the another record to the target field. For more information, refer to Data Import Lookup.
- Click the + button to match multiple fields between the source CSV file and looked up object to import correct GSID from the standard object into the target object. When you have multiple matches or when no match is found, you can select from the given options as needed. Click Apply.
- When Field Mappings and Derived Field Mappings are completed, click Save Mappings. A success message showing Job Created Successfully appears.
cURL API section
- Go to cURL API section and click Generate. cURL Command is generated.
- Click Copy to copy the cURL Command. Paste this cURL Command to any text editor.
- In the cURL command, enter the Access Key copied earlier and File Path as shown in the image below:
- Enter the cURL command in the Terminal and submit. The data is ingested into the object successfully.
- There is an Email sent to the success or failure recipients to inform the success or failure of the job as shown in the image below:
- Navigate to Administration > Connectors 2.0 > Logs. You can see Audit Log and Execution Log with success or failure for this data ingest job. For failure execution logs, you can see the reasons of data ingest failure to take appropriate action before ingesting the data again. Execution Log:
- Navigate to Administration > Data Management > [Click the object Year 2017 Company Records] > Data. You can see five records ingested from CSV file with the associated fields.