ServiceNow Service Portal Widget Explained

What a Service Portal Widget Is

A service portal widget is a reusable component that displays information or enables user interactions within a service portal page. Widgets handle specific tasks: one widget might display a list of recent requests, another might show a catalogue of available services, another might collect user input through a form. Widgets are building blocks that portal designers combine to create pages that serve different user needs.

Widgets are self-contained components that know how to fetch their own data, render information, and handle user interactions. A widget includes the display logic, the data retrieval logic, and the client-side behaviour that makes it interactive. Widget designers can create widgets once and reuse them across multiple portal pages, reducing the need to duplicate similar functionality.

Where Service Portal Widgets Live in ServiceNow

Service portal widgets are defined within the Service Portal application in ServiceNow. The configuration for each widget is stored in the sp_widget table. Each widget has a name, description, display template, and client controller logic that handles interactions. Widgets are associated with portal pages, and pages are associated with portals. Users access portals through URLs like /sp.

ServiceNow provides many pre-built widgets that handle common portal scenarios: form widgets that collect input, list widgets that display records, and search widgets. Organisations can also create custom widgets to display data or functionality specific to their needs. Custom widgets are written using AngularJS for the client-side logic and server-side JavaScript for data retrieval.

Widgets can be configured with options that control their behaviour. A list widget might be configured to show specific fields, filter records by category, or sort results in particular order. The same widget code can be used on multiple pages with different configurations.

A Worked Example: Service Catalogue Widget

A service catalogue widget displays available services that users can request. The widget might show service categories, services within each category, and allow users to select a service to request. The widget includes logic to fetch service records from the platform, render them as cards or a list, and detect when a user clicks to request a service.

The same catalogue widget might appear on multiple portal pages with different configurations. One version might show only services relevant to a specific department. Another might show all services available to all users. The underlying widget code is the same; only the configuration differs. This reusability reduces development effort and ensures consistent behaviour across the portal.

When a user clicks to request a service, the widget might navigate to a request form widget on another page, passing the selected service to the form. The request form widget then pre-fills the service field and allows the user to provide additional information needed for the request.

Common Misunderstandings About Service Portal Widgets

A frequent misunderstanding is thinking that widgets are the same as components or modules in other web frameworks. While the concept is similar, ServiceNow widgets are specifically designed for service portals and integrate with ServiceNow’s authentication, data model, and configuration capabilities. A widget can access ServiceNow data directly and respects the user’s permissions and roles.

Another confusion is assuming that all widgets are interactive. Some widgets are purely informational, displaying data without requiring user interaction. Others are highly interactive and respond to user actions. The level of interactivity depends on what the widget is designed to do.

Some organisations incorrectly assume that custom widgets require advanced development skills. While custom widgets do require JavaScript knowledge, many organisations can create useful widgets using patterns and examples available in ServiceNow’s documentation.

Designing and Configuring Portal Widgets

Effective service portal design starts with understanding what users need to accomplish when they visit the portal. Different user personas might need different widgets on their homepage. A user who frequently submits requests might need a request shortcut widget and a recent requests widget. An approval manager might need a pending approvals widget and an approval history widget.

Widget performance is important for portal usability. Widgets that fetch large datasets or perform complex queries can slow down page load times. Effective widget design fetches only the data needed, caches data when appropriate, and loads data asynchronously so that the page is responsive while data is being retrieved.

Portal accessibility requires that widgets work for users with different abilities. Widgets should support keyboard navigation, provide text alternatives for visual information, and follow accessibility standards. This ensures that portals are usable by all employees and customers.

Reuse, configure or build: the choice that drives later cost

A portal team facing a new page rarely starts with a blank widget. The usual sequence is to look for something existing, copy it when it almost fits, and only then write code. Each of those steps has a different long-term cost, and the cost is mostly paid during upgrades and when the page is later changed by someone who was not there. A widget used as delivered is cheap to keep. A copied widget becomes a second product the team has to maintain. A custom widget is the only option that gives full control, and it is also the only one that the team must test from scratch after every platform change.

Decide the approach before the build starts, and write the reason in the page’s design notes. That note is what a future developer will look for when they wonder why a page behaves oddly.

Comparing the four routes to a working page component

Route	Best fit	Ongoing cost	Upgrade exposure
Use a delivered widget with its options	A standard list, form or search need	Low, as long as options are documented	Low, the platform maintains it
Configure a clone of a delivered widget	A near-match that needs a different field set or a different link target	Medium, the clone no longer receives source fixes automatically	Medium, the clone must be compared after each upgrade
Build a custom widget	A function no delivered widget covers, with a clear owner	High, code, template and server logic all need upkeep	High, every platform change needs a regression pass
Build the page with the newer front-end approach	A new portal whose team will own it for a long period	Depends on the team’s skills and the components used	Lower for the page itself, but the component set must be checked against the platform’s current guidance

The newer page-building approach in the last row is described in the UI Builder page concept entry. The clone row is where much of the hidden cost sits. A cloned widget looks identical on the day it is copied and then drifts from its source, so a security fix or accessibility improvement delivered to the original never reaches the copy unless someone compares them.

