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 Microsoft Dynamics CRM connector articles. Gainsight recommends you to first refer 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 the five stages in it.
A Data sync job fetches data from an authorized Dynamics CRM 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:
To create a new job, click the Create job icon. The New Job window is displayed.
Sync 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 Dynamics 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.
- Click SAVE.
Data Source and Field Mappings Stage
In this stage, you can select the source entities from Dynamics CRM and target objects from Gainsight, and map the source fields from Dynamics CRM entity to their corresponding fields in Gainsight. In this stage, you can configure the following fields:
- Select Dynamics Source entity: You can select Standard and Custom entities from Dynamics CRM in this field. All the fields of the selected object and lookup fields from this object can be included in the field mappings stage. You cannot change the source entity 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.
- Field 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 Dynamics CRM object to target fields of Gainsight, based on the field mappings configured by you.
To add field mappings:
- From the Select Dynamics 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.
- Perform field mappings between the source and target fields.
While syncing Person records, Upsert keys for the mapping between the Dynamics Contact object and the Gainsight Person object are determined by the Person Resolution Key configuration. Fields selected in the Person Resolution Key configuration are automatically selected as Upsert Keys while syncing people from the Contact to the Person object. There can be one or multiple upsert keys used for the identification of people in Gainsight and you cannot edit them. For more information on the Person Resolution Key configuration, refer to the People Management article listed in the Additional Resources section.
Upsert keys must be mapped in the Field Mappings section. If they are not mapped, data sync job fails.
In the following image (after Step 9), values from the Email field of Dynamics CRM is synced into the Email field in Gainsight. Similarly, data from other source fields are synced into Gainsight fields. The Email field in Dynamics CRM helps in identifying unique Dynamics CRM records and matches with Gainsight Person records. Similarly, Full Name, First Name, Last Name, and Uniqueidentifier fields can be mapped to Name, First Name, Last Name, and External ID fields in Gainsight, respectively.
- 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 can create 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 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 Dynamics CRM 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.
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 Dynamics CRM source object can be used to filter data being synced into Gainsight NXT.
To add filters:
- Click + ADD FILTER.
- Select a field from the Dynamics CRM 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 demand. When data is synced for the first time, all the data starting from the beginning of time (1970) till date, is imported from Gainsight ; This applies to Import Now and Schedule options, only when executed for the first time.
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 NXT. For all subsequent job executions, only the newly added data is inserted; if any data which was previously inserted into Gainsight NXT from the Dynamics CRM is modified, the 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, 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 Now: 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 From Date: If you select this option, the job is executed and data updated during the specified dates in Dynamics CRM, is added to Gainsight. You can select date range in this option to import new and modified Dynamics CRM records in the specified date range.
Click IMPORT to start the data import process.
Gainsight recommends you to first run the job immediately using On demand execution, after configuration is made. You can then schedule the execution at regular intervals.
You can navigate to the LOGS tab to see the log history of all the data sync jobs. 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 and click REFRESH.
In the above image, filter is applied to display logs only for the Person Sync.
Gainsight NXT 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 symbol. 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 symbol. 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 Dynamics 365 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 Dynamics 365 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.