Servicenow Connector

Last updated
Save as PDF

Gainsight NXT

IMPORTANT: 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.

This article explains to admins about how to create a connection with ServiceNow, create jobs, configure job or job chains and view job activities.

Note: This document provides general guidance on creating a Connection and setting up Jobs because the business use case of each job is different and needs a unique configuration. For more information on creating any Job, refer to the Configuration of Connectors in the Additional Resources section at the end of this article.

Overview

ServiceNow is a ticketing tool that processes and catalogs customer service requests.

After a ServiceNow connection is established from Gainsight, ServiceNow data can be synced with Gainsight from the following ServiceNow objects:

Account
Contact
Incident
Request
User
User Group
Customer Services
Problem Object
Custom Objects

Once ServiceNow data is synced, you can generate strategic reports on this data, trigger health scores based on support data, and so on.

Benefits of the integration include:

Seeing the full picture of Customer Success with ServiceNow data in Gainsight.
Syncing data like tickets created along with their status and priority, is crucial for understanding the health of the customers in Gainsight.

Note: ServiceNow has 3500+ standard objects, and connectors provide a few objects out of the box. However, if the user wishes to retrieve data from another object, he can raise a support ticket.

Create an OAuth API Endpoint for External Clients

OAuth API endpoint from ServiceNow is used to ensure that Gainsight has access to ServiceNow data. After this configuration is performed in ServiceNow, unique credentials for a specific Gainsight org, OAuth Client ID and OAuth Client Secret are created. These credentials are required to create a ServiceNow connection from Gainsight.

Note: Copy the following URLs (based on your Gainsight org location) and enter in the Redirect URL field of the New OAuth page in ServiceNow:

Europe: https://eu-app.gainsight.com/v1.0/api/accounts/oauth2callback?accountType=SERVICENOW
United States: https://app.gainsight.com/v1.0/api/accounts/oauth2callback?accountType=SERVICENOW
United States 2:https://app.us2.gainsightcloud.com/v1.0/api/accounts/oauth2callback?accountType=SERVICENOW

For more information on how to create an OAuth API Endpoint, refer to the ServiceNow article.

Create a Connection

To create a ServiceNow connection:

Navigate to Administration > Connectors 2.0.
Click Create Connection. Create Connection dialog appears.

From the Connector dropdown, select ServiceNow.

Enter details in the following fields:

Name of the connection: Enter name of the connection.
Subdomain: Enter subdomain of ServiceNow.
OAuth Client Id: Enter the Client Id collected from the ServiceNow OAuth provider and profile page.
OAuth Client Secret: Enter the Client Secret from the ServiceNow OAuth provider and profile page.

Click Authorize to validate the connection. ServiceNow page appears.

Complete authorization by entering the ServiceNow credentials.

For more information on how to create and authorize a connection section in the Connections List Page in the Additional Resources section at the end of this article.

Context Menu

Following options are available from the context menu:

Edit Connection: This option is used to modify the ServiceNow connection details.
Re-Authorize Connection: If the existing connection is revoked, this option is used to re-authorize the ServiceNow connection.
Revoke Authorization: This option is used to disable access to the ServiceNow connection.
Delete Connection: This option is used to delete the ServiceNow connection if the associated Job Chains and data jobs are deleted.

Out of the Box Jobs

Gainsight provides two Out of the Box (OOB) jobs in the Connectors 2.0 > Jobs tab to sync important data such as Cases and Users, which are required for the assessment of data in Gainsight. The following are the two OOB jobs:

Sync ServiceNow Case with Gainsight
Sync ServiceNow Users with Gainsight

Sync ServiceNow Cases with Gainsight

The Cases OOB syncs ServiceNow cases to Gainsight. To get the data on ServiceNow Cases created by each Contact or User in an Organization, the following configurations are provided:

Four datasets are created on the following four Objects:
- Cases
- Account
- Contacts
- User
These datasets are merged and then mapped to the target Gainsight object.
In the Add to Destination, Source fields from the final merged dataset are mapped with the target Gainsight fields through Direct Mappings.
In the Add to Destination, Derived mapping populates the Gainsight GSID of the Users and Contacts who created the Cases in the target object.

