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

# Connect ServiceNow to Athena: Records, Knowledge, and Setup

> ServiceNow setup covers OAuth app registration in your instance, workspace configuration, member sign-in, record and knowledge tools, approval-gated writes, and troubleshooting.

Connect your ServiceNow instance to Athena so each member can search records,
read tickets with their comments and work notes, search knowledge articles,
and update records as their **own ServiceNow account**. Your ServiceNow
roles, ACLs and data policies apply unchanged. Athena sees exactly what you
can see in ServiceNow, nothing is shared through a service account, and every
change Athena makes is recorded under your name.

<Info>
  Setup involves two people. Your **ServiceNow administrator** registers an
  OAuth application in your instance. **Athena Intelligence** then registers
  that application for your workspace. Members can only connect after both
  are done.
</Info>

## Step 1 — Register an OAuth application in ServiceNow (ServiceNow admin)

Register one application per instance. If members should connect both
production and a sub-production instance, register one in each.

1. In your instance, go to **System OAuth → Application Registry → New** and
   choose **Create an OAuth API endpoint for external clients**.
2. Name it, for example `Athena`, and set the **Redirect URL**:

   ```text theme={null}
   https://api.athenaintel.com/api/direct-connectors/servicenow_direct/oauth/callback
   ```

   For private or VPC deployments, replace `api.athenaintel.com` with your
   environment's Athena API host. ServiceNow requires an exact match.
3. Leave **Public Client** off.
4. Keep a non-zero **Refresh Token Lifespan**. The default is 100 days.
   Athena refuses a connection that comes back without a refresh token.
5. Save the record, then copy the **Client ID** and the generated **Client
   Secret**.
6. Send the Client ID, the Client Secret and your instance address (for
   example `acme.service-now.com`) to Athena Intelligence through a secure
   channel.

<Info>
  By default the application uses ServiceNow's standard `useraccount` scope:
  Athena can do what the signed-in member can do, and nothing more. To fence
  Athena to specific REST APIs, create a custom auth scope and attach it to
  those APIs under **REST API Auth Scopes**. Then ask Athena Intelligence to
  request that scope instead. The scope must cover the Table API
  (`/api/now/table`) and the current-user lookup (`/api/now/ui/user`).
</Info>

## Step 2 — Athena registers the application for your workspace

Athena Intelligence adds a `servicenow_direct` integration for your
workspace. It holds the Client ID, the encrypted Client Secret and your
instance host. Secrets are encrypted at rest and never returned to the
browser. Once the integration is saved, the **ServiceNow** card on the
Integrations page is available to every member. Until then, the card says
the integration isn't set up for the workspace yet.

## Step 3 — Connect your account (each member)

