Execute JavaScript on a ServiceNow instance using Scripts - Background (the /sys.scripts.do endpoint). The script runs server-side with full GlideSystem API access (gs, GlideRecord, GlideAggregate, GlideDateTime, GlideUser, etc.). Use gs.print() or gs.info() to produce output.

SCOPE BEHAVIOR: Scripts execute within the specified application scope. When running in a scoped app (e.g., scope: 'x_myapp_custom'), you can reference that scope's Script Includes and classes directly by name (e.g., MyUtil.doSomething()) without fully-qualifying them. When running in global scope, scoped classes must be fully-qualified (e.g., x_myapp_custom.MyUtil.doSomething()).

IMPORTANT: This executes code directly on the ServiceNow instance. Always review scripts before execution and prefer read-only operations unless modification is explicitly intended.

Execute a single ServiceNow ATF (Automated Test Framework) test by its sys_id. The test runs on the instance, and this tool waits for it to complete before returning the result. Returns the test name, status (success/failure), run time, and any output produced by the test.

Use this tool when the user wants to run a specific ATF test and see its results.

Execute a ServiceNow ATF test suite and wait for all tests to complete. Identify the suite by either its name or sys_id (provide exactly one). Returns a summary with pass/fail/skip/error counts and overall status.

Use this tool when the user wants to run a collection of ATF tests as a suite.

Query any ServiceNow table using the Table API. Returns records matching the specified criteria. Supports encoded query strings, field selection, and display value resolution.

Use this for general-purpose data retrieval from any table (incident, sys_user, cmdb_ci, change_request, etc.).

Search for ATF (Automated Test Framework) tests on a ServiceNow instance. Find tests by name, description, or category. Returns a list of matching tests with their sys_ids, which can then be passed to the run_atf_test tool for execution.

Use this when you need to discover which ATF tests exist before running them.

Query the ServiceNow system log (syslog) to check for errors, warnings, and debug output. Returns log entries with timestamps, levels, sources, and messages. Results are ordered newest-first.

Useful for monitoring script execution results, checking for errors after deployments, and debugging issues. Can be called repeatedly to check for new entries. Use the 'syslog' table for system-level logs and 'syslog_app_scope' for scoped application logs.

Search for ServiceNow applications (scoped apps) and platform plugins by name, scope namespace, or plugin ID. Returns sys_id, name, scope, version, active status, and type for each match.

ServiceNow uses a hierarchical table structure for packages:

• sys_scope: All scoped applications (base table)

  • sys_app: Custom applications in development on this instance

  • sys_store_app: Applications installed from the ServiceNow Store or company app repo

• sys_plugins: Platform plugins

Key use cases:

• Find an application's sys_id to pass as the scope parameter to execute_script (to run scripts within that application's scope)

• Check whether a specific app or plugin is installed/active on the instance

• Look up version, scope namespace, and vendor info for any application or plugin

Search for ServiceNow tables by name or label. Queries the sys_db_object table to find and validate table names.

Use this tool to:

• Verify a table name exists before using it with query_table or in GlideRecord scripts

• Discover the correct internal name for a table when you only know the display label

• Find related tables (e.g., search "incident" to see incident, incident_alert, etc.)

• Check table hierarchy (which table a table extends)

Returns: table name (internal), label (display), parent table, whether it is extendable, number prefix, and application scope.

List or search columns (fields) on a ServiceNow table. Queries the sys_dictionary table to find column names, types, and metadata for a given table.

Use this tool to:

• List all columns on a table to see what fields are available

• Validate a column name before using it in a query or script

• Find the correct internal element name when you only know the display label

• Check column types, whether a field is mandatory, read-only, or a reference

Returns: element name (internal), column label (display), type, max length, reference target, mandatory/read-only/active flags.

Search for code across a ServiceNow instance using the Code Search API. Finds matching scripts, business rules, script includes, and other code artifacts across the platform. Results include the record name, table, field, and matching line numbers with context.

