Connecting to ServiceNow (extractor)

The Celonis ServiceNow extractor integrates the Celonis Platform with your ServiceNow tenants. It supports the following basic features:

Prerequisites

This section details important prerequisites or prerequisite knowledge for using this extractor.

ServiceNow authentication methods

The ServiceNow extractor allows you to authenticate using either:

Stored Credentials: Connect via basic authentication with the username and password of a ServiceNow user account.
Note
Specific permissions are required for the ServiceNow user account. For more information see Configuring ServiceNow user permissions (Stored Credentials).
OAuth (Recommended): Connect via a ServiceNow application endpoint. For the application endpoint, use the following URL:
```
https://auth.redirect.celonis.cloud/service-now_redirect
```
When using the OAuth method, you will need the client ID and client secret of the ServiceNow application.
Note
In Configuring the ServiceNow extractor, you will find a video that includes the steps in this process. For instructions, refer to the ServiceNow documentation.

Allowlisting Celonis Platform IPs and domains

If your ServiceNow instance is only reachable within a certain IP range, you need to allowlist the outbound IPs of the Celonis Platform, otherwise data cannot be extracted. The IPs of the Celonis Platform are different depending on the cluster (eu-1 or us-1). For more information, see: Allowlisting Celonis domain names, IP addresses, and third-party domains.

Configuring ServiceNow user permissions (Stored Credentials)

To extract data from your ServiceNow tenant using basic authentication (Stored Credentials), you need access to a user with the following permissions:

Tip

These steps are not needed if your are using OAuth credentials.

Roles: soap_query and snc_platform_rest_api_access
Table access: Access to the table sys_db_object and all tables you want to extract.
View access: Access to the table ‘sys_db_view’ and all views you want to extract.
Endpoint access: Access the following endpoint for each table, which is then used to derive the schema:
```
https://<instance>/<table>?SCHEMA
```
For example:
```
https://<instance>/incident.do?SCHEMA
```

To configure this user, we recommend the following steps:

Note

For the latest ServiceNow documentation and the steps involved, see: ServiceNow - Product Documentation.

In Configuring the ServiceNow extractor, you will find a video that includes an overview of the steps in this process.

Create a new role: In order to assign the correct access right to the user used for the Celonis extraction, we recommend creating a new role in the user administration section.
Create a new user and assign the required roles: Assign the roles soap_query snc_platform_rest_api_access, and the role you created in step 1.
Elevate privileges of your user: To modify access control for the newly created Celonis role, you need to elevate your privileges. You can do this by selecting Elevate Roles.
With the elevated role, you can then open access control lists (ACL).
Create two ACL:
- ACL One:
  - Operation: read
  - Active: true
  - Name: Table [sys_db_object]
  - Field (Column): *
  - Required roles: the role created in step 1.
- ACL Two:
  - Operation: read
  - Active: true
  - Name: Table [sys_db_object]
  - Field (Column): --None--
  - Required roles: the role created in step 1.
Settings that take an asterisk (*) are dependent on their ServiceNow permission settings. If you experience problems, change * to None.
Allow access to all tables: You should now allow access to all tables you want to extract. With the elevated role you can open access control lists (ACL). Here you need to create a new ACL with the following attributes:
- Operation: read
- Active: true
- Name: the name of the table
- Field (Column): all fields selected
- Required roles: the role created in step 1.
Repeat the previous step for all tables you want to extract.

Configuring the ServiceNow extractor

This section describes the basic setup of configuring the ServiceNow extractor. For an overview of this process, view:

Tip

This video includes an overview of the steps to set up both ServiceNow authentication methods.

To configure the extractor:

From your data pool diagram, Select Data Connections.
Select Add Data Connection and select Connect to Data Source.
Select Cloud - ServiceNow.
Configure the following connection details:
- Name: An internal reference for this data connection.
- Authentication method: Choose between Stored Credentials (username and password a Service now user) or OAuth.
  Note
  For more information, see ServiceNow authentication methods.
- Tenant or URL: The realm of your ServiceNow instance. The realm can be found by looking at the system URL. For example, in the following URL mycompany is the realm:
```
https://mycompany.service-now.com
```
Select Test Connection and correct any issues highlighted.
Select Save.
The connection between your ServiceNow tenant and the Celonis Platform is established. You can manage this connection at any time by selecting options:

ServiceNow data extraction best practices

When configuring your ServiceNow extraction tasks, we recommend the following the :

Filtering ServiceNow data

When executing your ServiceNow extractions, you can filter the data you extract. However you can't use all combinations of AND / OR filters, so we recommend the following:

Option 1 AND Option 2, for example:

sys_created_on > '2011-09-14' AND sys_updated_by = 'system'

Option 1 OR Option 2, for example:

sys_created_on > '2011-09-14' OR sys_updated_by = 'system'

(Option 1 AND Option 2) AND Option 3, for example:

(sys_created_on > '2011-09-14' AND sys_updated_by = 'system') AND sys_updated_on > '2018-12-05'(A AND B) AND C, example:

(Option 1 OR Option 2) OR Option 3, for example:

(sys_created_on > '2011-09-14' OR sys_updated_by = 'system') OR sys_updated_on > '2018-12-05'

Option 1 OR (Option 2 AND Option 3), for example:

sys_updated_by = 'system' OR (sys_created_on > '2011-09-14' AND sys_updated_on > '2018-12-05')

Filters are case-sensitive

When filtering in ServiceNow, the filters are case-sensitive. This means that FIELDNAME and fieldname are handled as separate filter queries.

Extract from read replica

You can enable Extract from read replica on a table level for your ServiceNow extractions. In ServiceNow, a read replica is a read-only copy of the primary database used to improve performance and scalability. It allows high-volume data reads, like analytics, reporting, or integrations, without impacting the performance of the main (read/write) transactional database.

Enabling this option for your ServiceNow extractions uses the parameter sysparm_query_category=reporting in all extraction requests. This will direct the query to the reporting read replica of ServiceNow.

To enable this for your ServiceNow extractions, select Data Jobs - Table Configuration and select Extract from read replica:

A screenshot showing how to enable the extraction from read replica of ServiceNow.

Extracting the sys_audit table

To increase the performance and limit the source system impact when extracting the sys_audit table:

The sys_audit table should not be extracted as a primary table, only as a dependent table. The extractor automatically adds the sys_audit tables as a dependent table for most objects. This means extractions are limited to the retrieved sys_is fields (which are unique), and lead to a better performance.
Applied filters should be limited to indexed columns only.
Additional filtering on sys_created_on or sys_updated_on can also improve performance.

Using Order-by Parameter in Request

When configuring your ServiceNow extractions, you can enable Use Order-by Parameter in Request for all API requests at the table level.

Enabling this option ensures data integrity by preventing missing records and duplicates. However, it will also lead to a longer extraction time and an increased load on the source system. To help minimize this impact, we recommend that you apply partitioning to reduce both the peak impact and the duration of the system being occupied or increase the batch size, which increases the peak impact but decreases the duration of the system being occupied.