> ## 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 Automation (Auto-Pickup)

> Configure Genesis to automatically pick up ServiceNow records when they are assigned, change state, or receive a comment or work-note mention, using polling, Flow Designer webhooks, or both.

## Overview

This page is the **second step** in the ServiceNow setup flow:

1. [Setup ServiceNow API Parameters](/docs/Setup/Setup-ServiceNow-API-Params) — save the ServiceNow connection.
2. **ServiceNow Automation (Auto-Pickup)** — *this page* — have Genesis automatically start work on records that match your rules.
3. [ServiceNow Connector Tools](/docs/Genbot-Toolkit/ServiceNow-Connector-Tools) — for ad-hoc, manual ServiceNow operations from inside an agent thread.

Once ServiceNow credentials are configured, Genesis can **automatically start a bot working on a ServiceNow record** when something specific happens — typically when the record is assigned to the Genesis worker identity, enters a configured state, or receives a `@genesis` comment or work-note mention.

There are two ways Genesis hears about record changes, and you can use either or both:

* **Polling (pull)** — Genesis runs a scheduled **ServiceNow Ticket Poller** Flow that searches configured tables for recently updated records and applies your trigger rules. Works in any network topology, including when ServiceNow cannot call Genesis inbound.
* **Webhook (push)** — ServiceNow Flow Designer (or a business rule) POSTs a minimal poke to Genesis at `POST /api/servicenow/webhook`. Lowest latency when outbound REST from ServiceNow is allowed.
* **Hybrid** — both at once. Webhooks deliver normal events; polling acts as a safety net for missed deliveries.

ServiceNow follows the Databricks App polling-only behavior described in
[Jira Automation (Auto-Pickup)](/docs/Setup/Jira-Automation#ingestion-modes).

In all modes, Genesis only **starts agent work** when a record both belongs to your monitored scope and matches your configured trigger rules. Each record gets a stable Genesis thread (`servicenow-<instance>-<table>-<sys_id>`), so follow-up events resume the existing thread instead of starting over.

<Note>
  All ServiceNow automation and worker controls are admin-scoped. You need Genesis admin access or `manage_all_connections` to see the **Automation** and **Genesis worker** tabs in the ServiceNow connection modal on **Config -> Connections**. Open **+ New Connection**, choose **ServiceNow** under **Dev Tools**, or edit an existing ServiceNow connection to switch tabs.
</Note>

## Prerequisites

Before configuring automation, make sure all of the following are true:

1. A **shared** ServiceNow connection has been saved in Genesis with valid credentials. See [Setup ServiceNow API Parameters](/docs/Setup/Setup-ServiceNow-API-Params). Personal connections cannot be selected for automation, and neither can a User OAuth connection, where each person signs in: automation runs with no person signed in, so it needs an integration-user or client-credentials connection.
2. You know which ServiceNow tables Genesis should monitor (for example `incident`, `change_request`).
3. You have decided which Genesis bot should pick up records. The default is `Eve`.
4. (Recommended) You have a dedicated ServiceNow user (for example `genesis.eve`) that customers can assign tickets to, with the **itil** role or equivalent for the monitored tables.
5. (Webhook mode only) Your ServiceNow instance can reach the Genesis backend over HTTPS for outbound REST.

## Ingestion modes

Configure the ingestion mode from the **Automation** tab in the ServiceNow connection modal on **Config -> Connections**.

### Polling (pull) — recommended default

In `polling` mode Genesis owns a scheduled **ServiceNow Ticket Poller** Flow. On each run Genesis:

1. Queries each configured table for records updated since the last successful poll (with a short overlap).
2. ANDs your optional `record_query` encoded filter into every table query.
3. Applies the configured trigger rules to each candidate record.
4. Deduplicates so the same matching condition does not retrigger.
5. For new matches, opens or resumes the record's stable Genesis thread, posts a pickup acknowledgement in ServiceNow (work notes by default), optionally transitions the record to `state_on_pickup`, and dispatches the configured bot.

Polling is the safest default — it works even when ServiceNow cannot make outbound HTTP calls to Genesis, and the Flow is visible in the scheduler.

### Webhook (push)

Genesis exposes `POST /api/servicenow/webhook` as a public-but-signed endpoint. The request body must contain only `table` and `sys_id`:

```json theme={null}
{"table":"incident","sys_id":"<32-char sys_id>"}
```

Sign the **exact raw body** with HMAC-SHA256 using your shared `webhook_secret` and send the digest as `X-Hub-Signature: sha256=<hex digest>`. Genesis re-reads the record from ServiceNow before deciding anything — webhook field values are never trusted.

Use webhook mode when ServiceNow can reach Genesis reliably; otherwise prefer polling or hybrid.

### Hybrid

`hybrid` runs both: webhooks handle normal traffic and polling backfills anything missed.

## Trigger types

Set **Trigger type** to one of:

| Value | Genesis picks up a record when... |
| - | - |
| **`assignment`** | The record's assignee matches **Genesis worker assignee** (`assigned_to`). |
| **`status`** | The record's state matches an entry in **Trigger states**. |
| **`status_or_assignment`** | Either of the above matches. |
| **`comment_keyword`** | A new comment or work note contains a keyword from **Comment/work-note keywords** (default `@genesis`, `genesis`). |
| **`hybrid`** *(default)* | Any of the above matches. |

<Tip>
  For most teams, `hybrid` with **Genesis worker assignee** set to the dedicated ServiceNow user and **Comment/work-note keywords** including `@genesis` produces the best UX: assigning the ticket to **genesis.eve** kicks off work, and a later `@genesis please revise` mention resumes the same Genesis thread.
</Tip>

## Setup workflow

<Steps>
  <Step title="Save the ServiceNow connection">
    Confirm a shared ServiceNow connection has been saved with credentials that can read and write the target tables. See [Setup ServiceNow API Parameters](/docs/Setup/Setup-ServiceNow-API-Params).
  </Step>

  <Step title="Configure the Genesis worker">
    Open **Config -> Connections**, open the ServiceNow connection modal, and select the **Genesis worker** tab. Create or choose the ServiceNow user that represents Genesis (for example `genesis.eve`), then save **ServiceNow worker** (`assigned_to`). Saving also ensures assignment pickup is included in the automation trigger when your trigger type supports it.
  </Step>

  <Step title="Configure automation rules">
    Select the **Automation** tab and set:

    * **Enable ServiceNow automation**: on.
    * **Detection mode**: `polling`, `webhook`, or `hybrid`.
    * **ServiceNow connection**: the saved shared connection.
    * **Genesis bot**: usually `Eve`.
    * **Tables**, **Trigger type**, trigger lists, and optional **Optional encoded query**.
    * **Lifecycle mapping** (state on pickup / needs info / done) and **Writeback journal** (`work_notes` or `comments`).

    Save. If polling or hybrid is selected, Genesis creates or updates the **ServiceNow Ticket Poller** Flow.
  </Step>

  <Step title="(Webhook or hybrid only) Configure Flow Designer">
    Copy the **Genesis webhook URL** and shared HMAC secret from the Automation tab. In ServiceNow Flow Designer, add an outbound REST step after a record is created or updated. Use **Copy Flow Designer setup** in Genesis for a ready-made template. Keep polling enabled as fallback by selecting hybrid mode.
  </Step>

  <Step title="Verify end-to-end">
    Assign a real record in a monitored table to the Genesis worker. Within one poll interval (or immediately in webhook mode), Genesis should open or resume the record's thread, post an acknowledgement, optionally transition state, and start work.
  </Step>
</Steps>

## Automation parameter reference

These fields are saved on the **Automation** tab. Defaults apply when a field is left blank.

| **Field** | **Type** | **Default** | **Notes** |
| - | - | - | - |
| **`enabled`** | Boolean | `false` | Master switch. When off, Genesis ignores all ServiceNow events. |
| **`ingestion_mode`** | String | `polling` | One of `polling`, `webhook`, `hybrid`. |
| **`connection_name`** | String | empty | The `servicenow.<name>` connection Genesis uses for API calls. Empty uses the default ServiceNow connection. |
| **`bot_id`** | String | `Eve` | The Genesis bot that picks up matched records. |
| **`tables`** | Array of strings | `["incident"]` | Tables Genesis polls. Must be on the connector allowlist. |
| **`record_query`** | String | empty | Optional encoded query ANDed into every poll (for example `active=true^priority<=3`). |
| **`trigger_type`** | String | `hybrid` | One of `assignment`, `status`, `status_or_assignment`, `comment_keyword`, `hybrid`. |
| **`assigned_to`** | String | empty | Tracked Genesis worker: `sys_user.user_name`, sys\_id, or display name. Set on the **Genesis worker** tab. |
| **`trigger_on_states`** | Array of strings | `[]` | State values or labels that trigger pickup (for example `1`, `2`). |
| **`trigger_on_comment_keywords`** | Array of strings | `["@genesis", "genesis"]` | Matched against new comments **and** work notes. |
| **`state_on_pickup`** | String | empty | Optional state applied when Genesis picks up the record. |
| **`state_on_needs_info`** | String | empty | Optional state suggested when the agent needs input. |
| **`state_on_done`** | String | empty | Optional state suggested when work finishes. |
| **`writeback_journal_field`** | String | `work_notes` | `work_notes` (internal) or `comments` (customer-visible) for acknowledgements and agent write-backs. |
| **`webhook_secret`** | String (secret) | empty | Shared HMAC secret (minimum 8 characters when set). Required for webhook intake. |
| **`poll_interval_seconds`** | Integer | `60` | Polling cadence. Minimum `30`, maximum `3600`. |
| **`poll_lookback_minutes`** | Integer | `15` | Lookback for the first poll and **Poll now** runs. Minimum `1`, maximum `1440`. |
| **`poll_max_results`** | Integer | `50` | Maximum records examined per table per poll. Minimum `1`, maximum `200`. |

Read-only telemetry fields (`poller_flow_id`, `poller_schedule_status`, `last_successful_poll_at`, `last_poll_error`, and similar) are written by Genesis for operations monitoring.

If the Flow service reports a schedule synchronization failure, Genesis returns a synchronization error instead of reporting that the save succeeded. The automation settings are saved before the Flow is synchronized, so a synchronization error does not roll back those settings.

## Genesis worker reference

The **Genesis worker** tab configures the ServiceNow identity customers assign tickets to. This is separate from the integration user or OAuth app on the **Connection** tab that Genesis uses to call the Table API.

| **Field** | **Purpose** |
| - | - |
| **ServiceNow worker** (`assigned_to`) | User name, sys\_id, or display name that assignment triggers match. Saving binds assignment pickup into the automation trigger when supported. |

Genesis queries live `sys_user` records for suggestions when the selected connection can reach ServiceNow. Manual values still work when live suggestions are unavailable.

## Troubleshooting

### Record assigned to Genesis worker but nothing happens

Check, in order:

1. ServiceNow automation is **enabled**.
2. The record's table is listed in **Tables** and satisfies **Optional encoded query**.
3. **Genesis worker assignee** matches the actual assignee in ServiceNow.
4. In polling mode, the **ServiceNow Ticket Poller** Flow status is `scheduled` and `last_poll_error` is empty.
5. The configured `bot_id` exists and is online.

### Webhook deliveries are rejected

When `webhook_secret` is set, ServiceNow must send `X-Hub-Signature: sha256=<hmac-hexdigest>` over the exact request body. Re-paste the secret on both sides. Webhook intake is disabled when the secret is unset.

### `@genesis` mentions do not wake Genesis

1. `trigger_type` includes comment wakeups (`comment_keyword` or `hybrid`).
2. `trigger_on_comment_keywords` includes the mention text.
3. In polling mode, the comment or work note was posted after the last successful poll cursor.

## Observing automation activity

Every detection, claim, dispatch, suppressed duplicate, and failure is recorded
See [Requests](/docs/User-Guide/Work-Center) for ServiceNow intake activity.

The **Automation** tab in the ServiceNow connection modal includes a **View requests →** link to the Requests page.

## Related pages

* [Setup ServiceNow API Parameters](/docs/Setup/Setup-ServiceNow-API-Params)
* [ServiceNow Connector Tools](/docs/Genbot-Toolkit/ServiceNow-Connector-Tools)
* [Connections](/docs/Setup/Connections)
* [Flows / Scheduler](/docs/User-Guide/Flows)