Note:

Gainsight strongly recommends you not to uncheck the mapping between Organization ID (from the Tickets Object) and Target Org ID (from the Case Object) in the Add to Destination as it may fail to load data into Company fields for the respective tickets.
If you are doing historical sync for Cases Standard job and the data is very huge i.e. more than 100K records, then kindly reach out to Gainsight support to increase the default job run time to eight hours.

pasted image 0.png

Preparation of Datasets

The following fields are selected in each ServiceNow object, while creating a dataset:

ServiceNow Case fields	ServiceNow Account fields	ServiceNow Contact Fields	ServiceNow User Fields
sys_id	sys_id	sys_id	sys_id
sys_updared_on	sys_updared_on	sys_updared_on	sys_updared_on
Description	Name	email	email
Account Value
Contact Value
Assigned Value
Priority
Short Description
Resolved
Opened
State
Number
Contact

Fields and criteria in Merge

The following are the fields and merge criteria selected in the following objects merge:

Case+Account:
Join Type: Left

Case	Account
sys_id, sys_updated_on, Description, Account Value, Contact Value, Assigned to Value, Priority, Short Description, Resolved, Opened, State, Number, Category	Sys_id, sys_updated_on, Name
Merge Criteria: Case : Account = Account Value : sys_id

Account+Case+Contact:
Join Type: Left

Case+Account	Contact
Account_sys_id, account_sys_updated_on, account_Name, sys_id, sys_updated_on, Description, Account Value, Contact Value, Assigned to Value, Priority, Short description, Resolved, Opened, State, Number, Category	sys_id, sys,updated_on, Email
Merge Criteria: Case+Account : Contact = Contact Value : sys_id

Case+Account+Contact+User:
Join Type: Left

Case+Account+Contact	Users
account_sys_id, account_sys_updated_on, account_Name, sys_id, sys_updated_on, Description, Account Value, Contact Value, Assigned to Value, Priority, Short description, Resolved, Opened, State, Number, Category, contact_sys_id, contact_sys_updated_on, contact_email	sys_id, sys_updated_on, Email
Merge Criteria: Case+Account+Contact : User = Assigned to Value : sys_id

Transform

The following fields are selected in the Transform dataset:

Account+Case+Contact+User+Case Fields:

Account+Case+Contact+User	Case Fields
account_sys_id, account_sys_updated_on, account_Name, sys_id, sys_updated_on, Description, Account Value, Short description, Resolved, Opened, Number, contact_sys_id, contact_sys_updated_on, contact_email, user_sys_id, user_sys,updated_on, user_Email	transformed_state, transformed_priority, transformed_category

Add to Destination Configuration

The following are the details of Direct Mapping and Derived Mapping:

Direct Mappings

The following table shows direct field mappings between the final Merged dataset (Account+Case+Contact+User) and the target Gainsight object (Case):

Final Merged Dataset fields	Gainsight Case Object fields
sys_updaed_on	Modified Date at Source
Description	Case Description
Short description	Case Subject
Resolved	Case Resolution Date
Opened	Created Date at Source
Number	External Id Note: Include in Identifiers check box is selected.
transformed_priority	Case Priority
Typetransformed_state	Case Status
Typetransformed_category	Case Type
account_sys_id	Source Org ID

Derived Mappings

In the Derived Mapping tab, the following table explains the values that are selected for the Derived Mapping configurations:

Fields	Values
Target Field: Company ID (GSID)
Source Field	account_Name
Select the intermediate object	Company
Field in Intermediate Object	Name
When Multiple Matches Occur	Mark record with an error
When No Matches Are found	Insert Null Value(s)
Gainsight Field	Company ID
Target Field: Requester ID (GSID)
Source Field	contact_Email
Select the intermediate object	Person
Field in Intermediate Object	Email
When Multiple Matches Occur	Mark record with an error
When No Matches Are found	Insert Null Value(s)
Gainsight Field	Requester ID
Target Field: Assignee ID (GSID)
Source Field	user_Email
Select the intermediate object	User
Field in Intermediate Object	Email
When Multiple Matches Occur	Mark record with an error
When No Matches Are found	Insert Null Value(s)
Gainsight Field	Assignee ID

