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

# ServiceNow

> Connect a ServiceNow instance so OpenSRE can check its configuration and credentials

OpenSRE connects to ServiceNow so the CLI and the interactive shell can answer configuration questions about your instance — `opensre integrations verify servicenow` and shell questions like *"Is ServiceNow configured?"* return a real result instead of suggesting commands to run.

## Prerequisites

* A ServiceNow instance URL (a free [developer instance](https://developer.servicenow.com) works)
* A user with read access to the `sys_user` table (used for the onboarding connectivity check)

## Setup

### Option 1: Onboarding wizard

```bash theme={null}
opensre onboard
```

Select **ServiceNow** under *Incident & Comms* and provide your instance URL, username, and password. The wizard validates the credentials with a one-row authenticated read of the `sys_user` table before saving.

### Option 2: Legacy CLI

```bash theme={null}
opensre integrations setup servicenow
```

### Option 3: Environment variables

```bash theme={null}
export SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
export SERVICENOW_USERNAME=admin
export SERVICENOW_PASSWORD=your-password
```

`SERVICENOW_PASSWORD` is also resolved from the OS keyring when the environment variable is not set (the wizard stores it there).

### Option 4: Persistent store

Add to `~/.opensre/integrations.json`:

```json theme={null}
{
  "version": 1,
  "integrations": [
    {
      "id": "servicenow-prod",
      "service": "servicenow",
      "status": "active",
      "credentials": {
        "instance_url": "https://dev12345.service-now.com",
        "username": "admin",
        "password": "your-password"
      }
    }
  ]
}
```

| Field          | Description                                                                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instance_url` | **Required.** Your ServiceNow instance URL (e.g., `https://dev12345.service-now.com`). Must use `https://` — plain `http://` is accepted only for localhost/loopback targets. |
| `username`     | **Required.** ServiceNow username for HTTP Basic authentication                                                                                                               |
| `password`     | **Required.** Password for the user                                                                                                                                           |

## Verify

```bash theme={null}
opensre integrations verify servicenow
```

Expected output on success:

```
SERVICE    │ SOURCE    │ STATUS   │ DETAIL
━━━━━━━━━━━┿━━━━━━━━━━━┿━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
servicenow │ local env │ ✓ passed │ Configured for ServiceNow at
           │           │          │ https://dev12345.service-now.com.
```

This is a configuration-presence check (`instance_url`, `username`, and `password` are all set) rather than a live API call. The live connectivity check runs during onboarding wizard validation.

You can also ask the interactive shell directly:

```
> Is ServiceNow configured?
```

The shell runs the same verifier and answers from its result.

## Troubleshooting

| Symptom                                | Fix                                                                                                             |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Status `missing`**                   | Set `instance_url`, `username`, and `password` via any setup option above                                       |
| **401 Unauthorized during onboarding** | Check the username and password combination                                                                     |
| **403 Forbidden during onboarding**    | The user authenticated but cannot read the `sys_user` table — grant a role with table read access (e.g. `itil`) |
| **404 Not Found during onboarding**    | Verify the instance URL (include `https://`, no path)                                                           |
| **Developer instance unreachable**     | Free developer instances hibernate after inactivity — wake it from the developer portal and retry               |

## Security best practices

* Use a **dedicated ServiceNow user** for OpenSRE with the minimum roles it needs (read access only).
* Prefer the onboarding wizard: it keeps the password in the OS keyring instead of `.env`.
* Rotate the password periodically and remove the integration when no longer needed.