spUtil - Client

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 6 minutes de lecture

    • The spUtil API provides utility methods to perform common functions in a Service Portal widget client script.

    These functions include:

    For additional information on widgets, see Service Portal widgets.

    spUtil - addErrorMessage(String message)

    Displays a notification error message.

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

    spUtil - addInfoMessage(String message)

    Displays a notification info message.

    Tableau 3. Parameters
    Name Type Description
    message String Message to display.
    Tableau 4. Returns
    Type Description
    void 
    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.

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

    spUtil - createUid()

    Create a unique identifier.

    Tableau 7. Parameters
    Name Type Description
    None
    Tableau 8. Returns
    Type Description
    String A unique 32 character ID.

    spUtil - get(String widgetId Object data)

    Embeds a widget model in a widget client script.

    The callback function returns the full widget model. For additional information on widgets, see Service Portal widgets.

    Tableau 9. Parameters
    Name Type Description
    widgetId String Widget ID or sys_id of the widget to embed.
    data Object Optional. Name/value pairs of parameters to pass to the widget model.
    Tableau 10. Returns
    Type Description
    Object Model of the embedded widget.

    Without data passed.

    spUtil.get("widget-cool-clock").then(function(response) {
  c.coolClock = response;
});

    With data passed.

    spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
  table: 'resource_allocation', 
  queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
  view: 'resource_portal_allocations' }).then(function(response) {
    var formModal = response;
    c.allocationListModal = response;
  });

    spUtil - getHeaders()

    Retrieves all headers to use for API calls.

    Tableau 11. Parameters
    Name Type Description
    None
    Tableau 12. Returns
    Type Description
    Object All headers to use for API calls.

    spUtil - getHost()

    Returns the complete host domain.

    Tableau 13. Parameters
    Name Type Description
    None
    Tableau 14. Returns
    Type Description
    String The complete host domain, for example hi.servicenow.com

    spUtil - getPreference(String preference, Function callback)

    Executes the callback with User Preference response by passing the preference name.

    Tableau 15. Parameters
    Name Type Description
    preference String Name of the preference.
    callback Function Define the callback function.
    Tableau 16. Returns
    Type Description
    void

    spUtil - getURL()

    Returns the current service portal URL information.

    Tableau 17. Parameters
    Name Type Description
    None
    Tableau 18. Returns
    Type Description
    String Current service portal URL.

    spUtil - format(String template, Object data)

    Formats a string that contains variables.

    Use this method as an alternative to string concatenation.

    Tableau 19. Parameters
    Name Type Description
    template String String template that contains values for variable substitution.
    data Object Object containing the values for the variables defined in the template string.
    Tableau 20. Returns
    Type Description
    String String containing the variable values instead of the variable nomenclature. 
    spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

    Output:

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

    spUtil - isMobile()

    Checks if the current client is a mobile device.

    Tableau 21. Parameters
    Name Type Description
    None
    Tableau 22. Returns
    Type Description
    Boolean Flag that indicates whether the current client is a mobile device.
    Valid values:
    • true: Current client is a mobile device.
    • false: Current client is not a mobile device.

    spUtil - parseAttributes(String attributes)

    Parses the comma-separated attributes within a specified string.

    Tableau 23. Parameters
    Name Type Description
    attributes String String containing comma separated attributes, such as the Attributes field of a dictionary record.
    Tableau 24. Returns
    Type Description
    Array Array of objects containing the parsed attributes. 
    function getRefQualElements() {
  var refQualElements = [];
  if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
    var attributes = spUtil.parseAttributes(field.attributes);
    refQualElements = attributes['ref_qual_elements'].split(';');
  }
  return refQualElements;
}

    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.

    Remarque :
    When passing the $scope argument into the recordWatch() function, inject $scope into the parameters of your client script function.
    Tableau 25. Parameters
    Name Type Description
    $scope Object Scope of the data object updated by the callback function.
    table String Watched table.
    filter String Filter for fields to watch.
    callback Function Optional. Parameter to define the callback function.
    Tableau 26. Returns
    Type Description
    Promise 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 a single parameter 'response', which contains 
  // the property 'data'. The 'data' property contains information about the changed record. 
  spUtil.recordWatch($scope, "incident", "active=true", function(response) {
        
    // Returns the data inserted or updated on the table 
    console.log(response.data);   
    
    });
}

    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.

    Tableau 27. Parameters
    Name Type Description
    $scope Object Scope defined for the update.
    Tableau 28. Returns
    Type Description
    Object Updated options and data objects.

    spUtil - scrollTo(String selector, Number time)

    Scrolls to the element with the specified selector, over a specified period of time.

    Tableau 29. Parameters
    Name Type Description
    selector String Selector to scroll to.
    time Number Time taken to scroll to the specified selector.

    Unit: Milliseconds
    Tableau 30. Returns
    Type Description
    void

    spUtil - setBreadCrumb(Object $scope, Array breadcrumbs)

    Updates the header breadcrumbs.

    Tableau 31. Parameters
    Name Type Description
    $scope Object Scope defined for the table.
    breadcrumbs Array Conditions used to create the breadcrumb filter.
    Tableau 32. Returns
    Type Description
    void

    spUtil - setPreference(String pref, String value)

    Sets a user preference.

    Tableau 33. Parameters
    Name Type Description
    pref String Preference name
    value String Preference value
    Tableau 34. Returns
    Type Description
    void

    spUtil - setSearchPage(String searchPage)

    Updates the search page.

    Tableau 35. Parameters
    Name Type Description
    searchPage String Name of the search page.
    Tableau 36. Returns
    Type Description
    void

    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.

    Tableau 37. Parameters
    Name Type Description
    $scope Object Scope defined for the update.
    Tableau 38. Returns
    Type Description
    Object Updated data object.

    The following example includes a P1 widget that watches for changes to the state field and uses a filter to watch all active P1s and let the callback function determine whether to refresh the data. The data.changes property contains an array of any updated fields. If the state of any fields have changed, the data is updated in the widget.

    var q = "priority=1^active=true^EQ";
spUtil.recordWatch($scope, "incident", q, function(event, data) {
   if (data.changes.includes("state")) { // only update if state was updated.
      spUtil.update($scope);
   }
});