# ServiceNow

ServiceNow is an enterprise IT service management (ITSM) platform that provides incident management, change management, asset tracking, and workflow automation. The Sling ServiceNow connector extracts data from the ServiceNow Table API, supporting ITSM records, user management, CMDB, and audit data.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `instance` **(required)** -> Your ServiceNow instance name (e.g., `dev12345` from `dev12345.service-now.com`)
* `username` **(required)** -> ServiceNow username with API access
* `password` **(required)** -> ServiceNow password for the specified user

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction on first sync (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your Credentials

1. Log in to your [ServiceNow instance](https://developer.servicenow.com/) as an administrator
2. The **instance name** is the subdomain of your ServiceNow URL (e.g., `dev12345` from `https://dev12345.service-now.com`)
3. Use your admin **username** and **password** for authentication
4. Ensure the user has the `rest_api_explorer` or `admin` role for full API access

{% hint style="info" %}
**Free Developer Instance:** You can get a free ServiceNow developer instance at [developer.servicenow.com](https://developer.servicenow.com/) to test the connector.
{% endhint %}

{% hint style="warning" %}
**Important:** Store your credentials securely. Never commit passwords to version control. Consider creating a dedicated service account with read-only access for data extraction.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set SERVICENOW type=api spec=servicenow secrets='{ instance: dev12345, username: admin, password: your_password }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export SERVICENOW='{ type: api, spec: servicenow, secrets: { instance: "dev12345", username: "admin", password: "your_password" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  SERVICENOW:
    type: api
    spec: servicenow
    secrets:
      instance: "dev12345"
      username: "admin"
      password: "your_password"
```

**With anchor date for historical data:**

```yaml
connections:
  SERVICENOW:
    type: api
    spec: servicenow
    secrets:
      instance: "dev12345"
      username: "admin"
      password: "your_password"
    inputs:
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync ServiceNow data to a PostgreSQL database:

```yaml
source: SERVICENOW
target: MY_POSTGRES

defaults:
  mode: incremental
  object: servicenow.{stream_name}

streams:
  # ITSM core data
  incidents:
  change_requests:
  problems:
  tasks:

  # User management
  sys_users:
  sys_user_groups:
  sys_user_group_members:
    mode: full-refresh

  # CMDB
  cmdb_ci:
  cmdb_ci_servers:

  # Reference data (full-refresh only)
  cmn_locations:
    mode: full-refresh
  core_companies:
    mode: full-refresh
  sys_user_roles:
    mode: full-refresh
  sys_user_has_roles:
    mode: full-refresh
```

**Sync all endpoints:**

```yaml
source: SERVICENOW
target: MY_POSTGRES

defaults:
  mode: incremental
  object: servicenow.{stream_name}

streams:
  # Sync all available endpoints
  '*':
```

## Endpoints

### ITSM Records

| Endpoint          | Description                                            | Incremental |
| ----------------- | ------------------------------------------------------ | ----------- |
| `incidents`       | IT incident records                                    | Yes         |
| `change_requests` | Change request records                                 | Yes         |
| `problems`        | Problem records                                        | Yes         |
| `tasks`           | Generic task records (base table for all ticket types) | Yes         |
| `sc_requests`     | Service catalog request records                        | Yes         |
| `sc_req_items`    | Service catalog requested item records                 | Yes         |

### User Management

| Endpoint                 | Description                     | Incremental |
| ------------------------ | ------------------------------- | ----------- |
| `sys_users`              | User account records            | Yes         |
| `sys_user_groups`        | User group records              | Yes         |
| `sys_user_group_members` | Group membership records        | No          |
| `sys_user_roles`         | Role definition records         | No          |
| `sys_user_has_roles`     | User-to-role assignment records | No          |

### CMDB

| Endpoint          | Description                       | Incremental |
| ----------------- | --------------------------------- | ----------- |
| `cmdb_ci`         | Configuration item records        | Yes         |
| `cmdb_ci_servers` | Server configuration item records | Yes         |

### Reference Data

| Endpoint         | Description                  | Incremental |
| ---------------- | ---------------------------- | ----------- |
| `cmn_locations`  | Location records             | No          |
| `core_companies` | Company/organization records | No          |

### Knowledge & Audit

| Endpoint       | Description                    | Incremental |
| -------------- | ------------------------------ | ----------- |
| `kb_knowledge` | Knowledge base article records | Yes         |
| `sys_audit`    | Audit log records              | Yes         |

To discover available endpoints:

```bash
sling conns discover SERVICENOW
```

## Incremental Sync

The ServiceNow connector supports incremental sync for most endpoints using the `sys_updated_on` timestamp field. On first sync, records from the last year (or the configured `anchor_date`) are fetched. Subsequent syncs only fetch records modified after the last sync timestamp.

### Supported Incremental Endpoints

* **ITSM:** `incidents`, `change_requests`, `problems`, `tasks`, `sc_requests`, `sc_req_items`
* **Users:** `sys_users`, `sys_user_groups`
* **CMDB:** `cmdb_ci`, `cmdb_ci_servers`
* **Knowledge:** `kb_knowledge`
* **Audit:** `sys_audit` (uses `sys_created_on` since audit records are append-only)

### Full-Refresh Only Endpoints

Reference and lookup tables use full-refresh mode since they are typically small and change infrequently:

* `cmn_locations`, `core_companies`, `sys_user_roles`, `sys_user_has_roles`, `sys_user_group_members`

## Rate Limiting

The ServiceNow API has rate limits that vary by instance type:

* **Developer instances:** Lower rate limits
* **Production instances:** Higher rate limits based on subscription

The connector automatically:

* Uses conservative rate limiting (5 requests/second)
* Retries with exponential backoff on HTTP 429 (rate limit) responses
* Retries on HTTP 5xx server errors

## Common Use Cases

### ITSM Incident Analytics

```yaml
source: SERVICENOW
target: MY_POSTGRES

defaults:
  mode: incremental
  object: itsm.{stream_name}

streams:
  incidents:
  change_requests:
  problems:
  tasks:
```

### User and Access Management

```yaml
source: SERVICENOW
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: servicenow_users.{stream_name}

streams:
  sys_users:
  sys_user_groups:
  sys_user_group_members:
  sys_user_roles:
  sys_user_has_roles:
```

### CMDB Asset Inventory

```yaml
source: SERVICENOW
target: MY_POSTGRES

defaults:
  mode: incremental
  object: cmdb.{stream_name}

streams:
  cmdb_ci:
  cmdb_ci_servers:
  cmn_locations:
    mode: full-refresh
  core_companies:
    mode: full-refresh
```

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/servicenow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.