Guillaume BOURGEOIS
1ca5597453
31 commands: ticket lifecycle (create/update/resolve/delete, comments, work notes, links, tags, journal notes, attachments), generic table records CRUD and discovery, CMDB/user/group queries, service catalog ordering, standard change from template, AWA queue routing, generic API call, plus get_incidents ingestion with a bundled OCSF mapper. Basic or OAuth 2.0 (password grant) authentication, stdlib-only scripts. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
447 lines
24 KiB
YAML
447 lines
24 KiB
YAML
id: servicenow
|
|
name: ServiceNow
|
|
version: 1.0.0
|
|
description: "ServiceNow ITSM (Table / Service Catalog / Change Management REST APIs) — ticket lifecycle (create/update/resolve/delete, comments, work notes, links, tags, journal notes), generic table records CRUD, CMDB and user/group queries, service catalog ordering, standard change creation, attachments, work-item queue routing, plus ticket ingestion (get_incidents) with an OCSF mapper. Basic or OAuth 2.0 (password grant) authentication."
|
|
changelog: "1.0.0 — Initial release: ticket lifecycle commands (incident, problem, change_request, sc_request, sc_task, sc_req_item), records/table CRUD and discovery, CMDB computer/group/user queries, service catalog (search, details, order), standard change from template + change tasks, attachments (list/upload/delete), queue routing, generic API call, and ticket ingestion with a bundled OCSF mapper."
|
|
category: ticketing
|
|
|
|
# Per-instance configuration. The base URL is the instance root, e.g.
|
|
# https://company.service-now.com (scripts append /api/now, /api/sn_sc, /api/sn_chg_rest).
|
|
config_schema:
|
|
properties:
|
|
url:
|
|
type: string
|
|
description: "ServiceNow instance URL, e.g. https://company.service-now.com"
|
|
auth_type:
|
|
type: string
|
|
description: "Authentication method: basic (username + password) or oauth (OAuth 2.0 password grant via /oauth_token.do — also requires client_id/client_secret)"
|
|
default: basic
|
|
username:
|
|
type: string
|
|
description: "ServiceNow username (needs rest_api_explorer/web_service_admin style roles plus read/write ACLs on the target tables)"
|
|
password:
|
|
type: string
|
|
description: "ServiceNow password"
|
|
x-soar-sensitive: true
|
|
client_id:
|
|
type: string
|
|
description: "OAuth client ID (oauth auth_type only — from an Application Registry entry)"
|
|
client_secret:
|
|
type: string
|
|
description: "OAuth client secret (oauth auth_type only)"
|
|
x-soar-sensitive: true
|
|
api_version:
|
|
type: string
|
|
description: "Optional REST API version segment (e.g. v2). Leave empty to use the unversioned endpoints."
|
|
ticket_type:
|
|
type: string
|
|
description: "Default ticket table for ticket commands and ingestion: incident, problem, change_request, sc_request, sc_task or sc_req_item"
|
|
default: incident
|
|
timestamp_field:
|
|
type: string
|
|
description: "Timestamp field used as the ingestion watermark (e.g. opened_at or sys_created_on)"
|
|
default: opened_at
|
|
required:
|
|
- url
|
|
- username
|
|
- password
|
|
|
|
# Documented for reference; the bundled scripts build the headers themselves.
|
|
# Basic: Authorization: Basic base64(username:password)
|
|
# OAuth: POST /oauth_token.do (grant_type=password) then Authorization: Bearer <access_token>
|
|
auth:
|
|
- id: basic
|
|
type: basic
|
|
username_field: username
|
|
password_field: password
|
|
|
|
commands:
|
|
# ── Ingestion ─────────────────────────────────────────────────────────────
|
|
- id: get_incidents
|
|
name: servicenow-get-incidents
|
|
description: "Fetch tickets from the configured ticket table for ingestion. Returns {result:[...]}; use result as the alert rule results path."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
query: { type: string, description: "Extra sysparm_query filter prepended to the watermark clause (e.g. stateNOT IN6,7)" }
|
|
created_after: { type: string, description: "Lower bound on the configured timestamp field, ISO8601, epoch ms or 'YYYY-MM-DD HH:MM:SS' (incremental fetch watermark)" }
|
|
ticket_type: { type: string, description: "Override the configured ticket table" }
|
|
limit: { type: number, description: "Maximum tickets to fetch (default 100)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
ingest:
|
|
results_path: result
|
|
dedup_key: sys_id
|
|
incremental_field: created_after
|
|
|
|
# ── Tickets ───────────────────────────────────────────────────────────────
|
|
- id: get_ticket
|
|
name: servicenow-get-ticket
|
|
description: "Retrieve a ticket by sys_id or number from any ticket table."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id" }
|
|
number: { type: string, description: "Ticket number (e.g. INC0010001) — used when id is empty" }
|
|
ticket_type: { type: string, description: "Ticket table: incident, problem, change_request, sc_request, sc_task, sc_req_item (default from instance config)" }
|
|
fields: { type: string, description: "Comma-separated list of fields to return (sys_id always included)" }
|
|
display_value: { type: string, description: "sysparm_display_value: true, false or all (default false)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
- id: create_ticket
|
|
name: servicenow-create-ticket
|
|
description: "Create a ticket. Common fields have named inputs; anything else goes through fields/custom_fields."
|
|
inputs_schema:
|
|
properties:
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
short_description: { type: string, description: "Short description (title)" }
|
|
description: { type: string, description: "Full description" }
|
|
urgency: { type: string, description: "Urgency (1, 2 or 3)" }
|
|
impact: { type: string, description: "Impact (1, 2 or 3)" }
|
|
priority: { type: string, description: "Priority (1-Critical … 5-Planning)" }
|
|
state: { type: string, description: "State code (numeric, table-specific)" }
|
|
category: { type: string, description: "Category" }
|
|
subcategory: { type: string, description: "Subcategory" }
|
|
caller_id: { type: string, description: "Caller (sys_id or exact user name)" }
|
|
assigned_to: { type: string, description: "Assignee (sys_id or exact user name)" }
|
|
assignment_group: { type: string, description: "Assignment group (sys_id or exact group name)" }
|
|
comments: { type: string, description: "Customer-visible comment to add on creation" }
|
|
work_notes: { type: string, description: "Internal work note to add on creation" }
|
|
fields: { type: string, description: "Additional fields as name=value;name2=value2" }
|
|
custom_fields: { type: string, description: "Custom fields as name=value;name2=value2 (u_ prefix added when missing)" }
|
|
input_display_value: { type: boolean, description: "Treat input values as display values (sysparm_input_display_value)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
- id: update_ticket
|
|
name: servicenow-update-ticket
|
|
description: "Update a ticket by sys_id (state changes, reassignment, resolution fields, any field via fields/custom_fields)."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id to update" }
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
short_description: { type: string, description: "Short description (title)" }
|
|
description: { type: string, description: "Full description" }
|
|
urgency: { type: string, description: "Urgency (1, 2 or 3)" }
|
|
impact: { type: string, description: "Impact (1, 2 or 3)" }
|
|
priority: { type: string, description: "Priority (1-Critical … 5-Planning)" }
|
|
state: { type: string, description: "State code (numeric, table-specific — e.g. incident 6=Resolved, 7=Closed)" }
|
|
category: { type: string, description: "Category" }
|
|
subcategory: { type: string, description: "Subcategory" }
|
|
caller_id: { type: string, description: "Caller (sys_id or exact user name)" }
|
|
assigned_to: { type: string, description: "Assignee (sys_id or exact user name)" }
|
|
assignment_group: { type: string, description: "Assignment group (sys_id or exact group name)" }
|
|
close_code: { type: string, description: "Close code (required by most instances when resolving)" }
|
|
close_notes: { type: string, description: "Close notes (required by most instances when resolving)" }
|
|
comments: { type: string, description: "Customer-visible comment to add" }
|
|
work_notes: { type: string, description: "Internal work note to add" }
|
|
fields: { type: string, description: "Additional fields as name=value;name2=value2" }
|
|
custom_fields: { type: string, description: "Custom fields as name=value;name2=value2 (u_ prefix added when missing)" }
|
|
input_display_value: { type: boolean, description: "Treat input values as display values (sysparm_input_display_value)" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
- id: delete_ticket
|
|
name: servicenow-delete-ticket
|
|
description: "Delete a ticket by sys_id."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id to delete" }
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
- id: query_tickets
|
|
name: servicenow-query-tickets
|
|
description: "Query tickets with an encoded sysparm_query (e.g. active=true^priority=1^ORDERBYDESCopened_at)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
query: { type: string, description: "Encoded sysparm_query" }
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
fields: { type: string, description: "Comma-separated fields to return (sys_id always included)" }
|
|
limit: { type: number, description: "Maximum records (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
display_value: { type: string, description: "sysparm_display_value: true, false or all (default false)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
- id: add_comment
|
|
name: servicenow-add-comment
|
|
description: "Add a customer-visible comment or an internal work note to a ticket."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id" }
|
|
comment: { type: string, description: "Text to add" }
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
work_note: { type: boolean, description: "Add as internal work note instead of customer-visible comment" }
|
|
required: [id, comment]
|
|
outputs_schema: { properties: {} }
|
|
- id: add_link
|
|
name: servicenow-add-link
|
|
description: "Post a clickable link (with optional text) into a ticket's comments or work notes."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id" }
|
|
link: { type: string, description: "URL to post" }
|
|
text: { type: string, description: "Link text (defaults to the URL)" }
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
work_note: { type: boolean, description: "Post into work notes instead of comments" }
|
|
required: [id, link]
|
|
outputs_schema: { properties: {} }
|
|
- id: add_tag
|
|
name: servicenow-add-tag
|
|
description: "Attach an existing tag (label) to a ticket via the label_entry table."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id" }
|
|
tag_id: { type: string, description: "Tag (label) sys_id — find it with servicenow-query-table on the label table" }
|
|
title: { type: string, description: "Entry title, e.g. 'Incident - INC0010001'" }
|
|
ticket_type: { type: string, description: "Ticket table (default from instance config)" }
|
|
required: [id, tag_id, title]
|
|
outputs_schema: { properties: {} }
|
|
- id: get_ticket_notes
|
|
name: servicenow-get-ticket-notes
|
|
description: "Retrieve a ticket's comments and work notes from the journal (requires read access to sys_journal_field)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Ticket sys_id" }
|
|
limit: { type: number, description: "Maximum notes (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
- id: get_ticket_attachments
|
|
name: servicenow-get-ticket-attachments
|
|
description: "List attachment metadata (name, size, content type, download link) for a record."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Record sys_id the attachments belong to" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
- id: upload_file
|
|
name: servicenow-upload-file
|
|
description: "Attach a file to a record (content provided as base64)."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Record sys_id to attach the file to" }
|
|
file_name: { type: string, description: "File name (extension drives the content type)" }
|
|
content_base64: { type: string, description: "File content, base64-encoded" }
|
|
table_name: { type: string, description: "Table of the record (default from the instance ticket_type)" }
|
|
required: [id, file_name, content_base64]
|
|
outputs_schema: { properties: {} }
|
|
- id: delete_file
|
|
name: servicenow-delete-file
|
|
description: "Delete an attachment by its attachment sys_id."
|
|
inputs_schema:
|
|
properties:
|
|
file_sys_id: { type: string, description: "Attachment sys_id (from servicenow-get-ticket-attachments)" }
|
|
required: [file_sys_id]
|
|
outputs_schema: { properties: {} }
|
|
|
|
# ── Records / tables ──────────────────────────────────────────────────────
|
|
- id: get_record
|
|
name: servicenow-get-record
|
|
description: "Retrieve a single record from any table by sys_id."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
table_name: { type: string, description: "Table name (e.g. alm_asset)" }
|
|
id: { type: string, description: "Record sys_id" }
|
|
fields: { type: string, description: "Comma-separated fields to return (sys_id always included)" }
|
|
display_value: { type: string, description: "sysparm_display_value: true, false or all (default false)" }
|
|
required: [table_name, id]
|
|
outputs_schema: { properties: {} }
|
|
- id: create_record
|
|
name: servicenow-create-record
|
|
description: "Create a record in any table."
|
|
inputs_schema:
|
|
properties:
|
|
table_name: { type: string, description: "Table name" }
|
|
fields: { type: string, description: "Fields as name=value;name2=value2" }
|
|
custom_fields: { type: string, description: "Custom fields as name=value;name2=value2 (u_ prefix added when missing)" }
|
|
input_display_value: { type: boolean, description: "Treat input values as display values (sysparm_input_display_value)" }
|
|
required: [table_name]
|
|
outputs_schema: { properties: {} }
|
|
- id: update_record
|
|
name: servicenow-update-record
|
|
description: "Update a record in any table by sys_id."
|
|
inputs_schema:
|
|
properties:
|
|
table_name: { type: string, description: "Table name" }
|
|
id: { type: string, description: "Record sys_id" }
|
|
fields: { type: string, description: "Fields as name=value;name2=value2" }
|
|
custom_fields: { type: string, description: "Custom fields as name=value;name2=value2 (u_ prefix added when missing)" }
|
|
input_display_value: { type: boolean, description: "Treat input values as display values (sysparm_input_display_value)" }
|
|
required: [table_name, id]
|
|
outputs_schema: { properties: {} }
|
|
- id: delete_record
|
|
name: servicenow-delete-record
|
|
description: "Delete a record from any table by sys_id."
|
|
inputs_schema:
|
|
properties:
|
|
table_name: { type: string, description: "Table name" }
|
|
id: { type: string, description: "Record sys_id" }
|
|
required: [table_name, id]
|
|
outputs_schema: { properties: {} }
|
|
- id: query_table
|
|
name: servicenow-query-table
|
|
description: "Query any table with an encoded sysparm_query."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
table_name: { type: string, description: "Table name" }
|
|
query: { type: string, description: "Encoded sysparm_query" }
|
|
fields: { type: string, description: "Comma-separated fields to return (sys_id always included)" }
|
|
limit: { type: number, description: "Maximum records (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
display_value: { type: string, description: "sysparm_display_value: true, false or all (default false)" }
|
|
required: [table_name]
|
|
outputs_schema: { properties: {} }
|
|
- id: list_table_fields
|
|
name: servicenow-list-table-fields
|
|
description: "List the API field names of a table (from a sample record)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
table_name: { type: string, description: "Table name" }
|
|
required: [table_name]
|
|
outputs_schema: { properties: {} }
|
|
- id: get_table_name
|
|
name: servicenow-get-table-name
|
|
description: "Resolve table names from a display label (e.g. label 'Asset' → alm_asset) via sys_db_object."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
label: { type: string, description: "Table display label (e.g. Asset, Incident, IP address)" }
|
|
limit: { type: number, description: "Maximum results (default 10)" }
|
|
required: [label]
|
|
outputs_schema: { properties: {} }
|
|
|
|
# ── CMDB / users / groups ─────────────────────────────────────────────────
|
|
- id: query_computers
|
|
name: servicenow-query-computers
|
|
description: "Query the cmdb_ci_computer table by sys_id, name, asset tag or encoded query."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
computer_id: { type: string, description: "Computer sys_id" }
|
|
computer_name: { type: string, description: "Exact computer name" }
|
|
asset_tag: { type: string, description: "Asset tag" }
|
|
query: { type: string, description: "Encoded sysparm_query (used when no other filter is given)" }
|
|
limit: { type: number, description: "Maximum records (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
- id: query_groups
|
|
name: servicenow-query-groups
|
|
description: "Query the sys_user_group table by sys_id, name or encoded query."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
group_id: { type: string, description: "Group sys_id" }
|
|
group_name: { type: string, description: "Exact group name" }
|
|
query: { type: string, description: "Encoded sysparm_query (used when no other filter is given)" }
|
|
limit: { type: number, description: "Maximum records (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
- id: query_users
|
|
name: servicenow-query-users
|
|
description: "Query the sys_user table by sys_id, username or encoded query."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
user_id: { type: string, description: "User sys_id" }
|
|
user_name: { type: string, description: "Exact username (user_name field)" }
|
|
query: { type: string, description: "Encoded sysparm_query (used when no other filter is given)" }
|
|
limit: { type: number, description: "Maximum records (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
|
|
# ── Service catalog ───────────────────────────────────────────────────────
|
|
- id: query_items
|
|
name: servicenow-query-items
|
|
description: "Search service catalog items by name (Service Catalog API)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
name: { type: string, description: "Free-text search (partial match)" }
|
|
limit: { type: number, description: "Maximum items (default 10)" }
|
|
offset: { type: number, description: "Starting record index (default 0)" }
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
- id: get_item_details
|
|
name: servicenow-get-item-details
|
|
description: "Get a catalog item's details, including its order variables (Service Catalog API)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Catalog item sys_id" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
- id: create_item_order
|
|
name: servicenow-create-item-order
|
|
description: "Order a catalog item (order_now). Mandatory item variables must be provided."
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Catalog item sys_id" }
|
|
quantity: { type: number, description: "Quantity to order (default 1)" }
|
|
variables: { type: string, description: "Item variables as name=value;name2=value2 (see servicenow-get-item-details)" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
|
|
# ── Change management ─────────────────────────────────────────────────────
|
|
- id: create_change_from_template
|
|
name: servicenow-create-change-from-template
|
|
description: "Create a standard change request from a standard change template (Change Management API)."
|
|
inputs_schema:
|
|
properties:
|
|
template: { type: string, description: "Standard change template sys_id" }
|
|
required: [template]
|
|
outputs_schema: { properties: {} }
|
|
- id: get_change_tasks
|
|
name: servicenow-get-change-tasks
|
|
description: "List the tasks of a change request (Change Management API)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties:
|
|
id: { type: string, description: "Change request sys_id" }
|
|
required: [id]
|
|
outputs_schema: { properties: {} }
|
|
|
|
# ── Misc ──────────────────────────────────────────────────────────────────
|
|
- id: document_route_to_queue
|
|
name: servicenow-document-route-to-queue
|
|
description: "Route a document (ticket/record) to an Advanced Work Assignment queue."
|
|
inputs_schema:
|
|
properties:
|
|
queue_id: { type: string, description: "Queue sys_id (awa_queue table)" }
|
|
document_id: { type: string, description: "Document sys_id to route" }
|
|
document_table: { type: string, description: "Document table (default incident)" }
|
|
required: [queue_id, document_id]
|
|
outputs_schema: { properties: {} }
|
|
- id: generic_api_call
|
|
name: servicenow-generic-api-call
|
|
description: "Call any instance REST endpoint (path relative to the instance URL, e.g. /api/now/table/incident)."
|
|
inputs_schema:
|
|
properties:
|
|
method: { type: string, description: "HTTP method: GET, POST, PATCH, PUT or DELETE" }
|
|
path: { type: string, description: "Endpoint path starting with / (e.g. /api/now/table/incident)" }
|
|
params: { type: string, description: "Query parameters as JSON object (e.g. {\"sysparm_limit\":\"5\"})" }
|
|
body: { type: string, description: "Request body as JSON (POST/PATCH/PUT)" }
|
|
required: [method, path]
|
|
outputs_schema: { properties: {} }
|
|
|
|
- id: test_connection
|
|
name: servicenow-test-connection
|
|
description: "Verify connectivity and credentials (used by the Test button)."
|
|
risk: read
|
|
inputs_schema:
|
|
properties: {}
|
|
required: []
|
|
outputs_schema: { properties: {} }
|
|
|
|
ingestion:
|
|
command: get_incidents
|
|
mapper: get_incidents
|
|
default_incident_type: "ServiceNow Ticket"
|