> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/servicenow-for-alert-notifs/incident-management.md).

# Incident Management

ThousandEyes supports routing alert notifications directly into [ServiceNow Incident Management Services](https://docs.servicenow.com/bundle/washingtondc-it-service-management/page/product/it-service-management/reference/r_ITServiceManagement.html) - a solution for streamlining the logging, classification, assignment, escalation, and reporting of incidents. The following guide describes the process of configuring ServiceNow and ThousandEyes [alert rules](https://docs.thousandeyes.com/product-documentation/alerts) to send alert notifications directly into the ServiceNow platform.

## Overview

The ThousandEyes platform can notify users whenever their test results trigger an *alert rule*. Alert rules allow configuring various methods of alert notification delivery. One of the supported methods is direct notification delivery into a ServiceNow account. Once the notification is delivered, ServiceNow processes it and allocates tasks based upon pre-defined workflows.

To route alert notifications directly into ServiceNow, configure the following:

* A ServiceNow integration.
* Alert rules associated with the ServiceNow integration.
* ThousandEyes tests associated with the alert rules.

The sections below guide you through configuring ServiceNow and the ThousandEyes platform. When a ThousandEyes alert triggers, the platform creates a new incident in your ServiceNow account. This process helps align ThousandEyes-reported events with your ServiceNow workflow.

## Choosing a ServiceNow Alert Route

Use this table to choose the route that matches your workflow:

| Route                              | Best for                                             | Short summary                                                                      |
| ---------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **ServiceNow Incident Management** | Managing a ServiceNow incident from trigger to clear | Creates one incident and updates its state.                                        |
| **Custom webhook**                 | Sending alert data to a custom endpoint              | Sends each notification with `POST`. Not available in ThousandEyes for Government. |

### ServiceNow Incident Management

Choose this route when you want the ThousandEyes platform to manage one ServiceNow incident through an alert's lifecycle. See [ServiceNow Alert Management](#servicenow-alert-management) for the request methods, state changes, and integration direction.

### Custom Webhooks

Choose this route when you need to send alert data to a custom endpoint or a system without a built-in integration. The current custom webhook operation sends every notification with `POST`; the receiving system must handle notification types and record correlation.

## Supported ServiceNow Releases

ThousandEyes support for a ServiceNow release family stops on the same date when ServiceNow declares a release EOL (end-of-life). However, despite the ServiceNow release reaching EOL, ThousandEyes alert integrations should continue to work. If you have support questions, contact the [ThousandEyes Customer Engineering Team](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes).

If your ServiceNow release is not listed as supported by ThousandEyes in the table below, use [Custom Webhooks](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks) instead of the ServiceNow integration.

| **ServiceNow Release** | **Supported by ThousandEyes** |
| ---------------------- | ----------------------------- |
| Utah                   | Supported                     |
| Vancouver              | Supported                     |
| Washington DC          | Supported                     |

## ServiceNow Configuration

To receive ThousandEyes alert notifications directly, configure ServiceNow first.

The following instructions assume that the ServiceNow [Service Management Portal](https://docs.servicenow.com/bundle/washingtondc-service-management-for-the-enterprise/page/product/it-services/task/t_ActivateServiceManagement.html) is activated.

### Configure OAuth Authentication

In these steps, create the [**OAuth Application Registry**](https://docs.servicenow.com/bundle/washingtondc-application-development/page/build/pipelines-and-deployments/task/create-oauth-api-endpoints-for-external-clients.html) for external API endpoints:

1. Select **System Oauth > Application Registry** from the **All** tab.

![Application Registry link on the All tab](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-9a6541d5f8c1c556467515576ca7ffc01453fea9%2Fproduct-documentation_integration-guides_custom-built-integrations_servicenow-for-alert-notifs_incident-management-2.png?alt=media\&token=480f1e44-d74d-4e02-9941-023118f315c7)

2. Click **New** in the **Application Registry** page.

![Showing the New button on the Application Registry page](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-7b2c293d0d81695356dc4a958c350592b1684d4c%2Fproduct-documentation_integration-guides_custom-built-integrations_servicenow-for-alert-notifs_incident-management-3.png?alt=media\&token=2bc0f232-eed2-4a17-97bb-6a5f9c100d4c)

3. Click **Create an OAuth API endpoint for external clients**.

![Showing list of OAuth applications to choose from](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-3fd42ae5d148108b2bb101d27da00c05d9ca548a%2Fproduct-documentation_integration-guides_custom-built-integrations_servicenow-for-alert-notifs_incident-management-4.png?alt=media\&token=06fe0810-192a-41e8-8146-40c77a366ec5)

4. Copy the generated Client ID and Client Secret.
   * This value will be used when configuring ThousandEyes' ServiceNow integration in the next section.

![The generated Client ID and Client Secret](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-b090369801ba380ebe72da9aec272d30573c5c08%2Fproduct-documentation_integration-guides_custom-built-integrations_servicenow-for-alert-notifs_incident-management-5.png?alt=media\&token=2eb8c1a7-6098-4734-9df9-e8b57189f89d)

5. Unlock the **Redirect URL** field and assign the following value: <https://app.thousandeyes.com/namespace/integrations/AuthCallbackPage.html>.

   **Note**: Access and refresh tokens require manual reconfiguration after they expire. Configure the token lifespan as `8640000`, the maximum value allowed, which equals 100 days.

## Creating a ServiceNow Integration Within ThousandEyes

A ServiceNow integration must be created before being assigned to alert rules.

### Navigate to the Integrations Screen

1. Start by selecting [**Manage > Integrations**](https://app.thousandeyes.com/manage/integrations) within the menu panel.
2. Click **+ New Integration**.
3. Select **ServiceNow Alert Notifications**.

### Configure ServiceNow Integration Settings

The following figure shows the dialog for creating a new ServiceNow integration: ![Edit configuration](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-0312e6f3031a25b68e6053dd02f454917dc6a986%2Fproduct-documentation_alerts_servicenow-integration-7.png?alt=media\&token=a662cc18-58ae-4efc-b25a-9c297f5e44db)

In the dialog, configure the following fields:

* **Type:** Make sure "ServiceNow" is selected.
* **Name:** Select a name for your ServiceNow integration.
* **ServiceNow URL:** The ServiceNow endpoint to which ThousandEyes will send notifications.
  * **ServiceNow URL format:** `https://<instance-name>.service-now.com`
* **Auth URL:** The ServiceNow endpoint to which ThousandEyes will authenticate, via [OAuth](https://en.wikipedia.org/wiki/OAuth), prior to submitting notifications.
  * **Auth URL format:** `https://<instance-name>.service-now.com/oauth_auth.do`
* **Client ID:** The identifier which ThousandEyes will use when authenticating to ServiceNow.

### Obtain a ServiceNow Authentication Token

After you configure the fields above, retrieve an authentication token. The ThousandEyes platform stores the token for alert notifications. Repeat this step when the token expires.

1. Click the **Get Token** button. The ServiceNow Authorization screen opens.
2. Click **Allow** to proceed.

![The Allow button on the ServiceNow Authorization screen](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-7d2c7b5cd050b78ad07c6e46e39375f4b77e4a58%2Fproduct-documentation_integration-guides_custom-built-integrations_servicenow-for-alert-notifs_incident-management-6.png?alt=media\&token=2015b2f9-5a72-433f-969c-8c37b279a17d)

### Test Your Integration

The **Test** button sends a sample **New** incident to the configured ServiceNow endpoint. A successful test confirms that ServiceNow accepted the sample request. It does not verify that a real alert re-trigger updates the same incident or that an alert clear resolves it.

### Validating the Alert Lifecycle

Before you begin, confirm that you have the *Edit Alert Suppression Windows* permission.

Use a disposable test alert and a real-time Alert Suppression Window to verify the full lifecycle:

1. Assign the ServiceNow integration to an alert rule and trigger the test alert condition. Confirm that ServiceNow creates a **New** incident.
2. Keep the alert condition active. In **Alerts > Active Alerts**, apply a real-time Alert Suppression Window to the alert. Applying the window sends a clear notification immediately, so confirm that ServiceNow updates the same `sys_id` and changes the incident to **Resolved**. Leave the condition active until the window ends. If the alert is still active, it returns to **Active Alerts** and sends another trigger notification for the same alert. Confirm that ServiceNow updates the same `sys_id` and changes the incident to **In Progress**. For more information, see [Continuous and Intermittent Alert Notifications](https://docs.thousandeyes.com/product-documentation/alerts/alert-clearing/alert-suppression-windows#continuous-and-intermittent-alert-notifications).
3. Restore the monitored condition so the alert clears. Confirm that ServiceNow updates the same `sys_id` and changes the incident to **Resolved** again.

If a step fails, check the alert notification history and ServiceNow records before treating the integration as fully validated.

## Assigning ServiceNow Integrations to Alert Rules

After you create it, assign the ServiceNow integration to an alert rule through the rule's **Notifications** settings and select it from the dropdown list:

1. Navigate to the **Integrations** section of the desired alert rule's **Notifications** configuration tab.
2. Select the desired ServiceNow integration from the dropdown.
3. Click **Save Changes**.

Keep these details in mind:

* Integrations are available within an account group. You can use an integration with multiple alert rules in that account group.
* Notification preferences are configured per alert rule. Assign your new ServiceNow integration to all alert rules that require it.
* Integrations cannot be shared between account groups, so create one for each account group.
* Multiple integrations may use the same ServiceNow endpoint and authentication token.

## ServiceNow Alert Management

When an alert first triggers, the ThousandEyes platform creates a corresponding ServiceNow incident. If the alert triggers again before it clears, the platform updates the same incident. When the alert clears, the platform updates that incident to show that it is resolved.

The integration follows this lifecycle:

* **New alert trigger:** Sends a `POST` request to create an incident in the **New** state.
* **Alert re-trigger:** Sends a `PUT` request for the same ServiceNow `sys_id` and changes the incident to **In Progress**.
* **Alert clear:** Sends a `PUT` request for the same `sys_id` and changes the incident to **Resolved**.

These updates flow from the ThousandEyes platform to ServiceNow. Resolving an incident in ServiceNow does not, by itself, clear or suppress the alert in the ThousandEyes platform.

![Example: ServiceNow Incident](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-8a769771f62981ca0150248ba1f9c90912213318%2Fproduct-documentation_alerts_servicenow-integration-9.png?alt=media\&token=a6849ef1-48cc-4112-9587-72366e20e1ac)

When the integration creates an incident, it includes the following customer-relevant fields. The request that creates the incident also includes a stable `sys_id` derived from the ThousandEyes alert ID. When the alert re-triggers or clears, the integration sends that same `sys_id` and updates the **State** only.

| Field                 | Value                                                                                                                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **State**             | Set to `New` when an alert first triggers, `In Progress` when an active alert triggers again, and `Resolved` when the alert clears.                                                                             |
| **Impact**            | Set when the incident is created: **High** for Critical alerts, **Medium** for Major alerts, and **Low** for all other severities. The integration does not resend Impact when the alert re-triggers or clears. |
| **Urgency**           | Set to `Medium`.                                                                                                                                                                                                |
| **Category**          | Set to `Network`.                                                                                                                                                                                               |
| **Caller**            | ServiceNow uses the current authenticated user's full name for the `caller_id` field.                                                                                                                           |
| **Short Description** | "ThousandEyes Alert triggered for Test: \<Test Name>".                                                                                                                                                          |
| **Description**       | Contains alert details, including the alert rule name and number of affected agents.                                                                                                                            |

## Related Information

The following resources provide additional information:

* [Creating and Editing Alert Rules](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules) is a detailed guide about how to manage alert rules within the ThousandEyes platform.
* [ServiceNow FAQ](https://support.servicenow.com/kb?id=kb_article_view\&sysparm_article=KB0610454#6) on EOL aka unsupported release family upgrades.