Gainsight Bulk API is a channel to load data into MDA objects and is an enhanced feature to the existing data loading through cURL commands. This is introduced 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 unified 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 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 DataImportJob into MDA custom object Bulk API Data Import. Names, records, and Access Key used in this document are just for reference only. Records in the CSV file with the headers Name and SFDCID are shown below:
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 and click Next. 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 Bulk API Data Import. 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 DataImportJob.csv file to upload. Make sure that the size of the CSV file is less than 1 MB and it contains headers. The CSV file is uploaded in this section to select mapping between CSV headers and MDA object fields.
- Select the appropriate Data Load Operation. Here we are performing Insert data load operation. For Update and Upsert operations, + button will be available to set key fields which will be used as identifiers.
- 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.
- 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)
- Gainsight Bulk API always supports the files which are encoding with UTF-8 only.
- 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.
- Click Fetch Mappings. A success message showing Fields Fetched Successfully appears.
- In the Mappings tab, map Target Object Fields with Source CSV field appropriately.
- Click +Add Fields to map more object fields with the CSV headers.
- In the Derived Mappings tab, click +Add Fields. Data import lookup configuration dialog appears. This is to lookup to a standard object and match fields to fetch Gainsight IDs (GSIDs) from the looked up object. Derived mappings can be performed only for target fields of GSID data type. For more information, refer to Data Import Lookup.
- Click the + button to match multiple fields between the source (object/CSV file) and target object to import correct GSID from the standard 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. 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 Bulk API Data Import > Data. You can see three records ingested from CSV file.