# 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, the following needs to be properly configured:

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

The content below will guide you through the process of configuring both, ServiceNow and ThousandEyes. In the end, an alert triggered in ThousandEyes will cause a new incident to be generated within your ServiceNow account instantly. This process should streamline the handling of ThousandEyes-reported events, aligning it with your existing (ServiceNow-based) workflow.

## 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 be able to receive ThousandEyes alert notifications directly, ServiceNow must first be configured to allow it.

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 you 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. Take a copy of 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 re-configuration once their lifespans have been exceeded. Token lifespan should be configured as `8640000` (max value allowed, equal to 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 pane.
2. Click **+ New Integration**.
3. Select **ServiceNow Alert Notifications**.

### Configure ServiceNow Integration Settings

The following figure depicts the dialog box 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)

Within the dialog box, you can 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

Once the fields in the previous step are configured, retrieval of an authentication token is required. ThousandEyes will retrieve and store the authentication token to be used when notifying ServiceNow of alerts. This step will need to be repeated whenever the token expires.

1. Click the **Get Token** button.
   * You should be redirected to the ServiceNow Authorization screen.
2. Click on **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 is provided to verify the correctness of your integration setup. Click it to send a test notification using your new integration. A new incident should be generated in your ServiceNow account.

## Assigning ServiceNow Integrations to Alert Rules

Once created, ServiceNow integration can be assigned to any alert rule by opening the rule's **Notifications** settings and selecting your new integration from the drop-down list:

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

Here are some additional details to be aware of:

* Integrations are available on an account group basis. An integration can be used by multiple alert rules in an account group.
* Notification preferences are configured per alert rule. Assign your new ServiceNow integration to all alert rules that require it.
* Integrations cannot shared between account group so must be created per account group.
* Multiple integrations may use the same ServiceNow endpoint and authentication token.

## ServiceNow Alert Management

Upon receiving a new notification from the ThousandEyes platform, ServiceNow will create a corresponding incident:

![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)

The following fields are mapped upon creation of a new incident:

* **State:** Set to `New` when an alert is triggered and `Resolved` when the alert is cleared.
* **Urgency:** Set to `Medium`.
* **Category:** Set to `Network`.
* **Short Description:** "ThousandEyes Alert triggered for Test: \<Test Name>".
* **Description:** This field contains alert details including alert rule name and number of agents affected.

## 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.