servicenow-agent

---
name: servicenow-agent
description: Read-only CLI access to ServiceNow Table, Attachment, Aggregate, and Service Catalog APIs; includes schema inspection and history retrieval (read-only).
read_when:
  - Need to read ServiceNow Table API records
  - Need to query a table or fetch a record by sys_id
  - Need to download attachment content or metadata
  - Need aggregate statistics or service catalog variables
metadata: {"clawdbot":{"emoji":"🧾","requires":{"bins":["node"]}}}
---

# ServiceNow Table API Read Only

Use this skill to read data from ServiceNow via the Table API. Do not create or update or delete records.

## Configuration

Set these environment variables in the .env file in this folder.

- SERVICENOW_DOMAIN instance domain such as myinstance.service-now.com
- SERVICENOW_USERNAME username for basic auth
- SERVICENOW_PASSWORD password for basic auth

If your domain already includes https:// then use it as is. Otherwise requests should be made to:

```
https://$SERVICENOW_DOMAIN
```

## Allowed Operations GET only

Use only the GET endpoints from these files.

- openapi.yaml for Table API
- references/attachment.yaml for Attachment API
- references/aggregate-api.yaml for Aggregate API
- references/service-catalog-api.yaml for Service Catalog API

### List records
- GET /api/now/table/{tableName}

### Get a record by sys_id
- GET /api/now/table/{tableName}/{sys_id}

Never use POST or PUT or PATCH or DELETE.

## Common Query Params Table API

- sysparm_query encoded query such as active=true^priority=1
- sysparm_fields comma separated fields to return
- sysparm_limit limit record count to keep small for safety
- sysparm_display_value true or false or all
- sysparm_exclude_reference_link true to reduce clutter

See openapi.yaml for the full list of parameters.

## CLI

Use the bundled CLI for all reads. It pulls auth from .env by default. You can override with flags.

### Command overview

- list table lists records from a table
- get table sys_id fetches one record by sys_id
- batch file.json runs multiple read requests in one call
- attach reads attachments and file content
- stats table aggregates stats
- schema table lists valid field names and types
- history table sys_id reads full comment and work note timeline
- sc endpoint Service Catalog GET endpoints

### Auth flags

- --domain domain instance domain
- --username user
- --password pass

### Query flags

Use any of these as --sysparm_* flags.

- --sysparm_query
- --sysparm_fields
- --sysparm_limit
- --sysparm_display_value
- --sysparm_exclude_reference_link
- --sysparm_suppress_pagination_header
- --sysparm_view
- --sysparm_query_category
- --sysparm_query_no_domain
- --sysparm_no_count

### Attachment API params

- --sysparm_query
- --sysparm_suppress_pagination_header
- --sysparm_limit
- --sysparm_query_category

### Aggregate API params

- --sysparm_query
- --sysparm_avg_fields
- --sysparm_count
- --sysparm_min_fields
- --sysparm_max_fields
- --sysparm_sum_fields
- --sysparm_group_by
- --sysparm_order_by
- --sysparm_having
- --sysparm_display_value
- --sysparm_query_category

### Service Catalog params

- --sysparm_view
- --sysparm_limit
- --sysparm_text
- --sysparm_offset
- --sysparm_category
- --sysparm_type
- --sysparm_catalog
- --sysparm_top_level_only
- --record_id
- --template_id
- --mode

### Output

- --pretty pretty print JSON output
- --out path save binary attachment content to a file

### Examples

List recent incidents.

```bash
node cli.mjs list incident --sysparm_limit 5 --sysparm_fields number,short_description,priority,sys_id
```

Query with a filter.

```bash
node cli.mjs list cmdb_ci --sysparm_query "operational_status=1^install_status=1" --sysparm_limit 10
```

Fetch a single record.

```bash
node cli.mjs get incident <sys_id> --sysparm_fields number,short_description,opened_at
```

Override auth on the fly.

```bash
node cli.mjs list incident --domain myinstance.service-now.com --username admin --password "***" --sysparm_limit 3
```

Attachment metadata and file download.

```bash
node cli.mjs attach list --sysparm_query "table_name=incident" --sysparm_limit 5
node cli.mjs attach file <sys_id> --out /tmp/attachment.bin
```

Aggregate stats.

```bash
node cli.mjs stats incident --sysparm_query "active=true^priority=1" --sysparm_count true
```

Service Catalog read only GETs.

