> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/software-engineering-insights/use-software-engineering-insights/setup-sei/configure-integrations/beta-integrations/servicenow/sei-servicenow.md).

# Connect with ServiceNow

{% hint style="info" %}
The SEI ServiceNow integration is in beta and is accessible behind the Feature Flag `<SEI_SERVICENOW>`. Contact [Harness Support](/software-engineering-insights/troubleshooting-and-resources/sei-support.md) to enable this feature.
{% endhint %}

ServiceNow is used to set up systems that define, manage, automate and structure IT services for companies. You can use the SEI ServiceNow integration to integrate Harness SEI with [ServiceNow Cloud](#connect-with-servicenow-cloud) and ServiceNow On-Prem accounts.

The SEI ServiceNow integration allows you to track, manage, and analyze incidents, and change requests in real-time, leading to improved efficiency and enhanced productivity.

{% embed url="<https://www.youtube.com/embed/wFWHAAIj3_o>" %}

### Requirements <a href="#requirements" id="requirements"></a>

To connect ServiceNow with Harness SEI, you can choose between two authentication methods:

* **Using OAuth:** Use token-based authentication with OAuth credentials.
* **Using Username and Password:** Use the service account credentials for direct authentication.

Ensure the service account has the required credentials and permissions to successfully configure the integration.

| Role                         | ServiceNow API                                                                                                                                                                                                                                                                                                                                                   | Description                                                                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`itil`**                   | <p><code>/api/now/table/incident</code><br><code>/api/now/table/change\_request</code><br><code>/api/now/table/sys\_user/\<sys\_id></code><br><code>/api/now/table/sys\_user?sysparm\_limit=1\&sysparm\_query=user\_name=\<USER\_NAME></code><br><code>/api/now/table/cmdb\_ci/\<sys\_id></code><br><code>/api/now/table/cmdb\_ci\_service/\<sys\_id></code></p> | Provides access to IT Service Management (ITSM) data such as incidents, change requests, users, and CMDB records.                                                  |
| **`personalize_choices`**    | `/api/now/table/sys_choice`                                                                                                                                                                                                                                                                                                                                      | Fetches possible field values (e.g., state, severity). Because Incident/Change Request APIs return codes, this API maps those codes to labels.                     |
| **`personalize_dictionary`** | `/api/now/table/sys_dictionary`                                                                                                                                                                                                                                                                                                                                  | Fetches field metadata, including custom fields.                                                                                                                   |
| **`oauth_admin`**            | N/A                                                                                                                                                                                                                                                                                                                                                              | Required only if using the OAuth flow for creating integrations. Used solely to register the app in ServiceNow; the integration does not call APIs with this role. |
| **`user_admin`**             | `/api/now/table/sys_user/<sys_id>`                                                                                                                                                                                                                                                                                                                               | Not generally required. Only needed to fetch detailed user information (e.g., user department).                                                                    |

{% tabs %}
{% tab title="Using OAuth" %}

#### OAuth Credentials <a href="#oauth-credentials" id="oauth-credentials"></a>

To configure the integration using OAuth-based authentication, you'll need to generate the following credentials in your ServiceNow instance:

* [ServiceNow Client ID](#create-a-client-id-and-client-secret-in-servicenow)
* [ServiceNow Client Secret](#create-a-client-id-and-client-secret-in-servicenow)

These credentials are essential for secure, token-based authentication between your application and the ServiceNow platform. To generate the credentials, go to [Create a Client ID and Client Secret in ServiceNow](#create-a-client-id-and-client-secret-in-servicenow).

#### Required permissions <a href="#required-permissions" id="required-permissions"></a>

When configuring the ServiceNow integration, ensure the service account has the following roles:

* **itil**: Provides access to IT Service Management (ITSM) functionalities.
* **personalize\_choices**: Enables customization of choice lists.
* **personalize\_dictionary**: Allows modification of dictionary entries.
* **oauth\_admin** (required only for app creation)

To fetch data for all users within the ServiceNow instance, the following roles are required:

* **user**: Basic role assigned to all ServiceNow users.
* **user\_admin**: Provides administrative capabilities over user accounts (only required if extended user attributes must be fetched).
  {% endtab %}

{% tab title="Using Username & Password" %}
When configuring the ServiceNow integration, ensure the service account has the following roles:

* **itil:** Provides access to IT Service Management (ITSM) functionalities.
* **personalize\_choices:** Enables customization of choice lists.
* **personalize\_dictionary:** Allows modification of dictionary entries.

To fetch data for all users within the ServiceNow instance, the following roles are required:

* **user:** Basic role assigned to all ServiceNow users.
* **user\_admin:** Provides administrative capabilities over user accounts.
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
If you have enabled an allowlist in your ServiceNow account, certain Harness IP addresses must be added to it in order to allow communication between the Harness Platform and ServiceNow. If the necessary IPs are not whitelisted, the integration may fail to authenticate or sync data properly.

To ensure your integration can work correctly, refer to the list of [Harness Platform IPs](/harness-ai/use-harness-platform/references/allowlist-harness-domains-and-ips.md) that may need to be whitelisted in your firewall.
{% endhint %}

#### Create a Client ID and Client Secret in ServiceNow <a href="#create-a-client-id-and-client-secret-in-servicenow" id="create-a-client-id-and-client-secret-in-servicenow"></a>

To create a Client ID and Client Secret in ServiceNow, follow these steps:

{% tabs %}
{% tab title="Interactive Guide" %}

{% endtab %}

{% tab title="Step-by-step" %}

1. Log in to the **ServiceNow** platform with an admin account.
2. Navigate to **System OAuth > Application Registry**.
3. Click the **New** button to create a new application registry.
4. Select **Create an OAuth API endpoint for external clients**.
5. Enter a descriptive name for the application registry, e.g., "SEI Connect".
6. Locate the **Redirect URL** in the **SEI ServiceNow integration** configuration settings. Click the lock button and paste the Redirect URL copied from SEI.
7. In the **Auth Scopes** section, add the table\_read scope.
8. Click **Submit** to create the application registry.
9. After the successful creation of the application registry, open the newly created application.
10. Click the lock button to display the **Client Secret**.
11. Copy and save the **Client ID** and **Client Secret**, as they will be required during the integration configuration on the SEI platform.

    <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The Client ID and Client Secret are sensitive credentials and should be handled with care.</p></div>

{% endtab %}
{% endtabs %}

### Connect with ServiceNow Cloud <a href="#connect-with-servicenow-cloud" id="connect-with-servicenow-cloud"></a>

#### Step 1: Select the integration <a href="#step-1-select-the-integration" id="step-1-select-the-integration"></a>

1. In your **Harness project**, go to the **SEI module**, and select **Account**.
2. Select **Integrations** under **Integration and Data Settings**.
3. Select **Available Integrations**, locate the **ServiceNow integration** under the **Others** **integration** tab and select **Install**.

#### Step 2: Choose the Type of ServiceNow setup <a href="#step-2-choose-the-type-of-servicenow-setup" id="step-2-choose-the-type-of-servicenow-setup"></a>

Select the type of ServiceNow setup as ServiceNow Cloud.

#### Step 3: Configure the integration <a href="#step-3-configure-the-integration" id="step-3-configure-the-integration"></a>

The ServiceNow integration can set up the authentication either by using **Username and Password** or by using **OAuth** as the mode of authentication.

{% tabs %}
{% tab title="Username/Password" %}

1. Choose the authentication mode as **Using Username and Password**.
2. Enter a name for this ServiceNow integration. You can add **Description** and **Tags** (Optional).
3. Enter the base URL you use to access ServiceNow. For example: `https://example.service-now.com`.
4. Add the **Username** and **Password**, of the **ServiceNow Service Account**.
5. Set the timezone to UTC by default. If you use a different timezone, specify it here.

**Advanced Configurations (Optional)**

If you want to filter the incidents or change requests to be ingested, create a query in your ServiceNow account:

1. In the ServiceNow app define a filter query for incidents or change requests.
2. Right-click the query in ServiceNow to copy it.
3. Paste the copied query into the integration configuration settings to apply the filter.
4. Click **Next: Validate Connection** to establish a connection with the provided URL, perform authentication, and run the preflight checks. If everything is successful, you will see a message confirming a successful connection.
5. Click on the **Done** button and the integration will be successfully saved.
   {% endtab %}

{% tab title="OAuth" %}

1. Choose the **Authentication Method** as **Use ServiceNow OAuth**.
2. Enter a name for this ServiceNow integration. You can add **Description** and **Tags** (Optional).
3. Enter the base URL you use to access ServiceNow. For example: `https://example.service-now.com`.
4. Add the **ServiceNow Client ID** and **Client Secret** that you generated after creating the application registry in ServiceNow
5. Set the timezone to UTC by default. If you use a different timezone, specify it here.
6. Click on the **Connect ServiceNow** button. This will redirect you to the ServiceNow application.
7. Allow the application and grant the required permissions, and it will redirect you back to SEI.
8. Click **Next: Validate Connection**. It will establish a connection with the provided URL, perform authentication, and then run the preflight checks. If everything is successful, you will see a message confirming a successful connection.
9. Click on the **Done** button and the integration will be successfully saved.
   {% endtab %}
   {% endtabs %}

#### ServiceNow field mapping and display values <a href="#servicenow-field-mapping-and-display-values" id="servicenow-field-mapping-and-display-values"></a>

ServiceNow [display value fields](https://www.servicenow.com/docs/r/platform-administration/ai-platform-administration/c_DisplayValues.html) (`dv_*`) are exposed differently in SEI depending on whether the underlying field is a standard ServiceNow field or a custom field.

<details>

<summary>Custom Fields</summary>

Custom ServiceNow fields (`u_*`) are available by clicking **Add custom fields** and are mapped using their display labels.

For example:

| ServiceNow field         | SEI field         |
| ------------------------ | ----------------- |
| `dv_u_reason_for_change` | Reason for Change |
| `dv_u_subcategory`       | Subcategory       |
| `dv_u_line_of_business`  | Line of Business  |

</details>

<details>

<summary>Standard Fields</summary>

Standard ServiceNow fields do not appear in the **Add custom fields** list because they are already available as built-in workflow filters.

For example:

| ServiceNow field | SEI field |
| ---------------- | --------- |
| `dv_state`       | Status    |
| `dv_category`    | Category  |

To filter on these fields, select **Status** or **Category** directly from the workflow filter dropdown instead of adding them as custom fields.

</details>

#### Recreate ServiceNow queries <a href="#recreate-servicenow-queries" id="recreate-servicenow-queries"></a>

When recreating a ServiceNow query in SEI:

* Use the display label shown in SEI rather than the raw `dv_*` field name.
* For custom fields (`dv_u_*`), add the field by clicking **Add custom fields** first.
* For standard fields such as `dv_state` and `dv_category`, use the built-in filter fields already available in workflow profiles.

### ServiceNow On-Prem <a href="#servicenow-on-prem" id="servicenow-on-prem"></a>

#### Step 1: Select the integration <a href="#step-1-select-the-integration" id="step-1-select-the-integration"></a>

1. In your **Harness project**, go to the **SEI module**, and select **Account**.
2. Select **Integrations** under **Integration and Data Settings**.
3. Select **Available Integrations**, locate the **ServiceNow integration** under the **Others** **integration** tab, and select **Install**.

#### Step 2: Choose the Type of ServiceNow setup <a href="#step-2-choose-the-type-of-servicenow-setup" id="step-2-choose-the-type-of-servicenow-setup"></a>

Select the type of ServiceNow setup as **ServiceNow On-Prem**.

#### Step 3: Configure the integration <a href="#step-3-configure-the-integration" id="step-3-configure-the-integration"></a>

The ServiceNow on-prem integration can set up the authentication only using the ServiceNow account's Username and Password.

1. Add the **Name** for the integration, which is mandatory. You can add **Description** and **Tags** (Optional).
2. Add the **URL** of your **ServiceNow application instance**, for example, "`https://xyz.service-now.com`". Make sure it's a valid URL.
3. Add the **Username** and **Password** for your **ServiceNow account**.
4. Set the timezone to UTC by default. If you use a different timezone, specify it here.

**Advanced Configurations (Optional)**

If you want to filter the incidents or change requests to be ingested, create a query in your ServiceNow account:

1. In the ServiceNow app, define a filter query for incidents or change requests.
2. Right-click the query in ServiceNow to copy it.
3. Paste the copied query into the integration configuration settings to apply the filter.
4. Click on **Download YAML File** to download the `satellite.yml` file.
5. Click on the **Done** button and the integration will be successfully saved. Once you have downloaded the `satellite.yml` file, update it by following the instructions [here](/software-engineering-insights/use-software-engineering-insights/setup-sei/sei-ingestion-satellite/satellite-overview.md).

Here’s a sample `satellite.yml` file:

```yaml
satellite:
  tenant: <ACCOUNT_NAME>
  api_key: <SEI_API_KEY>
  url: <SEI_ENV_URL>
integrations:
  - id: <INTEGRATION_ID>
    url: <SERVICENOW_URL>
    username: <SERVICENOW_USERNAME>
    application: servicenow
    api_key: <SERVICENOW_PASSWORD>
    metadata:
      change_request_query: <CHANGE_REQUEST_QUERY>
      incident_query: '<INCIDENT_QUERY'
      timezone: <TIMEZONE> # Default value is considered as UTC

```

### ServiceNow Use Cases <a href="#servicenow-use-cases" id="servicenow-use-cases"></a>

The ServiceNow integration primarily is used for measuring the incident recovery time using the DORA Mean Time to Restore (MTTR) widget.

For detailed instructions on setting up and configuring the DORA profile to effectively measure MTTR using the ServiceNow integration, see [Measure incident recovery time](/software-engineering-insights/use-software-engineering-insights/get-started/early-access/metrics-reports/mttr-incident-recovery.md).

### See also <a href="#see-also" id="see-also"></a>

* [Ingested data](/software-engineering-insights/use-software-engineering-insights/setup-sei/configure-integrations/beta-integrations/servicenow/sei-servicenow-datasheet.md)
* [Supported integrations](/software-engineering-insights/use-software-engineering-insights/setup-sei/configure-integrations/sei-integrations-overview.md)