1. Navigate to
   **[Integrations](https://app.athenaintel.com/dashboard/integrations/)** and
   click **Connect ServiceNow** on the **ServiceNow** card, under **Project
   Management & Ticketing**.
2. Your instance's sign-in page opens in a popup. Sign in if you are not
   already, then click **Allow**. There is no picker step on the Athena side:
   Athena stores your encrypted tokens and confirms the connection with your
   ServiceNow email.
3. If your workspace has more than one instance registered, pick the
   instance before connecting. To add another instance later, click **Connect
   another ServiceNow instance**.

## What Athena can do

Once connected, the **ServiceNow toolkit** gives agents these tools.

| Tool | What it does | Approval |
| - | - | - |
| List ServiceNow Instances | Lists your connected instances and the ServiceNow account each uses | No |
| Search ServiceNow Records | Searches any table you can read: incidents, requests, changes, problems, catalog tasks, configuration items, users, or custom tables. Supports filters, sorting and paging. | No |
| Get ServiceNow Record | Reads one record by number (`INC0010001`) or sys\_id, optionally with its additional comments and work notes | No |
| Search ServiceNow Knowledge | Searches published knowledge articles by keyword and reads their text | No |
| Create ServiceNow Record | Creates a record, such as an incident or request task, under your name | **Yes**, every time |
| Update ServiceNow Record | Changes fields of a record, such as state, assignment or close notes | **Yes**, every time |
| Add ServiceNow Comment | Adds a work note (internal) or an additional comment (visible to the caller or requester) | **Yes**, every time |
| Search ServiceNow Catalog | Lists the Service Catalog items you may order, optionally matching search words | No |
| Get ServiceNow Catalog Item | Reads a catalog item's description and the questions on its order form | No |
| Order ServiceNow Catalog Item | Orders a catalog item with your answers to its form, the same as **Order now** in the service portal; returns the request number | **Yes**, every time |

A few behaviors to know:

* **Plain-language requests work.** Ask "show my open P1 incidents" or
  "summarize the work notes on INC0012345". Athena builds the ServiceNow query
  for you.
* **Reference and choice fields show two values.** For example,
  `Beth Anglin [46d4…]` or `In Progress [2]`. The second value is what
  ServiceNow stores, and Athena uses it when it updates a record.
* **Notes are internal by default.** Athena adds a work note unless you ask
  for a customer-visible comment.
* **Platform tables are never written.** Athena never writes ServiceNow
  platform tables (`sys_*`), whatever your roles allow.
* **Read tools work in automations.** The read tools can run as steps, as the
  member who runs them. Write tools are available only in chat, where you can
  approve them.

## Run automations when records change

Your ServiceNow instance can tell Athena when a record is created or updated,
so an automation can run on it: triage a new P1 incident, for example, or
summarize a change request when its state moves.

1. Ask Athena Intelligence for your instance's webhook details. You receive a URL, a secret and a Business Rule script.
2. In ServiceNow, go to **System Properties** and create the property named in the webhook details (it starts with `athena.webhook.secret.`) with type **password2**. Set its value to the secret.
3. Go to **System Definition › Business Rules › New**. Pick the table to watch, for example **Incident**. Set **When** to **after**, check **Insert** and **Update**, turn on **Advanced**, and paste the script. The script sends the change from a background job, so saving a record never waits on Athena, and it retries a failed delivery a few times.

Automations can then use these events:

* `servicenow.incident.created` and `servicenow.incident.updated`
* `servicenow.record.created` and `servicenow.record.updated`, for other tables

Each event carries the record's number, short description, state, priority,
assignment, a link to the record, and the fields that changed.

## Use ServiceNow from a computer

On a computer with your ServiceNow connection
attached under **Connected Catalogs**:

* `SERVICENOW_INSTANCE_URL` holds your instance's address.
* `SERVICENOW_API_URL` holds its REST base, `https://<instance>/api/now`.
* `athena-catalog-token servicenow_direct` prints a short-lived access token
  for your connection.

```bash theme={null}
curl -H "Authorization: Bearer $(athena-catalog-token servicenow_direct)" \
  "$SERVICENOW_API_URL/table/incident?sysparm_query=active=true&sysparm_limit=5"
```

`athena-catalog-token` returns the current token while it is fresh and gets
a new one otherwise. With more than one ServiceNow instance attached, pass the
catalog's asset ID instead of `servicenow_direct`. The computer acts as you, so anyone you share it with
can use your ServiceNow access from it: attach your connection only to a
computer you don't share.

## Token lifecycle & troubleshooting

* **Everything is per-user.** Results always reflect *your* ServiceNow roles
  and ACLs, and every change is attributed to you.
* **"Reconnect ServiceNow."** A connection lasts as long as the application's
  refresh token lifespan (100 days by default). An administrator can also
  revoke it under **System OAuth → Manage Tokens**. Either way, reconnecting
  from the Integrations page fixes it.
* **"Invalid redirect\_uri" in the popup.** The application's Redirect URL
  doesn't exactly match the one in step 1.2.
* **"ServiceNow did not accept the new sign-in."** The instance refused
  Athena's request to identify you. If you use a custom auth scope, make sure
  it covers the Table API and the current-user lookup.
* **"Your roles or ACLs do not allow it."** ServiceNow refused the request for
  your account, for example because you lack the `itil` role needed for
  incidents. Ask your ServiceNow administrator for the role. Athena cannot
  widen your access.
* **Rate limits.** If your instance limits REST requests, Athena reports how
  long to wait instead of retrying.

## Disconnecting

Open the ServiceNow connection in Athena and click **Disconnect**. Athena
revokes its access on your instance and removes your stored tokens. Other
instances you connected stay connected.


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