A review checklist before a widget is reused on a live page

Reusing a widget on a different page changes its context. Its data, its permissions and its audience can all shift, and the review should check each one rather than assuming the widget is safe because it works on the page it came from.

1. Confirm which records the widget reads, and whether the query is limited by the signed-in user’s access or by a server-side filter that runs with broader rights.
2. Check how each option is supplied. Values that arrive from the browser, such as a record identifier in a URL, must be validated on the server before they are used in a query.
3. Look at the number of records requested on first load and whether the list can page or filter, since an unbounded request slows the whole page.
4. Test with a keyboard only, then with a screen reader, to confirm focus order, labels and the announcement of changing content. The portal accessibility review guidance covers reviewing the whole task path.
5. Check the link targets and the back-navigation behavior, because a widget that opens a form in the same tab can trap users who expected a return path.
6. Record the widget version or the date of the last source comparison in the page notes, so the next upgrade review knows what to compare.

Where portal pages tend to go wrong after launch

Many portal problems are not visible at launch because they depend on data volume, a particular user group or an unusual sequence of clicks. The patterns below recur often enough to plan for.

• A widget that works for a small test group slows down for a large audience, because the query was never tested against realistic record counts.
• A page is built with an administrator’s view and then published to a group that cannot see the records the widget depends on, so the page looks empty rather than broken.
• A custom widget keeps a copy of a value in the browser after the underlying record changes, and users act on the stale copy.
• Search and navigation are designed separately from the widgets, so a visitor who finds the right page cannot find the right widget on it. The portal navigation design guidance addresses that handoff.
• Accessibility is checked only on the default theme, and a color or contrast change later removes the text alternative the widget relied on.

Measuring whether a portal page is doing its job

A portal page earns its place when people finish the task it was built for, without going elsewhere to complete it. Whether the page belongs in the front door at all is a separate question, covered in the employee center front door guidance. Measure that directly where the data allows: the proportion of visits that end in the intended action, the searches that return nothing on the page, and the points where people leave and come back through a different route. The portal search analytics guidance describes how to read search terms as a signal of what the widgets are failing to surface. A widget with a high view count and a low completion rate needs a different fix from one that nobody visits, and treating them the same wastes effort.

Questions portal developers ask about widgets

Should a custom widget be the default when a requirement is unusual?

Not by default. Check whether the requirement can be met by configuring a delivered widget, or by combining two of them on the page. A custom widget should be the choice when the requirement is central to the portal and the team is ready to maintain it.

Why does a widget behave differently in two portals?

The options, the page layout and the portal’s theme can all differ. Compare the widget instance settings in each portal before looking at the widget code, since the configuration is the usual source of the difference.

How do we keep a clone from drifting?

Record which source version it was copied from, and schedule a comparison whenever the source is updated. A clone that is compared once a cycle is far easier to keep correct than one that is only examined when something breaks.

Is a server-side check still needed when the browser already validates input?

Yes. Browser validation helps the user, but it does not protect the server, because any request can be sent directly. The server should check every value that determines which record is read or written.

ServiceNow Service Portal widget examples, tables and field names

A Service Portal widget is a record in the sp_widget table made of an HTML template, CSS, a client script, a server script and an option schema. Typical examples are a request list, a knowledge search box and a row of quick links, each placed on a page as an instance with its own options.

The names below are common out-of-box values for the pieces a widget developer works with. Check them on your own instance and release, because labels, delivered widgets and defaults change between releases, and include them in your upgrade readiness review.

Name	What it holds
sp_widget	The widget definition: template, CSS, client script, server script and option schema
sp_instance	One placement of a widget on a page, with its own option values
sp_page	A portal page that holds containers, rows and columns of widget instances
sp_portal	The portal record, including the URL suffix users type after the instance address, such as sp

In the server script, the data object carries values to the template, input carries what the client sent back, and options carries the instance settings. In the client script, c.data reads the same values, and c.server.get() or c.server.update() sends a request back to the server script.

Example (hypothetical): a team wants a “My open incidents” card on the home page. The server script queries the incident table for active records where the caller is the signed-in user, limits the result to five and puts them in data. A number option in the option schema sets how many rows to show, so a second page can reuse the card with ten. Before publishing, the team tests it with a user who has no incidents and one who has hundreds, and reviews the access control rules behind the query. A team starting a new portal should compare this approach with UI Builder and workspaces.

What are good examples of Service Portal widgets to build first?

Start with read-only ones: a list of the signed-in user’s open requests, a search box that sends people to knowledge articles, and a row of quick links to popular catalog items. They typically carry little risk and expose permission problems early.

What is the difference between a widget and a widget instance?

The widget is the reusable definition stored in sp_widget. An instance is one placement of it on a page, stored in sp_instance with its own option values. Changing the widget changes every instance that uses it; changing an instance affects only that placement.

Where does the server script get its settings from?

The options object holds the values saved on the widget instance, shaped by the option schema, and the input object holds what the client script sent back. Read each value on the server and validate it, because anything arriving from the browser can be altered.