Code Search works through Search Groups, which define sets of tables and fields to search. There is typically a default search group. Use list_code_search_groups to discover available groups, and list_code_search_tables to see which tables a group covers.

Key use cases:

• Find scripts that reference a specific API, table, or pattern

• Locate business rules, script includes, or UI scripts containing specific logic

• Verify whether code has been deployed to an instance

• Search within a specific application scope or table

List available code search groups on a ServiceNow instance. Search groups define which tables and fields are included when performing a code search. Each instance typically has a default search group, and additional groups can be created for specific use cases.

Use the group name as the search_group parameter in code_search. Use the group sys_id when adding tables via add_code_search_table.

List the tables associated with a code search group. These are the tables and fields that are searched when performing a code search with that group.

Use this to understand what a search group covers, or to identify if a specific table is missing and needs to be added via add_code_search_table.

Add a new table to an existing code search group, expanding what gets searched. After adding a table, code searches using that group will also search the specified fields on the new table.

Requires the search group's sys_id (get it from list_code_search_groups) and the table name and fields to search.

IMPORTANT: This modifies the code search configuration on the instance. Verify the table name and fields before adding.

Discover the full schema of a ServiceNow table including all fields, types, references, and optionally choice values, relationships, UI policies, and business rules.

Returns the table name, label, parent class, and for each field: name, label, type, maxLength, mandatory, readOnly, referenceTable, and defaultValue.

Key use cases:

• Understand the structure of a table before querying or scripting against it

• Discover reference fields to understand table relationships

• Find choice values for dropdown fields

• Review UI policies and business rules that affect the table

Get detailed explanation of a specific field on a ServiceNow table, including type, constraints, help text, and available choice values.

Use this to understand what a field does, what values it accepts, and how it is configured before reading or writing data.

Validate a catalog item's configuration on a ServiceNow instance. Checks variables for duplicates, missing names, inactive mandatory variables, and UI policy issues.

Returns a valid/invalid flag, error and warning counts, and each issue with its severity, component, sys_id, description, and suggested fix.

Get the currently active application scope on the ServiceNow instance.

Change the active application scope. Validates the app exists, records previous scope, verifies the change. IMPORTANT: This changes the session's application context.

List scoped applications (sys_app records) on the instance with optional filtering.

Get the currently active update set for the session.

List update sets on the instance with optional filtering.

Create a new update set. IMPORTANT: This creates a new update set on the instance.

Set the active update set for the session. All changes will be captured in this update set.

Inspect an update set's contents — lists all components grouped by type (business rules, script includes, etc.).

Add a comment or work note to any task-based record (incident, change_request, problem, etc.). Comments are customer-visible by default; set is_work_note to true for internal work notes visible only to fulfiller staff.

Assign a task record to a user and optionally an assignment group. Works on any task-based table (incident, change_request, problem, sc_task, etc.).

Resolve an incident by setting state to Resolved (6) with resolution notes. IMPORTANT: This changes the incident state. The incident must typically be in an active state (New, In Progress, On Hold) for this to succeed.

Close an incident by setting state to Closed (7). IMPORTANT: This changes the incident state. The incident should typically be in Resolved state before closing, though this depends on instance configuration.

Approve a change request with optional comments. Sets the approval field to 'approved'. IMPORTANT: This changes the change request's approval status.

Find a task record by its number (e.g., "INC0010001", "CHG0030002"). Returns the full record if found, or a clear message if not. Use this to look up sys_ids, check current state, or retrieve task details before performing actions like assigning or resolving.

Create multiple records across one or more ServiceNow tables in a single batch. Operations execute sequentially, supporting variable references between them: use saveAs to name an operation's result sys_id, then reference it in later operations with ${name} in data values.

Example: Create a parent record with saveAs='parent', then create a child record with caller_id set to '${parent}'.

IMPORTANT: This creates records on the ServiceNow instance. Review the operations before executing.