```bash
node cli.mjs sc catalogs --sysparm_text "laptop" --sysparm_limit 5
node cli.mjs sc items --sysparm_text "mac" --sysparm_limit 5
node cli.mjs sc item <sys_id>
node cli.mjs sc item-variables <sys_id>
```

### Service Catalog endpoints GET only

- cart
- delivery-address user_id
- validate-categories
- on-change-choices entity_id
- catalogs
- catalog sys_id
- catalog-categories sys_id
- category sys_id
- items
- item sys_id
- item-variables sys_id
- item-delegation item_sys_id user_sys_id
- producer-record producer_id record_id
- record-wizard record_id wizard_id
- generate-stage-pool quantity
- step-configs
- wishlist
- wishlist-item cart_item_id
- wizard sys_id

### Schema Inspection

Use this if you are unsure of a field name.

```bash
node cli.mjs schema incident
```

### Reading Ticket History

Use this to read the full conversation instead of just the current state.

```bash
node cli.mjs history incident <sys_id>
```

### Specialist presets

Create JSON batch files under specialists/ to run multiple reads at once.

- specialists/incidents.json

Each entry supports sysparm_* fields plus these items.

- name label in the batch output
- table target table
- sys_id optional single record fetch

Run a batch preset.

```bash
node cli.mjs batch specialists/incidents.json --pretty
```

## Output

The Table API returns JSON by default. Results appear under result.

## Notes

- Keep result sizes small with sysparm_limit.
- Use sysparm_fields to avoid large payloads.
- This skill is read only by design.

## Summary of the Agent Toolkit

- list and get show the current state of records.
- attach shows files and screenshots.
- stats shows analytics and aggregates.
- sc shows requested item variables.
- schema shows the database map to correct errors.
- history shows the timeline of human conversations.

## Observations & Notes (important)

- Service Catalog endpoints may return empty arrays depending on catalog content and search text — try more specific `--sysparm_text` terms or increase `--sysparm_limit`.
- `sysparm_display_value` is enabled by default for table reads to return human-friendly values (e.g., user names instead of sys_ids). If you need raw system ids, pass `--sysparm_display_value false`.
- Keep `--sysparm_limit` small for agent-initiated queries to avoid large payloads and timeouts. Prefer `stats` for counts or aggregates instead of downloading many rows.
- Attachments: metadata is available via `attach list`/`attach get`; use `attach file <sys_id> --out <path>` to download binary content for local analysis.
- Schema inspection (`schema`) avoids guessing field names and is the recommended first step before reading unknown tables.
- History (`history`) fetches journal entries (comments/work_notes) from `sys_journal_field` and is useful to read the full conversation thread for a ticket.
- Use `--pretty` to make JSON outputs readable for human review and to help the agent summarize long results.

## Recommended Batch Presets

I recommend these specialist JSON presets under `specialists/` to speed up common read workflows. They are safe (read-only) and demonstrate how to combine related reads.

1) `specialists/inspect_incident_schema.json` — schema inspection for `incident`:

```json
[
  {
    "name": "schema-incident",
    "table": "sys_dictionary",
    "sysparm_query": "name=incident^elementISNOTEMPTY",
    "sysparm_fields": "element,column_label,internal_type,reference",
    "sysparm_limit": 500
  }
]
```

2) `specialists/incident_history_template.json` — history template (replace `<SYS_ID>` with the target sys_id before running):

```json
[
  {
    "name": "incident-history",
    "table": "sys_journal_field",
    "sysparm_query": "name=incident^element_id=<SYS_ID>",
    "sysparm_fields": "value,element,sys_created_on,sys_created_by",
    "sysparm_order_by": "sys_created_on",
    "sysparm_limit": 500
  }
]
```

3) `specialists/attachments_incident.json` — recent attachments for incident table:

```json
[
  {
    "name": "recent-incident-attachments",
    "table": "attachment",
    "sysparm_query": "table_name=incident",
    "sysparm_fields": "sys_id,file_name,content_type,table_sys_id,sys_created_on",
    "sysparm_limit": 20
  }
]
```

How to use these:
- For schema: `node cli.mjs batch specialists/inspect_incident_schema.json --pretty`
- For history: replace `<SYS_ID>` then `node cli.mjs batch specialists/incident_history_template.json --pretty` (or run `node cli.mjs history incident <SYS_ID> --pretty`)
- For attachments: `node cli.mjs batch specialists/attachments_incident.json --pretty`, then `node cli.mjs attach file <sys_id> --out /tmp/file` to download a file.

These presets are intentionally read-only and conservative (limits set small). Feel free to ask for additional presets (P1 dashboards, recent changes, escalations).