Service Portal Tips

NOTE: If the Service Portal does not open, you need to activate the Service Portal – Core plugin. See the Activate the Service Portal Plugin section at the bottom of this page.

  • For homepage quicklinks container use the parent class: homepage-quicklinks
  • In a fixed layout, page elements remain the same size as the page is widened or narrowed.
  • In a fluid layout, elements are a fixed percentage of the screen size. Element width varies as page width changes. Notice that the distance between the search field and the page edge remains the same.

As page width changes, the Search field remains remains a percentage of the container width

  • Use the Width field in the container options to specify whether a container is Fixed or Fluid.
  • Use the Parent class field when setting container options to specify the viewport size at which a container should appear or disappear. In this example, the container is hidden at the viewport size of extra small using the parent class hidden-xs. To show the container for the extra small viewport use the parent class visible-xs.
  • There are hidden/visible CSS classes for other sizes as well such as visible-lg and hidden-md. You can also try pull-right, pull-left, and center-block.
  • Branding and themes are set at the portal level. Changing a theme color, for example, changes only the currently selected portal.  The Theme Preview provides a quick way to determine if the colors in the theme look good together.

Widget Components

Widgets include both mandatory and optional components.

HTML Template

The widget’s HTML accepts and displays data.

  • Renders the dynamic view a user sees in the browser using information from the model and controller
  • Binds client script variables to markup
  • Gathers data from user inputs like input text, radio buttons, and check boxes

HTML is mandatory.

Client Script

The widget’s Client Script defines the AngularJS controller.

  • Service Portal maps server data from JavaScript and JSON objects to client objects
  • Processes data for rendering
  • Passes data to the HTML template
  • Passes user input and data to the server for processing

A Client Script is mandatory.

Server Script

The widget’s Server Script works with record data, web services, and any other data available in ServiceNow server-side scripts.

  • Sets the initial widget state
  • Sends data to the widget’s Client Script using the data object
  • Runs server-side queries

A Server Script is mandatory.

Option Schema

The Option Schema allows a Service Portal Admin (sp_admin role) to configure a widget.

  • Specifies widget parameters
  • Allows admin users to define instance options for a widget instance
  • Makes widgets flexible and reusable

An Option Schema is optional.

Angular Providers

An Angular Provider:

  • Keeps widgets in sync when changing records or filters
  • Shares context between widgets
  • Maintains and persists state
  • Creates reusable behaviors and UI components then injects them into multiple widgets

Client and Server Objects

 

Function Name Description
this.server.get() Calls the Server Script and passes custom input.
this.server.update() Calls the server and posts this.data to the Server Script.
this.server.refresh() Calls the server and automatically replaces the current options and data from the server response.

 

Widget API

Service Portal has an API known as the Widget API. The Widget API contains classes for both client-side and server-side scripting.

Client-side API

The client-side Widget API classes are:

  • spUtil: Contains utility methods to perform common functions in a Service Portal widget client script. Access the methods from this class using spUtil. For example, spUtil.addErrorMessage().
    • addErrorMessage(): display an error message
    • addInfoMessage(): display an informational message
    • addTrivialMessage(): display a message which automatically disappears after a short period of time
    • format(): used to build strings from variables (alternative to concatenation)
    • get(): gets a widget model by ID or sys_id
    • recordWatch(): watches for updates to a table or filter and returns the value from a callback function
    • refresh(): calls the server and replaces the current options and data objects with the server response
    • update(): updates the data object on the server within a given scope
  • spModal: Methods provide an alternative way to show alerts, prompts, and confirmation dialogs. Access the methods from this class using spModal. For example, spModal.alert().
    • alert(): displays an alert
    • confirm(): displays a confirmation message
    • open(): opens a modal using the specified options
    • prompt(): displays a prompt for user input
  • spAriaUtil: Uses an AngularJS service to show messages on a screen reader. Access the method from this class using spAriaUtil. For example, spAriaUtil.sendLiveMessage().
    • sendLiveMessage(): announce a message to a screen reader

For the complete API documentation, including method arguments and return values, follow the links to the API classes.

Server-side API

The server-side Widget API class is:

  • GlideSPScriptable: Methods for use in Service Portal widget Server Scripts. Access the GlideSPScriptable methods using the global $sp object. For example, $sp.canRead().
    • canReadRecord(): returns true if the user can read the specified GlideRecord
    • getCatalogItem(): returns a model and view model for a sc_cat_item or sc_cat_item_guide
    • getDisplayValue: returns the display value of the specified field from either the widget’s sp_instance or sp_portal record
    • getField(): returns information about the specified field in a GlideRecord
    • getFields(): checks the specified list of field names, and returns an array of valid field names
    • getFieldsObject(): checks the specified list of field names and returns an object of valid field names
    • getForm(): returns the form
    • getListColumns(): returns a list of the specified table’s columns in the specified view
    • getMenuHREF(): returns the (?id=) portion of the URL based on the sp_menu type
    • getMenuItems(): returns an array of menu items for the specified instance
    • getParameter(): returns the value of the specified parameter
    • getPortalRecord(): returns the portal’s GlideRecord
    • getRecord(): returns the current portal context
    • getRecordDisplayValues(): copies display values for the specified fields into the data parameter
    • getRecordElements(): for the specified fields, copies the element’s name, display value, and value into the data parameter
    • getRecordValues(): copies values for the specified field names from the GlideRecord into the data parameter
    • getStream(): gets the activity stream for the specified record. This method works on tables which extend the Task table
    • getUserInitials(): returns the user’s initials
    • getValue(): returns the value of the specified parameter
    • getValues(): copies values from the request or instance to the data parameter
    • getWidget(): gets a widget by id or sys_id, executes that widget’s server script using the provided options, then returns the widget model
(function() {
//create an array to populate without notes
data.notes = [];
var noteGR = new GlideRecord('x_snc_createnotes_note');
noteGR.addQuery('user', gs.getUser().getID());
noteGR.orderByDesc('sys_created_on');
noteGR.query();
while (noteGR.next()) {
var noteObj = {};
//use service portal helper method to get some display values
$sp.getRecordDisplayValues(noteObj, noteGR, 'number,title,sys_id');
//get the first 20 characters of the description
noteObj.note = noteGR.getValue('note').slice(0,20);
//push the populated obj into the array
data.notes.push(noteObj);
}
})();