Update multiple records across one or more ServiceNow tables in a single batch. Each update specifies a table, sys_id, and the field data to update.

IMPORTANT: This modifies records on the ServiceNow instance.

List file attachments on a ServiceNow record. Returns metadata for each attachment including file name, content type, and size.

Use this to discover what files are attached to incidents, changes, catalog items, or any other record.

Get metadata for a specific attachment by its sys_id. Returns file name, content type, size, and the record it is attached to.

Get detailed information about a ServiceNow application by its sys_id. Returns version, install status, update availability, scope, vendor, dependencies, store link, and other metadata.

Use lookup_app to find an application's sys_id by name, then use this tool to get full details.

Validate whether a set of applications are installed at the expected versions. Reports which apps are valid, need installation, need upgrade, or have version mismatches.

Useful for verifying environment readiness or checking deployment prerequisites.

Search or browse ServiceNow store applications by category.

Tab contexts:

• "installed" — list all installed store applications

• "updates" — list installed apps that have updates available

• "available_for_you" — browse apps available for installation

Use this to discover what is installed, find available updates, or browse for new applications to install.

List company-internal applications shared within your organization. Returns application metadata including name, scope, version, install status, and update availability.

Optionally filter by scope, sys_id, or installed status.

Install a ServiceNow store application on the target instance. This is a MUTATIVE, LONG-RUNNING operation that blocks until installation completes or times out (default: 30 minutes).

IMPORTANT:

• Installation adds new tables, scripts, and configuration to the instance.

• Review the application details (use get_app_details) before installing.

• Ensure the instance has sufficient capacity and the right entitlements.

• Consider testing on a sub-production instance first.

Use search_store_apps with tab_context 'available_for_you' to find apps available for installation.

Update an installed ServiceNow store application to a newer version. This is a MUTATIVE, LONG-RUNNING operation that blocks until the update completes or times out (default: 30 minutes).

IMPORTANT:

• Updates may alter existing behavior, modify tables, and affect customizations.

• Customizations to the application may be overwritten during the update.

• Consider testing on a sub-production instance first.

Use search_store_apps with tab_context 'updates' to find apps with available updates.

Install an application from the company's ServiceNow application repository using the CI/CD API. This is a MUTATIVE, LONG-RUNNING operation that blocks until installation completes or times out (default: 30 minutes).

Typically used for deploying custom applications across instances (e.g., dev -> test -> prod). Use list_company_apps to find the application scope and sys_id.

Publish an application to the company's ServiceNow application repository using the CI/CD API. This is a MUTATIVE, LONG-RUNNING operation that blocks until publishing completes or times out (default: 30 minutes).

This makes the application version available for installation on other instances in the company. Use list_company_apps or lookup_app to find the scope and sys_id.

Create a complete ServiceNow workflow from a single specification. Orchestrates: create workflow record -> create version -> create activities -> create transitions -> optionally publish.

Activities are referenced in transitions by their id field (if set) or their array index (as a string like '0', '1', etc.).

IMPORTANT: This creates multiple records on the ServiceNow instance (workflow, version, activities, transitions). Review the specification carefully.

Pull a script (Script Include, Business Rule, UI Script, UI Action, Client Script) from a ServiceNow instance and save it to a local file. The script content is read from the appropriate table and written to the specified file path.

Supported script types:

• sys_script_include (Script Include)

• sys_script (Business Rule)

• sys_ui_script (UI Script)

• sys_ui_action (UI Action)

• sys_script_client (Client Script)

Push a local script file to a ServiceNow instance, updating the script field on the matching record. The file is read from the specified path and the record is found by name in the appropriate table.

IMPORTANT: This modifies code on the ServiceNow instance. The record must already exist — this updates an existing script, it does not create new ones.

Supported script types:

• sys_script_include (Script Include)

• sys_script (Business Rule)

• sys_ui_script (UI Script)

• sys_ui_action (UI Action)

