> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ServiceNow
> Manage ServiceNow ITSM tickets, change requests, problems and the service catalog from Agent Factory agents and Builder workflows
The ServiceNow app exposes the [ServiceNow](https://www.servicenow.com) ITSM platform through its Table API. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as tools, or as a Builder app whose instructions you call directly from DSUL. It covers incidents, change requests, problems, the service catalog, requests, attachments, users and groups — plus a generic table accessor for any other ServiceNow table.
Authentication is a **per-workspace credential** resolved server-side: either **Basic Auth** (a ServiceNow user with the right roles) or an **OAuth2 client** (`client_credentials` grant). Agents are identified by the capability **Scope** `context_id,agent_id,user_id`; the credential is never passed through the agent.
Create, read, update and transition incidents, change requests and problems with work notes and close codes.
List and inspect catalog items, then order them with their variables — creating a request and request item.
Query any ServiceNow table with encoded queries, fetch records by sys\_id, and compute aggregate statistics.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to manage ServiceNow tickets. → *Agent builder* tab.
You run the platform and want to publish ServiceNow as a reusable capability. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call ServiceNow operations directly. → *Workspace builder* tab.
## Prerequisites (ServiceNow side)
* A **ServiceNow** instance — its URL has the form `https://.service-now.com`.
* A **credential**, one of:
* **Basic Auth** — a ServiceNow user (username + password) holding the roles needed for the tables you target.
* **OAuth2 client** (`client_credentials` grant) — create an **Application Registry** in ServiceNow under **System OAuth > Application Registry** and note its **Client ID** / **Client Secret**.
* The **roles** for the tables you intend to use: `itil` for incidents, `change_manager` for change requests, `problem_manager` for problems, `sn_request_write` for catalog requests, and a table-specific role for anything else. The generic table tools are ACL-filtered by the account's effective roles.
**Goal:** ServiceNow is a **per-workspace** connector — each workspace pastes its own ServiceNow credential (see the *Workspace builder* tab), so there is **no platform-wide credential to provision**. The only optional platform task is to publish ServiceNow as a reusable **capability** in AI Governance so agent builders can enable it from the catalog instead of pasting a raw MCP endpoint.
There is no shared ServiceNow credential and no central OAuth client for this connector. The ServiceNow instance URL and credentials (Basic or OAuth2) always live in the consuming workspace. A Governance capability you publish here points at a specific workspace's MCP endpoint; that workspace still owns the credential.
## Declare the capability in AI Governance (optional)
Create (or edit) the **ServiceNow** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint** (the workspace running the connector), and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant.
Declaring the capability makes the connector **available**; it does not by itself authorize a specific agent against a ServiceNow instance. The ServiceNow credential is resolved server-side from the workspace running the connector, and ServiceNow ACLs (the account's effective roles) are the final authorization boundary. There is **no OAuth auth-config JSON** to attach in Governance: authentication is a server-side Basic or `client_credentials` credential, not a per-user OAuth flow.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory manage ServiceNow tickets through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the ServiceNow app in a workspace (see the *Workspace builder* tab). Optionally, a *Platform admin* may have published a ServiceNow capability in AI Governance (see the *Platform admin setup* accordion above).
The ServiceNow credential (Basic or OAuth2) is resolved server-side from the workspace's app configuration — it is never exposed to the agent. Your agent is identified by the `agent_id` that Agent Factory injects through the capability *Scope*.
Follow the *Workspace builder* tab: install **ServiceNow** in a workspace, then fill in the instance URL and credentials (Basic or OAuth2).
In your agent, add a capability pointing at the workspace's **MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` is what lets the connector identify your agent. The server URL is the connector's MCP Endpoint, auto-populated when the app is installed.
The agent now has access to every ServiceNow tool exposed by the MCP server.
## Brief the agent in its system prompt
Wiring the capability is not enough — the agent also needs to know the tools exist and when to use them. Add a short paragraph to the agent's system prompt. Copy-pasteable starter:
```text theme={null}
You have access to the ServiceNow MCP server. Use it whenever the user asks about ITSM data — incidents, change requests, problems, requested items, the service catalog, attachments, users or groups. Examples: "List my open incidents", "Create a change request for the database upgrade tonight", "What's the status of INC0012345?", "Order a new laptop from the catalog". Prefer calling MCP tools directly over guessing, and confirm with the user before any destructive action (resolve an incident, close a problem, transition a change).
```
Refine the trigger keywords (assignment groups, ticket prefixes, catalog item names) so the agent reliably picks up the right intent in your context.
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent's identity is still propagated so the connector can read its `agent_id`.
## Available Tools
### Generic Table Access
| Tool | Description |
| -------------- | ---------------------------------------------------------------------- |
| `queryRecords` | Query any ServiceNow table using encoded query syntax |
| `getRecord` | Get a single record from any table by `sys_id` |
| `getStats` | Aggregate statistics for a table (count, sum, avg, min, max, group by) |
### Incidents
| Tool | Description |
| ---------------- | -------------------------------------------------------------------------------- |
| `listIncidents` | List incidents (state / priority / assignedTo / assignmentGroup filters) |
| `getIncident` | Get an incident by `sysId` or `number` |
| `createIncident` | Create an incident |
| `updateIncident` | Update an incident (supports `workNotes`, `comments`, `closeCode`, `closeNotes`) |
### Change Requests
| Tool | Description |
| ---------------------- | --------------------------------------------------- |
| `listChanges` | List change requests |
| `getChange` | Get a change request |
| `createChange` | Create a `normal` / `standard` / `emergency` change |
| `updateChange` | Update a change request |
| `getChangeTransitions` | Get available state transitions |
| `transitionChange` | Transition to a new state |
### Problems
| Tool | Description |
| --------------- | ------------------------------------------------------------------ |
| `listProblems` | List problems |
| `getProblem` | Get a problem |
| `createProblem` | Create a problem |
| `updateProblem` | Update a problem (supports `workaround`, `causeNotes`, `fixNotes`) |
### Service Catalog
| Tool | Description |
| ------------------ | ------------------------------------------------------- |
| `listCatalogItems` | List available catalog items |
| `getCatalogItem` | Get a catalog item with its variables (form fields) |
| `orderCatalogItem` | Order a catalog item (creates a request + request item) |
### Requests & Request Items
| Tool | Description |
| ------------------ | ----------------------------------------------------------------- |
| `listRequests` | List service catalog requests |
| `getRequest` | Get a service catalog request |
| `listRequestItems` | List request items (RITMs), optionally filtered by parent request |
### Attachments, Users & Groups
| Tool | Description |
| ------------------ | ----------------------------------- |
| `listAttachments` | List attachments on a record |
| `uploadAttachment` | Upload a file (base64) to a record |
| `listUsers` | List ServiceNow users |
| `getUser` | Get a user by `sysId` or `username` |
| `listGroups` | List ServiceNow user groups |
## Output Formats
Tools return the underlying ServiceNow Table API JSON. Most list and get operations accept a `displayValue` argument that controls how reference and choice fields are rendered:
* **`false`** — raw `sys_id` values (the default for most fields).
* **`true`** — human-readable labels.
* **`all`** — both, under `value` and `display_value`.
List operations also accept `limit`, `offset` and `fields` (comma-separated) to control the response size and shape.
## Tool Details
### queryRecords
Query any ServiceNow table using the [encoded query](https://docs.servicenow.com/bundle/utah-platform-administration/page/use/using-lists/concept/c_EncodedQueryStrings.html) syntax.
```json theme={null}
{
"name": "queryRecords",
"arguments": {
"tableName": "incident",
"query": "active=true^priority=1^assignment_groupSTARTSWITHNetwork",
"fields": "number,short_description,assigned_to,priority",
"limit": 50,
"displayValue": "all"
}
}
```
| Parameter | Required | Description |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| `tableName` | Yes | `incident`, `change_request`, `problem`, `sc_req_item`, `sys_user`, … |
| `query` | No | Encoded query (operators: `=`, `!=`, `STARTSWITH`, `CONTAINS`, `IN`, `^`, `^OR`, …) |
| `fields` | No | Comma-separated field names to return |
| `limit` | No | Max records (default 20) |
| `offset` | No | Pagination offset |
| `displayValue` | No | `true` / `false` / `all` |
### createIncident
```json theme={null}
{
"name": "createIncident",
"arguments": {
"shortDescription": "VPN disconnects every 10 minutes",
"callerId": "caller-sys-id",
"category": "network",
"impact": "2",
"urgency": "2",
"assignmentGroup": "Network Support",
"contactType": "email"
}
}
```
| Parameter | Required | Description |
| -------------------------------- | -------- | ---------------------------------------------------------- |
| `shortDescription` | Yes | Brief description of the incident |
| `callerId` | No | Caller `sys_id` |
| `category` / `subcategory` | No | Classification |
| `impact` / `urgency` | No | `1` / `2` / `3` — ServiceNow derives `priority` from these |
| `assignmentGroup` / `assignedTo` | No | Routing |
| `cmdbCi` | No | Affected configuration item `sys_id` |
| `contactType` | No | How reported: `email`, `phone`, `walk-in`, … |
### updateIncident
```json theme={null}
{
"name": "updateIncident",
"arguments": {
"sysId": "incident-sys-id",
"state": "6",
"closeCode": "Solved (Permanently)",
"closeNotes": "Rolled back the firmware to 7.2.1."
}
}
```
| Parameter | Required | Description |
| -------------------------- | -------- | ----------------------------------------------------------------------------- |
| `sysId` | Yes | Incident `sys_id` |
| `state` | No | `1` New, `2` In Progress, `3` On Hold, `6` Resolved, `7` Closed, `8` Canceled |
| `workNotes` | No | Internal work notes (appended) |
| `comments` | No | Customer-visible comments (appended) |
| `closeCode` / `closeNotes` | No | Required by most workflows when resolving |
### transitionChange
Call `getChangeTransitions` first to discover which target states are legal for a given change, then transition:
```json theme={null}
{
"name": "transitionChange",
"arguments": {
"sysId": "change-sys-id",
"state": "-2"
}
}
```
| Parameter | Required | Description |
| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sysId` | Yes | Change request `sys_id` |
| `state` | Yes | Target state value. Common (model-dependent): `-5` New, `-4` Assess, `-3` Authorize, `-2` Scheduled, `-1` Implement, `0` Review, `3` Closed, `4` Canceled |
### orderCatalogItem
```json theme={null}
{
"name": "orderCatalogItem",
"arguments": {
"sysId": "catalog-item-sys-id",
"quantity": 1,
"variables": {
"laptop_model": "macbook_pro_16",
"delivery_date": "2026-05-01"
}
}
}
```
| Parameter | Required | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `sysId` | Yes | Catalog item `sys_id` |
| `quantity` | No | Quantity (default 1) |
| `variables` | No | Object of form field values. Keys must match the item's variable names — call `getCatalogItem` first to discover them |
### uploadAttachment
```json theme={null}
{
"name": "uploadAttachment",
"arguments": {
"tableName": "incident",
"tableSysId": "incident-sys-id",
"fileName": "vpn-logs.txt",
"contentBase64": "VlBOIGxvZ3MgY29udGVudC4uLg==",
"contentType": "text/plain"
}
}
```
| Parameter | Required | Description |
| --------------- | -------- | ------------------------------------------------ |
| `tableName` | Yes | Table the record belongs to |
| `tableSysId` | Yes | Record `sys_id` |
| `fileName` | Yes | Attachment file name |
| `contentBase64` | Yes | File content as a base64 string |
| `contentType` | No | MIME type (e.g. `text/plain`, `application/pdf`) |
Max attachment size is set by the instance (default 1 GB via `com.glide.attachment.max_size`, but most instances restrict it further).
## Workspace builder
**Goal:** install the connector in a workspace, configure the ServiceNow credential, and call its instructions from your automations.
## Installation
1. Go to **Apps** in your workspace
2. Search for **ServiceNow** and install it
3. Open the app instance configuration and fill in the instance URL and credentials (Basic or OAuth2)
## Configuration
| Field | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Instance URL** | `https://.service-now.com` — full URL with scheme |
| **Authentication Type** | `basic` or `oauth2` |
| **Username** / **Password** | Required when `authType = basic` (stored as workspace secrets) |
| **OAuth2 Client ID** / **Client Secret** | Required when `authType = oauth2` — uses the `client_credentials` grant (Client Secret stored as a workspace secret) |
| **MCP Endpoint** | Auto-populated on install — the URL of the MCP endpoint for this instance, used to wire the connector into an agent capability |
The credential you provide selects the auth mode:
| Auth mode | What you provide | Best for |
| -------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Basic Auth** (`authType: basic`) | A ServiceNow username + password | Quick setup; reuses an existing technical user and its roles |
| **OAuth2 client credentials** (`authType: oauth2`) | Client ID + Client Secret from an Application Registry | Token-based, server-to-server; the connector exchanges them at `/oauth_token.do` and caches the bearer |
Credentials are stored as workspace secrets and resolved server-side on every call. Switch modes by editing the app instance configuration; no instruction lets you change credentials at runtime.
## Available Instructions
Every instruction resolves the credential from the workspace configuration. Most list operations accept `limit`, `offset`, `fields` (comma-separated) and `displayValue` (`true` / `false` / `all`) to control the response shape.
### Generic Table Access
| Instruction | Description | Returns |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `queryRecords` | Query any table by `tableName` (required) using an encoded `query`. `fields`, `limit`, `offset`, `displayValue` shape the response. | `{ result: [ { …record fields } ] }` |
| `getRecord` | Get one record by `tableName` (required) + `sysId` (required). | `{ result: { …record fields } }` |
| `getStats` | Aggregate statistics for `tableName` (required): `count`, `sumFields`, `avgFields`, grouped by `groupBy`, filtered by `query`. | `{ result: { stats: { count, … }, groupby_fields } }` |
### Incidents
| Instruction | Description | Returns |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `listIncidents` | List incidents filtered by `state`, `priority`, `assignedTo`, `assignmentGroup` and/or a raw `query`. | `{ result: [ { sys_id, number, short_description, … } ] }` |
| `getIncident` | Get one incident by `sysId` **or** `number` (e.g. `INC0010001`). | `{ result: { sys_id, number, state, … } }` |
| `createIncident` | Create an incident. `shortDescription` (required); plus `callerId`, `category`, `impact`, `urgency`, `assignmentGroup`, `contactType`, … | `{ result: { sys_id, number, … } }` |
| `updateIncident` | Update an incident by `sysId` (required). Supports `state`, `workNotes`, `comments`, `closeCode`, `closeNotes`, reassignment. | `{ result: { sys_id, number, state, … } }` |
### Change Requests
| Instruction | Description | Returns |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `listChanges` | List change requests filtered by `state`, `priority`, `type` (`normal`/`standard`/`emergency`), assignment and/or `query`. | `{ result: [ { sys_id, number, … } ] }` |
| `getChange` | Get one change request by `sysId` (required). | `{ result: { sys_id, number, state, … } }` |
| `createChange` | Create a change. `changeType` + `shortDescription` (required); plus `risk`, `impact`, `startDate`, `endDate`, `implementationPlan`, `backoutPlan`, `testPlan`, … Dates use `YYYY-MM-DD HH:mm:ss`. | `{ result: { sys_id, number, … } }` |
| `updateChange` | Update a change by `sysId` (required): schedule, plans, assignment, `workNotes`, … | `{ result: { sys_id, number, … } }` |
| `getChangeTransitions` | List the legal target states for a change by `sysId` (required). | `{ transitions: [ { state, label } ] }` |
| `transitionChange` | Move a change to a target `state` (required) by `sysId` (required). | `{ result: { sys_id, state, … } }` |
### Problems
| Instruction | Description | Returns |
| --------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `listProblems` | List problems filtered by `state`, `priority`, assignment and/or `query`. | `{ result: [ { sys_id, number, … } ] }` |
| `getProblem` | Get one problem by `sysId` (required). | `{ result: { sys_id, number, … } }` |
| `createProblem` | Create a problem. `shortDescription` (required); plus `category`, `impact`, `urgency`, assignment, `cmdbCi`. | `{ result: { sys_id, number, … } }` |
| `updateProblem` | Update a problem by `sysId` (required). Supports `state`, `workaround`, `causeNotes`, `fixNotes`, `workNotes`. | `{ result: { sys_id, number, … } }` |
### Service Catalog
| Instruction | Description | Returns |
| ------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `listCatalogItems` | List catalog items, optionally filtered by `catalog`, `category` or `query`. | `{ result: [ { sys_id, name, short_description } ] }` |
| `getCatalogItem` | Get one catalog item with its variables (form fields) by `sysId` (required). | `{ result: { sys_id, name, variables: [ … ] } }` |
| `orderCatalogItem` | Order an item by `sysId` (required), with `quantity` and a `variables` object of form values. | `{ result: { request_id, request_number, sys_id } }` |
### Requests & Request Items
| Instruction | Description | Returns |
| ------------------ | --------------------------------------------------------------------------------- | --------------------------------------- |
| `listRequests` | List service catalog requests, optionally filtered by `query`. | `{ result: [ { sys_id, number, … } ] }` |
| `getRequest` | Get one request by `sysId` (required). | `{ result: { sys_id, number, … } }` |
| `listRequestItems` | List request items (RITMs), optionally filtered by parent `requestId` or `query`. | `{ result: [ { sys_id, number, … } ] }` |
### Attachments, Users & Groups
| Instruction | Description | Returns |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `listAttachments` | List attachments on a record by `tableName` (required) + `tableSysId` (required). | `{ result: [ { sys_id, file_name, content_type, size_bytes } ] }` |
| `uploadAttachment` | Upload a base64 file to a record: `tableName`, `tableSysId`, `fileName`, `contentBase64` (all required) + `contentType`. | `{ result: { sys_id, file_name, download_link } }` |
| `listUsers` | List users, optionally filtered by `active` or `query`. | `{ result: [ { sys_id, user_name, name, email } ] }` |
| `getUser` | Get one user by `sysId` **or** `username`. | `{ result: { sys_id, user_name, name, email } }` |
| `listGroups` | List user groups, optionally filtered by `active` or `query`. | `{ result: [ { sys_id, name } ] }` |
`Returns` shows the shape of the operation output. `displayValue: all` adds a `display_value` alongside each `value` for reference and choice fields.
## DSUL Examples
### Open an incident from a form
```yaml theme={null}
- ServiceNow.createIncident:
shortDescription: VPN disconnects every 10 minutes
description: '{{payload.message}}'
callerId: '{{caller_sys_id}}'
category: network
impact: '2'
urgency: '2'
assignmentGroup: Network Support
contactType: email
output: incident
```
### Assign and resolve
```yaml theme={null}
- ServiceNow.updateIncident:
sysId: '{{incident.sys_id}}'
assignedTo: '{{engineer_sys_id}}'
state: '2'
workNotes: Investigating the VPN concentrator logs.
- ServiceNow.updateIncident:
sysId: '{{incident.sys_id}}'
state: '6'
closeCode: Solved (Permanently)
closeNotes: Rolled back the firmware to 7.2.1.
```
### Query with an encoded query
```yaml theme={null}
- ServiceNow.queryRecords:
tableName: incident
query: active=true^priority=1^assignment_groupSTARTSWITHNetwork
fields: number,short_description,assigned_to,priority
limit: 50
displayValue: all
output: critical
```
### Order a catalog item
```yaml theme={null}
- ServiceNow.getCatalogItem:
sysId: '{{laptop_item_id}}'
output: item
- ServiceNow.orderCatalogItem:
sysId: '{{laptop_item_id}}'
quantity: 1
variables:
laptop_model: macbook_pro_16
delivery_date: 2026-05-01
output: request
```
### Aggregate statistics
```yaml theme={null}
- ServiceNow.getStats:
tableName: incident
query: active=true
count: true
groupBy: priority,assignment_group
output: stats
```
***
## Error Handling
| HTTP Status | Error | Solution |
| ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 | Unauthorized | Verify credentials; for OAuth2, check the `client_credentials` grant is enabled on the Application Registry |
| 403 | Forbidden | The user/client lacks an ACL on the target table — grant `itil`, `change_manager`, `problem_manager`, or a table-specific role |
| 404 | Not Found | Verify the `sys_id` / `number` and that the record is not in a restricted domain |
| 409 | Conflict | The state transition is not allowed — call `getChangeTransitions` to get the valid targets |
| 429 | Rate Limited | The instance returned a `X-RateLimit-*` error — back off; ServiceNow also enforces per-user transaction quotas |
| 500 | Server Error | A ServiceNow business rule or script failed — check the instance's system logs |
### Common Issues
**"ServiceNow not configured"** — `instanceUrl` is missing from the app config. Paste the full URL with scheme (`https://acme.service-now.com`).
**"Basic Auth requires username and password"** — `authType` is `basic` but one credential is empty. Either fill both or switch to `oauth2`.
**"OAuth2 requires clientId and clientSecret"** — `authType` is `oauth2` but the client credentials are missing. Create an **Application Registry** in ServiceNow (**System OAuth > Application Registry**) with the `client_credentials` grant and paste its Client ID / Client Secret.
**Empty results with a seemingly valid query** — encoded queries are case-sensitive and ACL-filtered. Try `displayValue: all` and verify the effective roles of the account; a record outside the account's domain is silently excluded.
## External Resources
Official Table API reference
Operators and syntax for the `query` argument
Create an OAuth Application Registry
Learn how Agent Factory agents consume MCP tools in Prisme.ai.