For more information on how to configure the data jobs, refer to the Jobs List Page n the Additional Resources section at the end of this article.

Sync ServiceNow Users with Gainsight

This job syncs active ServiceNow users with Gainsight. In the User OOB Job:

ServiceNow User object is selected as the source object in the dataset preparation.
A filter is added to filter the tickets created by the user.
In the Add to Destination, the ServiceNow source fields are mapped with the Gainsight target fields.

Note: In User Sync jobs, only the fields from the User object can be selected as Identifiers. Fields from Avatar objects cannot be selected as Identifiers.

pasted image 0 (1).png

The following are fields and their mapping in the Add to Destination:

ServiceNow User Fields	Target Fields in Gainsight (User)
sys_id	Avatar_<<connection name>> :: ServiceNow User ID
Active	Avatar_<<connection name>> :: Active
Email	Username Note: Include in Identifiers check box is selected.
Name	Name
sys_update_on	NA

For more information on how to configure the data jobs, refer to the Jobs List Page n the Additional Resources section at the end of this article.

Create a Job

Create jobs from the Jobs page to sync data from required source objects like Deals, Accounts, Contacts, Users, and any custom objects with Gainsight. You can create a dataset from one source object, and similarly you can create multiple datasets to create a Job. For more information, refer to the Jobs List Page n the Additional Resources section at the end of this article.

Note:(Optional) Create multiple data jobs, as required. If the data jobs in a connection are dependent on each other, create a Job chain and configure the schedule to the Job Chain. For more information, refer to the Job Chain Page in the Additional Resources section at the end of this article.

Merge Datasets

Merge two datasets together and create an output dataset. For example, merge Deals and Account objects to collect the business deals stored for each Account with their details and work on them to provide a better customer experience. For more information on Merge, refer to the Jobs List Page n the Additional Resources section at the end of this article.

Transform Data

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.

For more information on Transform Data, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Add Destination

Once the final output dataset is prepared, add a destination to the output dataset to sync data from the source to the target Gainsight object. For more information on Add Destination, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Direct Mapping

In the Direct Mapping, map the 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, per field mappings. For more information on Direct Mapping, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Note: Gainsight doesn’t support fetching all records from a multi-picklist data type field. Only the first value from an array or multi-picklist data type will be imported into Gainsight if you map the field using direct mapping

Derived Mapping

This is optional and you must configure the derived mappings only if you want to populate values into the target fields of data type GSID. GSID values are populated from the same or another object through lookup. In this stage, you can create Lookup mapping in a data sync job. Create a lookup to the same object or another standard object and match up to six columns. Once the required matching is performed, fetch Gainsight IDs (GSIDs) from the lookup object into GSID data type fields. For more information on the derived mappings, refer to the Jobs List Page in the Additional Resources section at the end of this article.

Note:

To use Derived Mappings, target object must have at least one field of data type GSID.
Cases Sync Job will ingest all records even if the organization is not present against an case. To exclude these records, kindly apply a filter where organization are not null .

Configure Job or Job Chain Schedule

Configure the schedule of a data job or Job chain as required. For more information, refer to the Configure Job or Job Chain Schedule in the Additional Resources section at the end of this article.

If you create a Job Chain by adding multiple Jobs in a sequence and add a schedule to the Job Chain, the schedule of the individual jobs is not honored.

Job Activities

View the Execution and Update Activities of all the data jobs in the Activity page. You can also download the logs of the job execution from this page to help troubleshooting the configuration issues. For more information, refer to the Activity Page in the Additional Resources section at the end of this article.

Additional Resources

For more information about Connectors, refer to the following articles: