> 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/ai-dlc-insights/use-ai-dlc-insights/setup/integrations/servicenow/index.md).

# ServiceNow Integration

The ServiceNow integration enables AI DLC Insights to ingest incident and change management (ITSM) data from ServiceNow. This data can be used to track operational performance and correlate incidents and changes with engineering metrics in SEI dashboards.

AI DLC Insights supports the following authentication methods:

* **API key authentication** using a ServiceNow API key with permissions to read ServiceNow data
* **Username/password authentication** using ServiceNow account credentials
* **OAuth authentication** using a ServiceNow client ID and client secret

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you can configure the ServiceNow integration, ensure you have the following requirements:

* A ServiceNow instance URL
* Admin access to your ServiceNow account
* A ServiceNow service account with the required permissions

Ensure the ServiceNow service account has the following roles:

| Role                     | Description                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `itil`                   | Provides access to IT Service Management (ITSM) data such as incidents, change requests, users, and CMDB records.     |
| `personalize_choices`    | Allows SEI to retrieve choice field labels such as incident state and severity values.                                |
| `personalize_dictionary` | Allows SEI to retrieve field metadata and custom field definitions.                                                   |
| `oauth_admin`            | Required only when configuring OAuth applications in ServiceNow.                                                      |
| `user`                   | Required to ingest user-related metadata for all users in the ServiceNow instance. Assign together with `user_admin`. |
| `user_admin`             | Optional. Required only if you want to ingest extended user attributes.                                               |

To ingest user-related metadata for all users in the ServiceNow instance, ensure that `user` and `user_admin` roles are also assigned.

{% hint style="info" %}
**HARNESS IP ADDRESSES**

If your ServiceNow instance uses IP allowlisting, ensure the required Harness IP addresses are added to the allowlist.

Go to [Harness Platform IPs](/harness-ai/use-harness-platform/references/allowlist-harness-domains-and-ips.md) to add the required Harness IP addresses to your allowlist.
{% endhint %}

**Configure OAuth in ServiceNow**

To use OAuth authentication, create an OAuth application in ServiceNow.

1. Log in to ServiceNow with an administrator account.
2. Navigate to **System OAuth > Application Registry**.
3. Click **New**.
4. Select **Create an OAuth API endpoint for external clients**.
5. Enter a name for the application.
6. Add the redirect URL generated during the ServiceNow integration setup.
7. In the **Auth Scopes** section, add the `table_read` scope.
8. Save the application.
9. Copy the generated **Client ID** and **Client Secret** for use during integration setup.

   <div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><p>The Client ID and Client Secret are sensitive credentials. Store them securely.</p></div>

### Setup <a href="#setup" id="setup"></a>

To configure the ServiceNow integration:

1. From the SEI navigation menu, click **Account Management**.
2. From the **Integrations** page, navigate to the **Available Integrations** tab.
3. Locate the ServiceNow integration tile under `Incident Management` and click **Add Integration**.
4. Select an installation option: **ServiceNow Cloud** or **ServiceNow On-Prem**.

Once the integration is configured, Harness AIDI begins ingesting ITSM data from ServiceNow.

### Custom fields <a href="#custom-fields" id="custom-fields"></a>

The **Custom Fields** tab allows you to map additional ServiceNow fields to SEI. You can use custom fields to include organization-specific metadata (such as priority, assignment group, or custom attributes) in your SEI dashboards and reports.

You can map custom fields by defining filter sets for incident and change request identification on the **Incident Management** tab in [**Team Settings**](/software-engineering-insights/use-software-engineering-insights/setup-sei/setup-teams.md#configure-team-tool-settings).

![](/files/4KCbaEbsXDJcPPFRx84q)

Once configured, these fields are included in data ingestion and become available for filtering and analysis in AI DLC Insights.

### Integration monitoring <a href="#integration-monitoring" id="integration-monitoring"></a>

To monitor the status of the ServiceNow integration, navigate to the **Monitoring** tab. This page displays ingestion logs that provide visibility into data synchronization.

You can click the **Filters** icon to filter logs by **Status** (`Success`, `Failed`, `Pending`, or `Scheduled`).

Each ingestion log includes the following fields:

| Field                      | Description                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| **Scan Range Time**        | The time window of data retrieved from ServiceNow during the ingestion task.                   |
| **Data Retrieval Process** | The ingestion job responsible for fetching data from ServiceNow.                               |
| **Task Start Time**        | The timestamp when the ingestion task began running.                                           |
| **Status**                 | The current state of the ingestion task (for example, Success, Failed, Pending, or Scheduled). |
| **Time to Complete**       | The total duration required for the ingestion task to complete.                                |
| **Retries**                | The number of times the ingestion task was retried after a failure.                            |