spUtil - Client

Utility methods to perform common functions in a Service Portal widget client script.

spUtil - addErrorMessage(String message)

Displays a notification error message.

Table 1. Parameters
Name Type Description
message String Error message to display.
Table 2. Returns
Type Description
spUtil.addErrorMessage("There has been an error processing your request")

spUtil - addInfoMessage(String message)

Displays a notification info message.

Table 3. Parameters
Name Type Description
message String Message to display.
Table 4. Returns
Type Description
spUtil.addInfoMessage("Your order has been placed")

spUtil - addTrivialMessage(String message)

Displays a trivial notification message.

Trivial messages disappear after a short period of time.

Table 5. Parameters
Name Type Description
message String Message to display.
Table 6. Returns
Type Description
spUtil.addTrivialMessage("Thanks for your order")

spUtil - format(String template, Object data)

Formats a string as an alternative to string concatenation.

Use this method to build a string with variables.

Table 7. Parameters
Name Type Description
template String

String template with values for substitution.

data Object Object containing variables for substitution.
Table 8. Returns
Type Description
String A formatted string.
spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})


'An error occurred: 404 when loading sp-widget'

spUtil - get(String widgetId)

Gets a widget model by ID or sys_id.

Use this method to embed a widget model in a widget client script. The callback function returns the full widget model.

Table 9. Parameters
Name Type Description
widgetId String The widget ID or sys_id of the widget to embed.
Table 10. Returns
Type Description
Object The model of the embedded widget.
spUtil.get("widget-cool-clock").then(function(response) {
    c.coolClock = response;

spUtil - refresh(Object $scope)

Calls the server and replaces the current options and data with the server response.

Calling spUtil.refresh() is similar to calling server.refresh(). However, when you call spUtil.refresh(), you can define the $scope object.

Table 11. Parameters
Name Type Description
$scope Object The scope defined for the update.
Table 12. Returns
Type Description
Object The updated options and data objects.

spUtil - update(Object $scope)

Updates the data object on the server within a given scope.

This method is similar to server.update(), but includes a $scope parameter that defines the scope to pass over.

Table 13. Parameters
Name Type Description
$scope Object The scope defined for the update.
Table 14. Returns
Type Description
Object The updated data object.

spUtil - recordWatch(Object $scope, String table, String filter, Function callback)

Watches for updates to a table or filter and returns the value from the callback function.

Allows a widget developer to respond to table updates in real-time. For instance, by using recordWatch(), the Simple List widget can listen for changes to its data table. If records are added, removed, or updated, the widget updates automatically.

When passing the $scope argument into the recordWatch() function, be sure to inject $scope into the parameters of your client script function.

Tables that are periodically subject to a high frequency of database events are blacklisted from recordWatch() to prevent event storms.

Table 15. Parameters
Name Type Description
$scope Object The scope of the data object updated by the callback function.
table String Watched table.
filter String Filter for fields to watch.
callback Function An optional parameter to define the callback function.
Table 16. Returns
Type Description
Promise The return value of the callback function.
//A simple recordWatch function.
spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

//In a widget client script
function(spUtil, $scope) {
  /* widget controller */
  var c =this;

  // Registers a listener on the incident table with the filter active=true, 
  // meaning that whenever something changes on that table with that filter, 
  // the callback function is executed.    
  // The callback function takes two parameters: name and data. 
  spUtil.recordWatch($scope, "incident", "active=true", function(name, data) {
    // Returns information about the event that has occurred 
    // Returns the data inserted or updated on the table