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

# ServiceNow Connector Tools

> Read and update ServiceNow ITSM records — incidents, changes, and catalog requests — through the Table API and Attachment API.

## Overview

<Note>
  This page documents the **manual tool surface** that an agent (or a Flow) can call to act on ServiceNow on demand. It is **not** the same as automatic record pickup — for that, configure [ServiceNow Automation (Auto-Pickup)](/docs/Setup/ServiceNow-Automation), which uses these same credentials but adds polling/webhook intake and trigger rules so Genesis starts work without being asked.

  Before using this tool group, save a ServiceNow connection as described in [Setup ServiceNow API Parameters](/docs/Setup/Setup-ServiceNow-API-Params).
</Note>

### Tool Name

```json theme={null}
servicenow_connector_tools
```

### Purpose

The **servicenow\_connector\_tools** group integrates Genesis workflows with ServiceNow ITSM. Authenticate to a ServiceNow instance, list and update records, add comments or work notes, manage attachments, and run constrained raw Table API requests.

#### Functions Available

1. **`servicenow_connector`**: Standard ServiceNow record, journal, attachment, and search operations.
2. **`servicenow_automation_action`**: Run a ServiceNow polling pass from a scheduled Genesis Flow (`POLL_ONCE`).

## Input Parameters

### `servicenow_connector`

**Parameters**

| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **action** | Operation to perform. Supported: `TEST_CONNECTION`, `LIST_RECORDS`, `GET_RECORD`, `CREATE_RECORD`, `UPDATE_RECORD`, `ADD_COMMENT`, `ADD_WORK_NOTE`, `LIST_COMMENTS`, `SET_STATE`, `LIST_ATTACHMENTS`, `DOWNLOAD_ATTACHMENT`, `UPLOAD_ATTACHMENT`, `RAW_REQUEST`. | String (required) | none |
| **connection** | Optional ServiceNow connection name like `servicenow.prod`. Uses the effective usable ServiceNow connection for the current user and active bot when omitted. | String | none |
| **table** | ServiceNow table name (for example `incident`, `change_request`, `sc_request`, `sc_req_item`). Required for most actions. Only allowlisted tables are accepted. | String | none |
| **sys\_id** | Record sys\_id (32-char hex). Provide **sys\_id** OR **number**. | String | none |
| **number** | Human-readable record number (for example `INC0010001`) as an alternative to sys\_id. | String | none |
| **query** | Encoded query for `LIST_RECORDS` (for example `active=true^assigned_to.user_name=genesis.bot^ORDERBYDESCsys_updated_on`). | String | none |
| **fields** | Comma-separated field names to return. | String | none |
| **data** | Field/value object for `CREATE_RECORD` or `UPDATE_RECORD` bodies. | Object | none |
| **comment** | Text for `ADD_COMMENT` (customer-visible) or `ADD_WORK_NOTE` (internal). | String | none |
| **state** | Target state value for `SET_STATE` (numeric value like `2` or a label). | String | none |
| **state\_field** | Field to update for `SET_STATE`. | String | `state` |
| **limit** | Maximum records for list actions. | Integer | `25` |
| **offset** | Pagination offset for list actions. | Integer | `0` |
| **order\_by** | Field to order `LIST_RECORDS` by. | String | `sys_updated_on` |
| **display\_value** | How to render reference/choice fields: `true`, `false`, or `all`. | String | `true` |
| **attachment\_sys\_id** | Attachment sys\_id for `DOWNLOAD_ATTACHMENT`. | String | none |
| **file\_path** | Relative path in thread storage for `UPLOAD_ATTACHMENT`. | String | none |
| **file\_name** | Optional filename override for `UPLOAD_ATTACHMENT`. | String | none |
| **api\_path** | `RAW_REQUEST` path; must start with `/api/now/` (for example `/api/now/table/incident`). | String | none |
| **method** | `RAW_REQUEST` HTTP method. Only `GET` is accepted; use typed actions for record mutations and attachments. | String | `GET` |
| **params** | Optional query parameters object for `RAW_REQUEST`. | Object | none |