• sys_script_client (Client Script)

Count records on any ServiceNow table, optionally filtered by an encoded query. Uses the Stats API for efficient server-side counting — much faster than querying all records and counting client-side.

Use this to quickly gauge data volumes (e.g., how many open P1 incidents, how many users in a group, how many CIs of a given class).

Run aggregate functions (COUNT, AVG, MIN, MAX, SUM) on any ServiceNow table using the Stats API. Returns computed statistics without returning individual records.

Examples: average resolution time for incidents, max priority across open changes, sum of story points in a sprint, count of active users.

Run aggregate functions (COUNT, AVG, MIN, MAX, SUM) grouped by a field on any ServiceNow table. Returns per-group statistics — ideal for breakdowns and dashboards.

Examples: count of incidents grouped by priority, average resolution time grouped by category, sum of story points grouped by assignee.

Run a consolidated health check on a ServiceNow instance. Returns version info, cluster node status, stuck scheduled jobs, active semaphore count, and operational counts (open incidents, changes, problems).

Each section can be individually enabled/disabled. Use this to quickly assess the overall health and status of an instance.

Get direct relationships of a CMDB Configuration Item (CI). Returns upstream, downstream, or both relationship directions. Use this for impact analysis, dependency mapping, and understanding CI topology.

Provide the CI sys_id (from cmdb_ci or any CI class table). Optionally filter by relationship type (e.g., 'Depends on::Used by', 'Contains::Contained by').

Traverse the CMDB relationship graph starting from a Configuration Item using breadth-first search. Returns all nodes (CIs) and edges (relationships) discovered up to the specified depth.

Use this for deep impact analysis, service mapping, and understanding the full dependency chain of a CI. Max depth is 5, max nodes is 1000.

List tables on a ServiceNow instance with optional filtering. Returns table name, label, parent class, scope, and whether the table is extendable.

Unlike lookup_table (which searches by name or label keyword), this tool supports browsing with prefix filters, scope filters, and extendable-only mode. Use this to discover tables in a specific scope or browse tables by naming convention.

List ServiceNow platform plugins on an instance. Returns plugin ID, name, version, and active status. Use to discover which plugins are installed/active or to find a specific plugin by name prefix.

Find records matching an encoded query and update them all with the specified data. Supports a dry-run mode: set confirm=false (the default) to see how many records would be affected WITHOUT making changes, then set confirm=true to execute.

IMPORTANT: When confirm=true, this modifies records on the ServiceNow instance. Always run a dry-run first to verify the match count before committing.

Find records matching an encoded query and delete them all. Supports a dry-run mode: set confirm=false (the default) to see how many records would be deleted WITHOUT making changes, then set confirm=true to execute.

IMPORTANT: When confirm=true, this PERMANENTLY DELETES records on the ServiceNow instance. Always run a dry-run first to verify the match count before committing. This operation cannot be undone.

Clone an existing update set by creating a new one and copying all its records. The new update set gets the specified name and starts in 'in progress' state.

IMPORTANT: This creates a new update set and copies all records on the instance.

Move records from one update set to another. You can move specific records by sys_id, or move all records from a source update set.

IMPORTANT: This modifies update set membership of records on the instance.

Upload a file attachment to a ServiceNow record. The file content must be provided as a base64-encoded string.

IMPORTANT: This creates an attachment on the ServiceNow instance.

Export a single record from a ServiceNow instance in unload XML format. Uses the /.do?UNL endpoint to generate ServiceNow-native XML that can be imported into another instance or used as a configuration backup.

Common use cases:

• Backing up a Script Include, Business Rule, or other configuration record

• Exporting a record to transfer it to another instance

• Comparing record definitions across instances

• Generating XML for inclusion in an update set

Import XML records into a ServiceNow instance via the sys_upload.do processor. Accepts ServiceNow unload XML format (the output of export_record_xml or update set XML exports).

IMPORTANT: This is a mutative operation that creates or updates records on the instance. Always verify the XML content and target table before importing. Use this for restoring configurations, migrating records between instances, or applying exported record definitions.

List knowledge bases on a ServiceNow instance. Returns knowledge base records from the kb_knowledge_base table with optional filtering by active status and encoded query. Use this to discover available KBs before browsing articles or categories.

Get details of a specific knowledge base by sys_id, including the total number of articles and categories. Use this to understand the scope of a KB before browsing its contents.

List knowledge base categories from the kb_category table. Filter by knowledge base, parent category, active status, or encoded query. Use this to understand a KB's taxonomy before creating or categorizing articles.

Create a new category in a knowledge base. Requires a label and the knowledge base sys_id. Optionally set a parent category for subcategories.

IMPORTANT: This creates a new category on the instance.

List knowledge article summaries from the kb_knowledge table. Returns lightweight records without body content for efficiency. Filter by knowledge base, category, workflow state (draft/published/retired), text search on title, or encoded query.

Use get_kb_article to retrieve the full article body content.

Get the full content of a knowledge article by sys_id, including the HTML body text. Use this when you need to read, review, or extract content from an article.

Create a new knowledge article in a specified knowledge base. The article is created in 'draft' workflow state by default. Use publish_kb_article to make it visible to end users.

The body content can be provided as HTML (text field) or wiki markup (wiki field). HTML is the more common format.

IMPORTANT: This creates a new article on the instance.

Update an existing knowledge article's fields. Only the fields provided will be modified; all others remain unchanged.

IMPORTANT: This modifies the article on the instance.

Publish a draft knowledge article by setting its workflow_state to 'published'. This makes the article visible to end users who have access to the knowledge base.

IMPORTANT: This makes the article publicly visible. Ensure the content has been reviewed before publishing.

List service catalog items from the sc_cat_item table. Supports text search on item name and description, filtering by category, catalog, and active status.

Use this to browse or search for available catalog offerings before getting item details or submitting a request.

Get details of a specific service catalog item by sys_id, optionally including its variables (form fields). Use this to understand what a catalog item offers and what information is needed before submitting a request.

Set include_variables to true (default) to also retrieve the item's form fields.

List service catalog categories from the sc_category table. Filter by parent category, catalog, active status, or title. Use this to browse the catalog's organizational structure.

Get details of a specific service catalog category by sys_id, including the count of items in that category.

List the variables (form fields) for a specific catalog item. Returns variable names, types, whether they are mandatory, default values, and help text. Includes variables from associated variable sets by default.

Essential for understanding what data to provide when using submit_catalog_request. Variable types include: Single Line Text, Multi Line Text, Select Box, Reference, CheckBox, Date, Yes/No, and more.

Submit a service catalog request using the ServiceNow order_now API. Returns the request (REQ) and request item (RITM) numbers.

IMPORTANT: This creates a real service request on the instance. Use list_catalog_item_variables first to understand what variables are required. Variable values should be passed as a key-value object where keys are the variable names and values are strings. For reference-type variables, pass the sys_id of the referenced record.

Execute a published ServiceNow Flow Designer flow by scoped name. Runs the flow using sn_fd.FlowAPI via a background script.

In foreground mode (default), the call blocks until the flow completes and returns outputs directly. In background mode, it returns immediately with a context ID that you can poll with get_flow_context_status.

IMPORTANT: Flows with approval or wait steps MUST use background mode — foreground mode will fail if the flow enters a waiting state.

NOTE: This tool requires the flow to be published. If you are iterating and building a flow that may not be published yet, use test_flow instead — it tests the flow in its current draft state, exactly as the 'Test' button in Flow Designer does.

Execute a ServiceNow Flow Designer subflow by scoped name. Subflows are reusable building blocks in Flow Designer — this is the primary tool for testing subflows during development.

In foreground mode (default), the call blocks until the subflow completes and returns outputs directly. In background mode, it returns a context ID for polling with get_flow_context_status.

