IMPORTANT NOTE: Gainsight is upgrading Connectors 2.0 with Horizon Experience. This article applies to tenants which have been upgraded to the Horizon Experience for Connectors 2.0. If you are using Connectors 2.0 with the previous version, you can find the documentation here.
A connection is an integration between a Gainsight org and an external system. Creating Connection is the first step in the configuration of a connector from Gainsight to sync data from the respective external system to Gainsight. For general information on the Gainsight Connectors, refer to the Data Platform and Connectors Overview in the Additional Resource section at the end of this article.
Gainsight offers out of the box jobs for a few important connectors and Admins can create custom jobs as required. Customer data from the source system is fetched through these jobs, as configured. In the following sections you will learn about how to prepare and configure a dataset to create a Connector Job.
To create a Job:
- Navigate to Connectors 2.0 > Jobs. You can see the existing Jobs of all the Connections. These jobs are editable. For more information on Connectors Listing page and options, refer to the Connections List Page in the Additional Resource section at the end of this article.
- Click Create Job. The Dataset Preparation page appears.
- Prepare a Dataset. For more information on how to prepare a Dataset, refer to the next topic called Prepare a Dataset section.
Prepare a Dataset
To prepare a Dataset:
- In the Enter job name field, enter a name.
- From the Data Source dropdown, select the required external system. All the objects under the selected Data Source appear.
- Drag and drop the required Object from the Objects list to the Canvas screen. You will be navigated to a page, where you can see the Fields, Filters and Summary tabs.
Following options are available in the Fields tab:
- Name of the Dataset: Enter Dataset Name in the Name of the Dataset text box.
- Search: Search a field by its name and add it to the object.
- Add Fields: Click Add Fields to select the required fields that you want to add to the dataset, and then click Select.
- Fields: Displays the count and list of fields selected.
- Display Name: Default Field Name name appears in the Display Name text box, you can modify if required.
- Data Type: Displays the field data type.
- Delete: Click the Delete icon to delete a field from the dataset.
- Save: Click Save to save the changes made in the dataset.
To apply Filters:
- Navigate to the Filters tab.
- Click Add Filter.
- Select the field you want to filter on.
- Choose the Operator and then input the data in the Value text box.
- Add more filters by clicking the + icon next to the Value text box.
- Delete a filter by clicking the x icon.
- Add advance filters such as (A OR B) AND C, type in your desired expression in the Advanced Logic text box.
- Click Save.
In the Summary tab, you can view a list of all Fields and Filters in the Dataset.
- Once the dataset is prepared, you can Add Destination to the dataset or you can configure the dataset. For more information on how to Add Destination, refer to the Add Destination under Create Job section.
- If you have two or more datasets, you can perform the Merge action. For more information on how to perform the Merge action, refer to the Merge under Create Job section.
In the Preparation step of a connector job, admins can Transform data and Add Case Fields to get more meaningful insights from the customer data.
Example Business use case: The Transform function provides the capability to create or modify new case fields. The new case fields can be used to modify the external field as per the consumption requirement in Gainsight’s data model. Case fields can be defined to populate different values for different case conditions. For example, External picklist values such as New, Open, and Closed can be modified to Active and Inactive to match Gainsight’s picklist values.
Note: Transform function is only available for Zendesk, Freshdesk, ServiceNow, Jira, Zuora, Zoho and Pipedrive.
To transform a dataset:
- Navigate to Administration > Connectors 2.0 > Jobs tab.
- Click Create Job.
- In the Name of the Job field, enter a name.
- Click Next.
- In the Data Source dropdown list, select a source.
- Drag and drop the required object to the Preparation screen.
- From the context menu of the dataset, click Transform.
- Click Add Case Field.
- In the Label field, enter the name for the case field.
- In the Data Type field, select the data type as Boolean, Number, or String.
- Click Case 1 to expand the view.
- Click Add Filter to add a condition as per your requirement.
- In the THEN field, select the field and the value to display the resultant data when the set conditions are met.
- (Optional) Click +CASE to add another case field by following steps 3 to 7.
- In the DEFAULT field, select a value when none of the conditions match.
- Click Add.
- Click Save.
You can merge two datasets together and create an output dataset. You can merge two datasets or multiple datasets and create one final dataset.
Use Case: For instance, you might want to know the details of Tickets and User who create support tickets in Zendesk. To achieve this use case, you can merge datasets created on Zendesk Tickets and Zendesk Users objects into one output Dataset and import data into Gainsight Standard or Custom objects (Target object).
To merge two Datasets, select Merge from the options of the dataset that you want to merge with the required dataset.
Once you merge the datasets, a new window with the dataset name ‘Merge’ appears, where you can see Join, Fields, Filters and Summary tabs.
Basic JOIN clauses are used to combine rows from two or more tables, based on a common field between them. There are four types of Joins supported in Gainsight: Inner Join, Left Join, Right Join, and Outer Join. Each join type, when used with a Merge task in the Connectors, produces a slightly different data set. For more information, refer to the Join Types article in the Additional Resources section.
- Inner Join: It retains common records from both datasets.
- Left Join: It retains all the records from the left dataset.
- Right Join: It retains all the records from the right dataset.
- Full Outer Join: It retains all records from both datasets.
To join two Datasets:
- Navigate to the Join tab.
- Select the required Join type.
- Select a field from each dataset to set the criteria. For example, the User ID in the first dataset is Assignee ID, and User ID in the second dataset is ID while merging datasets created on the objects, Zendesk Tickets and Zendesk Users.
- Click + to add multiple record matching criteria. This helps filter the records based on your business requirements.
- Click Save.
The following options are available in the Fields tab:
- Select: Select/Deselect the individual fields that are added from the source datasets to add them to the merged output dataset.
- Display Name: By default, Field Name name appears in the Display Name textbox, you can modify if required.
- Save: Click Save to save the changes made in the merged dataset.
Filters in Merge work as Filters in Preparation of Dataset. For more details, refer to the Filters under Prepare a Dataset section.
Summary details in Merge are same as Summary details in Preparation of Dataset and in addition it displays Join details also. For more information, refer to the Summary section under the Create Job section.
You can now proceed to the configuration step. For more information on how to configure a dataset, refer to the Configuration of Job or Job Chain Schedule in the Additional Resource section at the end of this article.
If you want to delete a dataset permanently from a data job, click Delete from the options of the dataset.
Once the final output dataset is prepared, a destination can be added to the output dataset to sync data from the source to the target Gainsight object. In Add Destination, you can select the target object from Gainsight and map the source fields from external system objects to their corresponding target fields in Gainsight.
To add destination to the Dataset:
- Click Add Destination from the context menu of the final output dataset. A new window appears where the destination can be configured.
- Select the Gainsight Target object from the dropdown menu.
- Select the Primary Object from the dropdown menu.
Note: Select any of the source objects added to the canvas screen including merge or add destination. The source object cannot be changed once you proceed to the field mappings.
After you select the Gainsight and Primary Objects, you can configure the Direct and Derived Mappings.
In Direct Mapping, you should map fields from the output dataset to the target object in the field mappings. Data sync happens from the source fields of the external system to the target fields of Gainsight, based on the configured field mappings.
The following options are available in Direct Mapping:
- In Source Field column, all the selected source fields from the dataset appear.
- In Target Field column, select the target field to which data should be synced.
- Select the Include in identifiers check box for at least one of the fields. It helps to identify a unique record from Source to Gainsight while updating data into the mapped fields.
Note: Any Source field which has unique values can be used as an Identifier ( For example, Zendesk Ticket ID to External ID in Gainsight).
- Click Save.
You can proceed to the Job configuration step. For more information on how to configure a dataset, refer to the Configuration of Job or Job Chain Schedule in the Additional Resource section at the end of this article.
Note: This is optional and you must configure the derived mappings only if you want to populate values into the target fields of data type Gainsight ID (GSID). GSID values are populated from the same or another object through lookup.
In Derived Mappings, you can create Lookup mapping to the same object or another standard object in a data sync job and match up to six columns. Once the required matching is performed, you can fetch GSIDs from the lookup object into GSID data type fields. For more information on the derived mappings, refer to the Data Import Lookup in the Additional Resource section at the end of this article.
IMPORTANT: To use Derived Mappings, the Target Object must have at least one field of data type GSID.
To add Derived Mappings:
- Click Add Field Mapping. You can see the following options:
- In Source fields, select field from the output dataset which is used for lookup mapping.
- In Target Fields, select the field to which GSIDs are imported.
- In Select Lookup, the Compound Field Mapping is selected which imports GSID from lookup field to the target field, while ingesting data from the external system.
- In Source Object, select the source (lookup) object from which the GSIDs must be fetched.
- In MATCH BY SOURCE, the Source Field from the output dataset is selected.
- In MATCH BY TARGET, select the lookup field to match the records.
- In When Multiple Matches Occur dropdown menu, select a value.
Note: The selected value determines what action must be performed when multiple records are found for the matching criteria. The following are options in the dropdown menu of When Multiple Matches Occur dropdown menu:
- Use any one match: One of the two records is selected.
- Mark record with an error: The record is not synced and is marked as an error.
- In When no matches are found dropdown menu, select a value.
Note: The selected value determines the action to be performed when no matching records are found. The following are options in the When no matches are found dropdown menu:
- Insert Null Value(s): Null value is inserted in the GSID field of the target object.
- Reject Record: The specific record is not considered and is rejected.
- Click Save.
In the Summary tab, the details of Direct and Derived Mappings are available.
Once you complete the preparation of the Dataset, navigate to the Configure tab to schedule the job execution. For more information on how to Configure the Job, refer to the Configuration of Job or Job Chain Schedule in the Additional Resource section at the end of this article.