sp_widget Table — ServiceNow Reference

Table Reference/sp_widget

The sp_widget table stores Service Portal widget definitions, containing the HTML template, CSS, client/server scripts, and Angular controller for each widget. Part of the Service Portal module. Query with caution in server scripts — widget records contain large text fields that can impact performance.

What This Table Is

The sp_widget table stores the complete definition of Service Portal widgets — reusable components that render content on Service Portal pages. Each record contains the HTML template, CSS styling, client-side controller JavaScript, and server-side script that make up a widget. The table serves as the configuration layer for all portal functionality, from simple data displays to complex interactive forms.

This table belongs to the Service Portal module and supports the entire portal rendering process. When a user requests a Service Portal page, the platform queries sp_widget records to assemble the page content. The widget's server script executes first, followed by the HTML template rendering, then the client controller loads in the browser.

The sp_widget table extends the base sys_metadata table but contains no child table extensions. Widget instances on specific pages are tracked in separate tables like sp_instance and sp_container, which reference back to widget definitions in this table.

Most enterprise instances contain 200-800 widget records. Out-of-box ServiceNow ships with around 150 widgets, and customers typically create 50-200 custom widgets over time. The table experiences moderate query volume during portal page loads but low write activity — widgets are created during development and rarely modified in production.

When You'll Script Against This Table

You'll query sp_widget primarily in Script Includes that support Service Portal functionality, Migration Set Transform Maps when deploying widgets between instances, and Background Scripts during widget maintenance. Business Rules on this table are rare but useful for enforcing widget development standards or triggering related configuration updates.

Access requires the sp_admin role for write operations, though users with sp_portal can read widget definitions. Widget server scripts execute in the Service Portal application scope, inheriting the portal user's roles plus any elevated permissions configured for the widget.

Common scripting patterns:

Finding widgets by id (the technical name) for dynamic portal configuration
Querying by category to build widget picker interfaces
Reading option_schema to validate widget instance configuration
Updating css or template fields for programmatic widget maintenance
Filtering by public field to control widget visibility in the designer
Copying widget definitions for customization while preserving the original
Analyzing widget dependencies by parsing script and client_script for API usage

Table Gotchas

⚠️

The template, script, client_script, and css fields contain large text blocks. Querying multiple widgets without field restrictions can cause performance issues and exceed script execution limits.

⚠️

Widget IDs must be unique and follow JavaScript variable naming conventions since they're used as Angular module names. Special characters will break portal rendering.

The option_schema field stores JSON but as a string type — parse it before use and handle malformed JSON gracefully
Widget records cache aggressively — changes may not appear immediately in portals, especially in development instances with multiple browser tabs open
The servicenow boolean identifies out-of-box widgets — never set this to true on custom widgets as it affects upgrade behavior

⚠️

Widget server scripts run in a different execution context than standard Business Rules. They have access to a special 'data' object and '$sp' API but cannot use standard GlideRecord transaction methods.

Deleting widgets doesn't automatically clean up their instances on pages — orphaned sp_instance records can cause portal errors

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

The sp_widget table extends sys_metadata, inheriting application scope and update set tracking. Widget definitions connect to the broader Service Portal ecosystem through several key relationships that developers frequently traverse in queries.

The sp_instance table stores individual widget placements on pages, referencing sp_widget through its widget field. The sp_page table defines portal pages that contain widget instances. Developers often join these three tables to understand complete page composition. The sp_dependency table tracks JavaScript and CSS dependencies that widgets require, linking back to widget records through dependency maps.

When building comprehensive Service Portal queries, you'll frequently cross-reference the sp_portal table to understand portal-specific configurations, and the sys_scope table to identify which application owns custom widgets. The sys_update_set relationship becomes crucial during widget deployments between instances.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Key Fields