Pass inputs as key-value pairs matching the subflow's input variables.

Execute a ServiceNow Flow Designer action by scoped name. Actions are the lowest-level building blocks in Flow Designer (e.g., lookup record, create task, send notification).

In foreground mode (default), the call blocks until the action completes and returns outputs directly. Actions typically complete quickly and foreground mode is usually appropriate.

Query the current status of a flow execution by its context ID. Use this to poll background flow executions started with execute_flow, execute_subflow, or execute_action in background mode.

Possible states: QUEUED, IN_PROGRESS, WAITING, COMPLETE, CANCELLED, ERROR.

Typical pattern: execute in background -> poll this tool every few seconds -> once COMPLETE, call get_flow_outputs. If ERROR, call get_flow_error.

Retrieve outputs from a completed flow/subflow/action execution by its context ID. Only call this after get_flow_context_status shows COMPLETE.

Returns the output name-value pairs defined by the flow/subflow/action.

Retrieve the error message from a failed flow execution by its context ID. Call this after get_flow_context_status shows ERROR to understand why the flow failed.

Returns the flow's error message which can be used to diagnose and fix issues in the flow definition.

Cancel a running or paused flow execution by its context ID. Use this to stop a background flow that is no longer needed, is stuck in a waiting state, or was started by mistake.

IMPORTANT: This is a destructive operation — the flow will be permanently cancelled and cannot be resumed.

Test a ServiceNow Flow Designer flow without requiring it to be published. This is the PRIMARY tool to use when building and iterating on a flow — it invokes the same API as the 'Test' button in Flow Designer, running the flow in its current saved (draft) state.

Unlike execute_flow (which requires a published flow and uses sn_fd.FlowAPI), test_flow works on unpublished drafts via the ProcessFlow REST API (POST /api/now/processflow/flow/{id}/test).

Provide the flow's sys_id or scoped name in flow_id, and supply trigger output variable values in output_map. For record-triggered flows this is typically { "current": "<record_sys_id>", "table_name": "" }. Check the flow's trigger configuration in Flow Designer to determine the correct variable names.

The tool returns a context ID on success — use get_flow_context_status to poll the execution, then get_flow_outputs or get_flow_error once complete.

Copy an existing ServiceNow Flow Designer flow into a target scoped application. This is the best-practice first step when you want to modify any flow — OOB (out-of-box) and shared flows should not be modified directly. Copying into your application scope first keeps the original intact and gives you a flow you own and can freely modify.

This tool enables the full AI-assisted flow development lifecycle: copy_flow → pull with 'now-sdk transform' → modify → push → test_flow → publish_flow

The copied flow lands in draft/unpublished state in the target scope with a new sys_id, independent of the source. The tool returns the new flow's sys_id and prints the exact 'now-sdk transform' command to pull it locally.

Use list_scoped_apps to find the target_scope sys_id for your application.

Get rich execution details for a flow context: per-action timing, inputs, outputs, and high-level metadata (state, runtime, who ran it, test vs production).

This is the primary diagnostic tool after test_flow or execute_flow — use it to understand what each action did, identify which step failed, inspect inputs and outputs, and iterate on the flow definition.

Uses the ProcessFlow operations API (GET /api/now/processflow/operations/flow/context/{id}), the same endpoint Flow Designer uses to display execution details.

IMPORTANT: Requires flow operations logging to be enabled on the instance. If the execution report is unavailable, the response will include a notice explaining why.

Typical workflow: test_flow → get_flow_execution_details → diagnose → modify flow → test_flow again

Retrieve flow execution log entries from sys_flow_log for a given context.

Log entries include error messages, step-level debug output, and cancellation reasons. Use this alongside get_flow_execution_details to get the full picture of what happened during an execution.

Note: Log entries may be empty for simple successful executions, or if the flow's reporting level is set to NONE. Errors and warnings are always logged regardless of the reporting level setting.