<Note>
  **Table allowlist:** writes are limited to `incident`, `change_request`, `sc_request`, and `sc_req_item` plus any tables an admin adds via the `servicenow.extra_tables` config setting. `sys_user`, `sys_user_group`, and `sys_journal_field` are readable for lookups but never writable. **DELETE is not available** through any action.
</Note>

<Note>
  **`RAW_REQUEST` constraints:** paths must be under `/api/now/`, table paths obey the allowlist, and attachment API paths are blocked. `RAW_REQUEST` is read-only and accepts only `GET`; use `CREATE_RECORD`, `UPDATE_RECORD`, `ADD_COMMENT`, `ADD_WORK_NOTE`, `SET_STATE`, or `UPLOAD_ATTACHMENT` for writes. Those typed writes run under Action Review.
</Note>

<Note>
  **Action Review for writes:** `CREATE_RECORD`, `UPDATE_RECORD`, `ADD_COMMENT`, `ADD_WORK_NOTE`, `SET_STATE`, and `UPLOAD_ATTACHMENT` are governed writes. See the [Action Review response contract](/docs/Genesis-API/API-Reference#action-review-response-fields) for pending and reconciliation results. For the ServiceNow identity used by a User OAuth write, including an approved write, see [User OAuth setup](/docs/Setup/Setup-ServiceNow-API-Params). For uploads, Genesis reads the thread-storage file again before submission and refuses the upload if the file cannot be read or its content changed after approval. When Genesis creates a record in `task`, `incident`, `incident_task`, `problem`, `problem_task`, `change_request`, `change_task`, `sc_request`, `sc_req_item` or `sc_task`, it sets the record's `correlation_id` to a unique `genesis-<uuid>` value unless your request sets `correlation_id` itself. If the create's response is lost, Genesis reads the table by that value: finding the record settles the attempt as executed; not finding it leaves the attempt for a person to check, because the field can be changed by other integrations or hidden by access rules. A write that fails because the connection's credentials could not be exchanged for a token is reported as not applied, because nothing was sent to ServiceNow.
</Note>

**Example**

```python theme={null}
servicenow_connector(
    action="GET_RECORD",
    table="incident",
    number="INC0012345",
    fields="number,short_description,state,assigned_to",
)
```

### `servicenow_automation_action`

Use this helper to run a ServiceNow polling pass from a scheduled Genesis Flow or manually from chat.

| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **action** | Automation action to perform. Currently supports `POLL_ONCE`. | String (required) | none |
| **lookback\_minutes** | Optional polling lookback override in minutes. | Integer | none |

`POLL_ONCE` uses the saved shared automation configuration from [ServiceNow Automation (Auto-Pickup)](/docs/Setup/ServiceNow-Automation) and returns matched, dispatched, skipped, and failed record lists.

**Example**

```python theme={null}
servicenow_automation_action(
    action="POLL_ONCE",
    lookback_minutes=15,
)
```

## Use Cases

1. **Look up an incident** — `GET_RECORD` by `number` or `sys_id` when a user references `INC0012345`.
2. **Triage open work** — `LIST_RECORDS` with an encoded query for high-priority active incidents.
3. **Post internal notes** — `ADD_WORK_NOTE` after analysis; `ADD_COMMENT` when the customer should see the update.
4. **Transition state** — `SET_STATE` when a workflow step completes.
5. **Attach evidence** — `UPLOAD_ATTACHMENT` from thread storage or `DOWNLOAD_ATTACHMENT` into the current thread for agent review.
6. **Scheduled intake** — wire `servicenow_automation_action` with `POLL_ONCE` into the managed **ServiceNow Ticket Poller** Flow.

## Related pages

* [Setup ServiceNow API Parameters](/docs/Setup/Setup-ServiceNow-API-Params)
* [ServiceNow Automation (Auto-Pickup)](/docs/Setup/ServiceNow-Automation)
* [Connections](/docs/Setup/Connections)
* [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools)