servicenow-ai-bridge

name

servicenow-ai-bridge

description

Use this skill when the user wants to: - Create, read, update, or query any record in ServiceNow - Build ServiceNow applications (scoped apps, business rules, scheduled jobs, etc.) - Create any ServiceNow artifacts programmatically - Deploy Scripted REST APIs with custom namespaces - Automate ServiceNow development and administration Keywords: ServiceNow, AI bridge, GlideRecord, scoped app, REST API, business rule, scheduled job, artifact

ServiceNow AI Bridge Skill

This skill enables AI agents like Claude Code to create and manage any artifact in ServiceNow through a REST adapter. Install the XML update set on your ServiceNow instance, and AI agents can then create applications, business rules, scheduled jobs, script includes, and any other ServiceNow artifacts programmatically.

Prerequisites

The ServiceNow AI Bridge update set must be installed on the target ServiceNow instance. The user should have:

1. Deployed the "REST adapter for AI agents" XML update set to their ServiceNow instance
2. ServiceNow admin credentials

Adapter Base URL

The adapter is always available at:

https://{instance}.service-now.com/api/1851835/ai_adapter_rest

The namespace 1851835 is hardcoded in the update set, so no lookup is required.

Why Use the Adapter?

ServiceNow's Table API has critical limitations:

Limitation	Impact
Records go to global scope	getSessionToken() returns null
sys_scope parameter ignored on creation	Cannot deploy to scoped apps
Custom namespace ignored for REST APIs	URLs get auto-assigned like /api/1851835/...
Some fields are read-only	Cannot set certain system fields

The adapter uses GlideRecord internally, which has none of these limitations.

Environment Setup

Before making API calls, ask the user for these credentials:

SERVICENOW_INSTANCE=https://devXXXXXX.service-now.com
SERVICENOW_USER=admin
SERVICENOW_PASSWORD=<password>

The adapter base URL is always:

https://{instance}/api/1851835/ai_adapter_rest

API Reference

Authentication

All requests require Basic Auth with admin credentials:

curl -u "admin:password" ...

GET - Query Records

GET /api/1851835/ai_adapter_rest/{tableName}

Query Parameters:

• sysparm_query - Encoded query string (e.g., name=My App)
• sysparm_fields - Comma-separated fields to return
• sysparm_limit - Max records (default: 100)
• sysparm_offset - Pagination offset
• sysparm_display_value - true, false, or all
• sys_id - Get single record by sys_id

Examples:

# Get all scoped applications
GET /api/1851835/ai_adapter_rest/sys_app

# Query with filter
GET /api/1851835/ai_adapter_rest/sys_properties?sysparm_query=name=x_myapp.html

# Get specific record
GET /api/1851835/ai_adapter_rest/sys_ws_definition?sys_id=abc123

# Get specific fields only
GET /api/1851835/ai_adapter_rest/sys_app?sysparm_fields=name,scope,sys_id

POST - Create Record

POST /api/1851835/ai_adapter_rest/{tableName}
Content-Type: application/json

{
  "data": {
    "field1": "value1",
    "field2": "value2",
    "sys_scope": "<scope_sys_id>",
    "sys_package": "<scope_sys_id>"
  }
}

Special Fields:

• sys_scope - Set the scope of the record (sys_id of sys_app)
• sys_package - Usually same as sys_scope for scoped apps
• namespace - For sys_ws_definition, controls the API URL path

PUT/PATCH - Update Record

PUT /api/1851835/ai_adapter_rest/{tableName}/{sysId}
Content-Type: application/json

{
  "data": {
    "field1": "new_value"
  }
}

Update by query (use _ as sys_id placeholder):

PUT /api/1851835/ai_adapter_rest/sys_properties/_?sysparm_query=name=x_myapp.html

Response Format

Success:

{
  "result": {
    "sys_id": "abc123...",
    "table": "sys_app",
    "name": "My App",
    "sys_scope": "abc123...",
    "sys_scope_display": "My App"
  },
  "meta": {
    "fields_set": ["name", "scope"],
    "fields_skipped": [],
    "message": "Record created successfully"
  }
}

Error:

{
  "error": {
    "message": "Record not found",
    "detail": "No record with sys_id \"xyz\" in table \"sys_app\""
  }
}

Common Workflows

Create a Scoped Application

POST /api/1851835/ai_adapter_rest/sys_app
{
  "data": {
    "name": "My Custom App",
    "scope": "x_myorg_app",
    "short_description": "Description of my app"
  }
}
# Returns: sys_id of the new scope

Create REST API in Custom Scope

# 1. First create the scoped app (see above)
# 2. Create REST API with proper scope
POST /api/1851835/ai_adapter_rest/sys_ws_definition
{
  "data": {
    "name": "My API",
    "namespace": "x_myorg_app",
    "sys_scope": "<scope_sys_id>",
    "sys_package": "<scope_sys_id>",
    "active": "true"
  }
}
# Returns: base_uri shows the actual API path (e.g., /api/x_myorg_app/my_api)

Create REST Endpoint in Scope

POST /api/1851835/ai_adapter_rest/sys_ws_operation
{
  "data": {
    "name": "Get Token",
    "http_method": "GET",
    "relative_path": "/get_token",
    "web_service_definition": "<api_sys_id>",
    "requires_authentication": "false",
    "requires_snc_internal_role": "false",
    "operation_script": "(function process(request, response) { ... })(request, response);",
    "sys_scope": "<scope_sys_id>",
    "sys_package": "<scope_sys_id>"
  }
}

Create/Update System Property

# Create
POST /api/1851835/ai_adapter_rest/sys_properties
{
  "data": {
    "name": "x_myorg_app.config",
    "type": "string",
    "value": "configuration content here",
    "sys_scope": "<scope_sys_id>",
    "sys_package": "<scope_sys_id>"
  }
}

# Update by name
PUT /api/1851835/ai_adapter_rest/sys_properties/_?sysparm_query=name=x_myorg_app.config
{
  "data": {
    "value": "updated content"
  }
}

Key Tables Reference

Table	Purpose	Key Fields
sys_app	Scoped applications	name, scope, short_description
sys_ws_definition	Scripted REST APIs	name, namespace, base_uri, sys_scope
sys_ws_operation	REST endpoints	name, http_method, relative_path, operation_script, web_service_definition
sys_properties	System properties	name, type, value, sys_scope
sys_script_include	Server-side scripts	name, script, api_name, sys_scope
sys_script	Business rules	name, script, collection, when, sys_scope
sysauto_script	Scheduled jobs	name, script, run_type, sys_scope
sys_ui_page	UI pages	name, html, client_script, sys_scope

Important Notes

1. Always query first - Before creating, check if a record already exists
2. Save sys_ids - Store returned sys_ids for subsequent operations (e.g., scope sys_id for all scoped artifacts)
3. Check base_uri - For REST APIs, the actual URL is in base_uri, not derived from namespace
4. Scope consistency - Set both sys_scope and sys_package to the same scope sys_id
5. Authentication - The adapter requires admin credentials; all operations respect ACLs

Error Handling

If a request fails:

1. Check HTTP status code (400 = bad request, 404 = not found, 500 = server error)
2. Read the error.detail field for specific information
3. Verify table name is correct
4. Ensure all required fields are provided
5. Check for duplicate key constraints (unique names, scopes)