Column	Type	Label	Notes
id	string	Widget ID	Unique technical identifier used in code and URLs. Must follow JavaScript variable naming rules since it becomes an Angular module name.
name	string	Name	Display name shown in the Service Portal designer. Can contain spaces and special characters unlike the ID field.
template	html	Body HTML template	Angular HTML template with ServiceNow-specific directives. Supports two-way data binding to the widget's server data object.
css	css	CSS	Scoped CSS that applies only to this widget instance. Automatically prefixed with widget-specific selectors to prevent style bleeding.
script	script	Server script	Server-side JavaScript that executes before template rendering. Has access to the special 'data' object and '$sp' API but not standard glide APIs.
client_script	script	Client script	Angular controller JavaScript that runs in the browser. Receives the server data object and can make $http calls back to the server.
option_schema	json	Option schema	JSON schema defining configurable options for widget instances. Validates option values and generates the instance configuration UI.
public	boolean	Public	Controls visibility in the Service Portal designer widget picker. Private widgets can only be added programmatically.
roles	string	Roles	Comma-separated list of roles required to view this widget. Empty means no role restriction, but portal page ACLs still apply.
servicenow	boolean	ServiceNow	Identifies out-of-box widgets. Never set to true on custom widgets as it affects upgrade behavior and support.
category	string	Category	Organizes widgets in the designer palette. Custom categories appear alongside out-of-box ones like 'form' and 'data'.
description	string	Description	Tooltip text shown in the designer widget picker. Should explain the widget's purpose and any configuration requirements.
docs	html	Documentation	Rich text documentation for developers. Appears in the widget editor's documentation tab but nowhere in the runtime portal.
field_list	string	Field list	Comma-separated list of table fields this widget commonly displays. Used for form widgets to auto-populate field options.
has_preview	boolean	Has preview	Indicates if this widget supports preview mode in the designer. Complex widgets often disable preview for performance.
internal	boolean	Internal	Marks widgets for internal ServiceNow use only. Internal widgets may change behavior in upgrades without notice.
link	script	Link	Server-side script that executes when the widget receives AJAX calls from its client controller. Returns data to the client.
data_table	string	Data table	Table name this widget primarily displays data from. Used by the platform to suggest relevant widgets when building forms.

Common Queries

Get all public widgets available in the designer

// Most common query - find widgets users can add to pages
var gr = new GlideRecord('sp_widget');
gr.addQuery('public', true);
gr.addQuery('internal', false);
gr.orderBy('name');
gr.query();

while (gr.next()) {
    // Process widgets for picker UI
    gs.info('Widget: ' + gr.name + ' (' + gr.id + ')');
    gs.info('Category: ' + gr.category);
}

Find custom widgets in a specific application scope

// Filter by scope and exclude ServiceNow out-of-box widgets
var gr = new GlideRecord('sp_widget');
gr.addQuery('servicenow', false);  // Custom widgets only
gr.addQuery('sys_scope.name', 'My Custom App');
gr.addQuery('public', true);
gr.query();

while (gr.next()) {
    gs.info('Custom widget: ' + gr.name);
    gs.info('ID: ' + gr.id);
    gs.info('Description: ' + gr.description);
}

Get widget definition by ID for dynamic portal configuration

// Real-world scenario: loading widget config in portal script
var widgetId = 'ticket-list';  // From page configuration
var gr = new GlideRecord('sp_widget');
gr.addQuery('id', widgetId);
gr.query();

if (gr.next()) {
    // Parse option schema for instance validation
    var schema = JSON.parse(gr.option_schema.toString() || '{}');
    gs.info('Widget found: ' + gr.name);
    gs.info('Required roles: ' + gr.roles);
} else {
    gs.error('Widget not found: ' + widgetId);
}

Count widgets by category using GlideAggregate

// Analyze widget distribution for governance reporting
var ga = new GlideAggregate('sp_widget');
ga.addQuery('public', true);
ga.addAggregate('COUNT');
ga.groupBy('category');
ga.query();

while (ga.next()) {
    var category = ga.category.toString() || 'Uncategorized';
    var count = ga.getAggregate('COUNT');
    gs.info('Category ' + category + ': ' + count + ' widgets');
}

GOTCHA: Wrong vs right way to query large text fields

// WRONG: Queries all text fields, causes performance issues
// var gr = new GlideRecord('sp_widget');
// gr.query();  // Loads template, script, css for all widgets

// RIGHT: Specify fields when you need text content
var gr = new GlideRecord('sp_widget');
gr.addQuery('id', 'my-widget');
gr.query();

if (gr.next()) {
    // Only access large fields when actually needed
    var template = gr.template.toString();
    gs.info('Template length: ' + template.length);
}

Related Tables

sp_page

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue