Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 39 ยท Integrations and Service Portal

Service Portal, Widgets and Employee Center

Understand the ServiceNow Service Portal framework: portals, pages, containers and widgets with server script, client controller and HTML template, plus Employee Center.

Most people never see the ServiceNow back-end interface. They use a portal: a simpler, branded website where employees order items, read knowledge articles and check their tickets. The classic framework for building one is Service Portal. This lesson explains its structure and how a widget works, the unit that you will customize most.

Portals render in a browser on an instance, so the steps are described, and the widget code is read-only. The stand-ins below are JavaScript that imitate a widget's server and client halves, so you can practice the data flow.

Portals, pages and widgets

A Service Portal has three nested layers:

  1. Portal: a site with a URL suffix, such as /sp (the default employee portal) or /csm for a customer one. It has a theme, a header and footer, and a homepage.
  2. Page: a layout identified by an id in the URL, for example /sp?id=index or /sp?id=ticket&table=incident&sys_id=....
  3. Widget: a block placed in a column of a container-row-column grid, based on Bootstrap's grid.

You manage them in Service Portal > Service Portal Configuration, and visually in Page Designer, where you drag widgets into columns and set Instance options (settings per placement). Themes control colors and fonts. In current releases ServiceNow's newer experience, Employee Center with UI Builder pages, is where much new development goes, but the older Service Portal remains widely deployed, and its widget concepts are the basis for understanding both.

Anatomy of a widget

A widget (Service Portal > Widgets) has these parts:

Part Language Runs on
HTML Template AngularJS 1.x template Browser
CSS - SCSS Styles scoped to the widget Browser
Client Script AngularJS controller Browser
Server Script Server-side JavaScript Instance
Option schema JSON describing instance options Config

The server script runs first, fills an object named data, and that object is sent to the browser, where the client controller and template use it:

JavaScript
// Server script
(function () {
  data.items = [];
  var gr = new GlideRecord('incident');
  gr.addQuery('caller_id', gs.getUserID());
  gr.addActiveQuery();
  gr.orderByDesc('sys_created_on');
  gr.setLimit(5);
  gr.query();
  while (gr.next()) {
    data.items.push({ number: gr.getValue('number'), title: gr.getValue('short_description') });
  }
})();
HTML
<!-- HTML template -->
<div class="panel panel-default">
  <div class="panel-heading">My open incidents</div>
  <ul class="list-group">
    <li class="list-group-item" ng-repeat="i in data.items">{{i.number}}: {{i.title}}</li>
  </ul>
  <p ng-if="!data.items.length">Nothing open. Enjoy the quiet.</p>
</div>
JavaScript
// Client script (controller)
api.controller = function () {
  var c = this;
  c.refresh = function () {
    c.server.get({ action: 'refresh' }).then(function (r) { c.data.items = r.data.items; });
  };
};

The client can send input back with c.server.get() or c.server.update(), and the server script reads input.action. Remember that the user can change anything sent from the browser, so validate input and let GlideRecord apply ACLs: use canRead() and similar checks when you return data.

sequenceDiagram
    participant B as Browser
    participant S as Server script
    B->>S: Load page, widget requested
    S->>S: Fill data object (GlideRecord)
    S-->>B: data JSON
    B->>B: Template renders with data
    B->>S: c.server.get({action: "refresh"})
    S-->>B: Updated data

Server fills data, the browser renders it, and events go back with input.

Built-in widgets and reuse

Before writing a widget, look at what exists: Simple List, Data Table, Form, Catalog Item, Knowledge Search, Ticket Conversation, Approvals. Clone a widget (never edit the base one, because upgrades overwrite it) and change the clone. Use Instance options (a name, a default, a type) so one widget serves several uses, such as the table to list.

Portal security

A portal page is not security. ACLs on tables decide what data comes back, and public pages must be marked carefully: set the Public flag only on pages meant for anonymous visitors. Service Portal access is also limited by user criteria on catalog items and knowledge bases, which control who can see which content.

Performance habits

  1. Limit queries in the server script.
  2. Avoid heavy work in the client controller's digest cycle.
  3. Cache data used by many widgets.
  4. Keep the number of widgets per page reasonable.

The data flow in JavaScript

The first stand-in is a "server script" function that fills data, and a "template" rendered by a plain function.

JS Stand-in: server fills data, template renders it

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second stand-in demonstrates the rule "never trust the browser": the server clamps and validates what the client sends.

JS Stand-in: validate input on the server

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a Service Portal widget, which part fills the data object?

    The server script runs on the instance, populates data and sends it to the browser.
  2. 2. Why clone a base widget before changing it?

    Customize copies so platform upgrades do not erase your work.
  3. 3. What are widget instance options for?

    Options are per-placement settings, such as which table or how many rows to show.
  4. 4. A portal page is hidden from the menu. Is the data now secure?

    Hiding a page is not access control; table ACLs and criteria decide what a user can read.

Summary

  • A portal is made of pages built from containers, rows, columns and widgets.
  • A widget has an HTML template, client controller, server script, styles and option schema; the server script fills data.
  • Clone before customizing, validate all input and rely on ACLs for security.
  • Employee Center and UI Builder are the newer path, but widget concepts still apply to the large base of existing portals.

Next: Incident, Problem and Change Management