> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ServiceNow

> Connect ServiceNow for ITSM, ITOM / Event Management, CMDB, and ACC context during investigations.

Connecting ServiceNow lets Traversal pull read-only operational context during investigations.

## What Traversal reads

Traversal reads each of the following tables with `GET /api/now/table/{table}`.

| Table | What Traversal reads | Module |
| - | - | - |
| `incident` | Incidents, including the initial connection test | ITSM |
| `change_request` | Change requests | ITSM |
| `sys_user_group` | Assignment groups | ITSM |
| `sys_attachment` | Attachment metadata on the records Traversal reads | ITSM |
| `em_alert` | Alert records | ITOM / Event Management |
| `cmdb_ci` | Configuration items | CMDB |
| `cmdb_rel_ci` | Relationships between configuration items | CMDB |
| `cmdb_ci_service` | Business services | CMDB |
| `cmdb_ci_business_app` | Business applications | CMDB |
| `service_offering` | Service offerings | CMDB |
| `kb_knowledge` | Knowledge base articles | Knowledge |

> [!NOTE]
>
> Use this table as the source of truth for the read access the ServiceNow integration needs on a standard instance. Traversal needs read access to these tables and no others, and no write access to any of them.

### Additional endpoints

Traversal also calls two endpoints outside the Table API:

| Endpoint | Purpose |
| - | - |
| `GET /api/now/attachment/{sys_id}/file` | Downloads the contents of an attachment found on a record Traversal has already read |
| `POST /api/now/v1/batch` | Reads ACC / Clotho metrics, such as CPU, memory, and disk, for supported configuration items |

The Batch API call carries its sub-requests in the request body. Traversal puts one `GET` per metric there, in the form:

```text theme={null}
GET /api/now/v1/clotho/table/cmdb_ci_computer/{ci_sys_id}/{metric}
```

The ACC / Clotho metrics are optional. Traversal reads them only for supported hardware configuration items, so you can leave that access out if you don't want Traversal to read metrics.

> [!NOTE]
>
> The Batch API call is an HTTP `POST`, but it is still read-only. The method is a `POST` because ServiceNow's Batch API takes its sub-requests in the request body, and Traversal only ever puts `GET` requests there. The call creates and modifies no records.

### Custom tables

Some ServiceNow instances are customized enough that Traversal needs to read an additional or custom table, such as a database view that replaces a standard table. Traversal identifies any such tables with you during onboarding and adds them to the list above for your deployment. The tables in this page are what a standard ServiceNow instance requires.

## Before you start

Ask your ServiceNow administrator for:

* your ServiceNow instance URL, such as `https://your-instance.service-now.com`
* your token URL, which is usually `https://your-instance.service-now.com/oauth_token.do`
* an integration user with read access to the tables listed in [What Traversal reads](#what-traversal-reads)
* if you want ACC metrics, whatever Clotho or ACC permissions your instance requires for metrics access

Some teams use roles such as `snc_read_only` for general table reads and `sn_clotho_user` for Clotho metrics access, but ServiceNow roles vary by module, release, and instance customization. Confirm the exact role set with your ServiceNow administrator instead of assuming one universal combination.

## Setup

**1. Choose how you want to sign in**

> [tab] OAuth client credentials
>
> Use this option when your administrator gives you a dedicated OAuth application's **Client ID**, **Client Secret**, and token URL.

> [tab] Username and password
>
> Use this option when your administrator gives you a ServiceNow **Username**, **Password**, and token URL for the integration user.
>
> Traversal uses those credentials to obtain access tokens automatically. You don't need to generate and paste a bearer token yourself.

**2. Gather the values Traversal needs**

In Traversal, you will enter:

* **Instance URL**
* **Token URL**
* either **Client ID** and **Client Secret**, or **Username** and **Password**

The token URL is usually:

```text theme={null}
https://<your-instance>.service-now.com/oauth_token.do
```

**3. Configure in Traversal**

Go to **Integrations**, select ServiceNow, and enter:

* **Instance URL** (for example, `https://your-instance.service-now.com`)
* **Auth type**: select the option that matches the credentials your administrator provided
* **Token URL**
* For client credentials: **Client ID** and **Client Secret**
* For username and password: **Username** and **Password**

If the integration doesn't work after you save it, confirm that:

* the credentials have read access to every table in [What Traversal reads](#what-traversal-reads)
* the token URL is the correct `oauth_token.do` endpoint for your instance or custom domain
* the integration user is allowed to use ServiceNow web services

## Private network access

If the service endpoint isn't directly reachable by Traversal (as is common with self-hosted services), deploy a [Traversal Connector](https://docs.traversal.com/architecture/connector.md) in a network that can reach it. When configuring the integration, select that connector under **Network Access Needed**. The service endpoint doesn't need public internet exposure.

See [Set up the Traversal Connector](https://docs.traversal.com/setup/connector.md) for deployment and network requirements.

## FAQ

> [accordion] Which authentication method should I use?
>
> Use **OAuth client credentials** if your administrator can issue a dedicated OAuth app for Traversal. Use **Username and password** if your administrator prefers an integration user account. Both methods let Traversal obtain OAuth access tokens automatically, but the operational difference is whether your administrator manages an OAuth app or a user credential.

> [accordion] Does Traversal write to any ServiceNow tables?
>
> No. Traversal only makes read-only API calls. No records are created, updated, or deleted.
>
> One call uses the `POST` method: `POST /api/now/v1/batch`, which Traversal uses to fetch ACC / Clotho metrics. ServiceNow's Batch API takes its sub-requests in the request body, which is why the call is a `POST`, and Traversal only puts `GET` requests there. If your security review flags the method, this is the call it found.

> [accordion] What is the minimum access Traversal needs?
>
> Read-only access to the tables in [What Traversal reads](#what-traversal-reads), plus the [additional endpoints](#additional-endpoints) if you want attachments and ACC metrics. Traversal needs nothing beyond read access to those. See [Before you start](#before-you-start) for guidance on the roles that grant it.

## More information

* [ServiceNow REST API](https://developer.servicenow.com/dev.do#!/reference/api)
* [ServiceNow OAuth setup](https://support.servicenow.com/kb?id=kb_article_view\&sysparm_article=KB2058319)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.