IMPORTANT NOTE: Gainsight is upgrading Connectors 2.0 with Horizon Experience. This article applies to tenants which are yet to be upgraded to the Horizon Experience of Connectors 2.0. If you are using Connectors 2.0 with Horizon Experience, you can find the documentation here.
This article is the fourth in a series of Salesforce connector articles. Gainsight recommends you refer to the initial articles and then proceed with this article.
This article explains the process of creating and configuring Data sync jobs. After reading this article, you can create a Data Sync job and configure all five stages of it.
A Data sync job fetches data from an authorized Salesforce org and ingests it into Gainsight NXT. A Data sync job has five stages and you must configure these stages, as required. The five stages of a Data Sync job are:
- Job Configuration Stage
- Data Source and Field Mappings Stage
- Derived Mappings Stage
- Sync Filters Stage
- Schedule Stage
To create a new job, click the Create job icon. The New Job window is displayed.
Job Configuration Stage
This stage consists of the basic settings to be configured in a Data Sync job. In this stage, you can configure the following fields:
- Connection Name: The connection for which this job is created. This field is automatically populated with the name of the connection. You cannot edit this field.
- Connector: This field displays the name of the connector. This field is always set to Salesforce in all the jobs.
- Job Name: This field holds the name of the job, entered by you.
- Dependent Jobs: If any other job must be completed before the current job, you must add that job here. The dependent job is executed first and then the current job. You can add only one dependent job.
- Notification Details: This field notifies users about the success or failure of the current job. In the first text box, enter the email address of the recipient(s) who should be notified when this job is executed successfully. In the second text box, enter the email address of the recipient(s) who should be notified when this job fails to execute. You can enter multiple email addresses separated by a comma.
Data Source and Field Mappings Stage
In this stage, you can select the source object from Salesforce and target object from Gainsight. You can map the source fields from Salesforce object to their corresponding fields in Gainsight. In this stage, you can configure the following fields:
- Select Salesforce Source Object: You can select Standard and Custom objects from SFDC in this field. All the fields of the selected object and lookup fields from this object can be included in the field mappings and Sync Filters stage. You cannot change the source object once you proceed to the field mappings.
- Select Target Gainsight Object: You can only see Standard and Custom objects in this field. You cannot change the source object once you proceed to the field mappings.
Salesforce Data to Gainsight Data Mappings: You should map fields from the source object to the target object in the field mappings stage. Data is synced from source fields of Salesforce object to target fields of Gainsight, based on the field mappings configured by you.
To add field mappings:
- From the Select Salesforce Source Object field, select the source object.
- From the Select Target Gainsight Object field, select the target object.
- Click PROCEED TO MAPPING. Field mappings section appears.
- Click ADD to add the field mappings.
- In the Source Field column, select the field from which data must be imported.
- In the Target Field column select the field to which data must be imported.
- Click ADD, to add more field mappings.
- Select the Upsert key check box for at least one of the fields. Upsert key helps to identify a unique record from Salesforce to Gainsight while syncing data into the remaining mapped fields. Any Salesforce field which has unique values can be used as an Upert key.
In the following image (after Step 9), the values from the Account ID field of Salesforce are synced into the SFDC Account ID field in Gainsight. Similarly, data from other source fields are synced into Gainsight fields. The Account ID field in Salesforce helps in identifying unique Salesforce records and syncs them to the SFDC Account ID field in Gainsight.
- Click SAVE MAPPINGS. Clicking this button enables the Derived Mappings stage. You can even proceed to the Sync Filters or Schedule stage directly, if required.
Derived Mappings Stage
This stage is optional and you must configure it only if any of the target fields in the above mappings has a field with GSID data type. In this stage, you will create a Lookup mapping in a data sync job. You can have a lookup to the same object or another standard object and match up to six columns. Once the required matching is performed, you can fetch Gainsight IDs (GSIDs) from the lookup object into GSID data type fields. The main purpose is to populate GSIDs of the records from the same or another object. Derived Mappings are also known as Data Import Lookup.
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 another record to the target field. To learn more about Derived Mappings, refer to the Data Import Lookup article.
IMPORTANT: To use Derived Mappings, your Target Object selected in the field mappings stage must have at least one field with GSID Data Type.
To add Derived Mappings:
- Click ADD. The Data import lookup configuration window is displayed.
- Lookup Type: Select either Direct or Self Lookup.
- Direct: In Direct Lookup, you can have a lookup to another Gainsight Standard Object and fetch GSIDs of the records from the lookup object.
- Self: In Self Lookup, you have a lookup to the same standard object and fetch GSIDs of another record to the target field.
- From: Select the source object from which the GSID must be fetched. This field is automatically set to the same object in Self lookup, since lookup is on the same object itself.
- To Target Field: Select the target field into which GSID must be loaded. You can only view fields with GSID data type in this field.
- Match by: Select the two fields based on which records must be matched. The first field is from the Salesforce source object and the second field is from the lookup object.
- (Optional) Click ADD ANOTHER, to add additional mappings.
- Select a value in the When multiple matches occur field. The selected value determines what action must be performed when multiple records are found for the matching criteria.
- Use any one match: If this option is selected, one of the two records is selected.
- Mark record with an error: If this option is selected, the record is marked as an error in the target object and it will be synced to the target object.
Select a value in the When no matches are found field. The selected value determines the action to be performed when no matching records are found.
- Insert null value(s): If this option is selected, null value is inserted in the GSID field of the target object.
- Reject record: The specific record is not considered and is rejected.
- Click APPLY.
Sync Filters Stage
In this stage, you can add filters to refine the list of records that should be synced. Any standard, custom, or lookup fields in the Salesforce source object can be used to filter data being synced into Gainsight NXT.
To add filters:
- Click + ADD FILTER.
- Select a field from the Salesforce object, in the select a value section.
- Select the required operator.
- Select the matching criteria.
- Click SAVE FILTER.
- (Optional) Click + ADD FILTER, to add more filters.
When you add multiple filters, the AND operation is applied by default. However, you can change this to the OR operation.
Schedule Jobs Stage
In this stage, you can schedule your data sync job to be executed later, or execute a Data sync Job on the fly. When data is synced for the first time, all the data starting from the beginning of time (1970) till date, is imported from Gainsight.
In this sub section, you can schedule the execution of the job as required. When the job is executed for the first time, all the values are inserted into Gainsight. For all subsequent job executions, only the newly added data is inserted; if any data which was previously inserted into Gainsight from Salesforce, is modified in Salesforce, corresponding data in Gainsight NXT is updated.
To schedule the job:
- Select the Enable Schedule check box.
- Select one of the following options:
Daily: The data is synced on a daily basis.
- Select Once to run the job once everyday. Choose the time at which the job must be executed, in the Select a Time section.
- Select Repeat to repeat the execution of the job. Select the other options as listed below:
- You can select the time frame between which the execution must be performed, in the From and To fields.
- You can select the frequency at which the execution must be performed in the set time frame, in the For every field.
For example, if you select from 10 am to 2 pm time frame and select every hour frequency, the job is executed five times at 10,11,12,1 and 2.
- Weekly: Select the days of the week on which the job must be executed.
Select the required time at which the job must be executed, in the Select a Time field.
- Monthly: Select the date on which the job must be executed, in the Monthly on day field. Select the required time at which the job must be executed, in the Select a Time field.
- Click SAVE.
On Demand Execution
In this sub section, the following options enable you to execute the job immediately:
- Import data that were modified since the last sync date and time: If you select this option, job execution is started immediately. In the first execution, all the data from 1970 till date is executed. For subsequent imports, the last import date is considered to be the start date and current date is considered to be the end date.
For example, if you imported data for the first time on 1st Feb 2018, data is imported from 1st Jan 1970 to 1st Feb 2018. If you execute the job again on 5th Feb 2018, new records and modified records between 1st Feb and up to 5th Feb are imported.
- Import data that were modified within a specific date range: If you select this option, the job is executed and data updated during the specified dates in Salesforce, is added to Gainsight. You can select date range in this option to import new and modified Salesforce records in the specified date range.
- Import All Data: If you select this option, the job is executed and data is updated for all the data in Gainsight from Salesforce.
Click IMPORT to start the data import process.
Note: You can also sync data from DATA JOBS page, click Import icon.
Select any one option and click IMPORT.
You can navigate to the LOGS tab to see the log history of all the data sync jobs. By default, this page displays the logs for all the Connectors. You can filter this page to display logs only for a specific job from a specific connector. To filter the logs, select the required job from the Show drop-down menu.
In the above image, filter is applied to display logs only for the Company Sync job of Connect to SFDC connection.
Gainsight maintains two types of Logs for every Data Sync job:
- Audit logs: An audit log is recorded when an activity is performed on a job. The various activities could be Create, Edit, delete, and so on. Audit logs are represented by AL symbols. The various fields displayed in this log are:
- Attribute: The stage of the job which was modified. For example, if you modified a mapping, this field displays Mapping.
- Sub-Attribute: The element modified in an attribute..
- Action: The activity performed on the job. Possible values can be Create, Edit, Delete.
- Old Value: The value which was modified.
- New Value:The current value in the modified field.
- Additional Info: Additional information about the activity.
Execution logs: An Execution log is created when a job is executed. Execution logs are represented by EL symbols. An EL symbol in green indicates a successful execution.
The various details displayed by Audit logs are:
- Date: The date of job execution.
- Calltype: Always displays APPLICATION_DATA for SFDC connector.
- pStatus: The status of the job. Possible values could be Success, Failure, in progress.
- # Success: Number of records which were synced successfully.
- # Failure: Number of records which failed to sync.
The LOGS page displays the logs only for the Data Sync jobs. To view the Connection logs, you can navigate to the Salesforce Connector logs page. The various columns in Connection logs are:
- Connection Name: The name of the connection.
- User: The user who created the connection.
- Action: The action performed on the connection.
- Modified on: The date on which the connection was last modified.
- Attribute: The element modified in the connection.
- Old Value: The value which was replaced after modification.
- New Value: The new value which replaced the old value.