---
sourceDocument: Zurich API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/api-reference

 Release :

    - zurich

ft:locale :

    - en-US

ft:publication_title :

    - Zurich API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# spUtil - Client

# spUtil - Client {#ariaid-title1}

* Release version: Zurich
* 
* Updated July 31, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

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

* Display a notification error message. [spUtil - addErrorMessage(String message)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-addErrorMessage_S "Displays a notification error message.")
* Display a notification info message. [spUtil - addInfoMessage(String message)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-addInfoMessage_S "Displays a notification info message.")
* Display a trivial notification message. [spUtil - addTrivialMessage(String message)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-addTrivialMessage_S "Displays a trivial notification message.")
* Create a unique identifier. [spUtil - createUid()](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-createUid "Create a unique identifier.")
* Format a string with variables. [spUtil - format(String template, Object data)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-format_S_O "Formats a string that contains variables.")
* Embed a widget model in a widget client script. [spUtil - get(String widgetId Object data)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-get_S "Embeds a widget model in a widget client script.")
* Retrieve all headers to use for API calls. [spUtil - getHeaders()](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-getHeaders "Retrieves all headers to use for API calls.")
* Return the complete host domain. [spUtil - getHost()](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-getHost "Returns the complete host domain.")
* Execute the callback with User Preference response by passing the preference name. [spUtil - getPreference(String preference, Function callback)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-getPreference "Executes the callback with User Preference response by passing the preference name.")
* Return the current service portal URL information. [spUtil - getURL()](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-getURL "Returns the current service portal URL information.")
* Check if the current client is a mobile device. [spUtil - isMobile()](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-isMobile "Checks if the current client is a mobile device.")
* Parse the comma-separated attributes within a specified string. [spUtil - parseAttributes(String attributes)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-parseAttributes "Parses the comma-separated attributes within a specified string.")
* Watch for updates to a table or filter and returns the value from the callback function. [spUtil - recordWatch(Object $scope, String table, String filter, Function callback)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-recordWatch_O_S_S_F "Watches for updates to a table or filter and returns the value from the callback function.")
* Call the server and replaces the current options and data with the server response. [spUtil - refresh(Object $scope)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-refresh_O "Calls the server and replaces the current options and data with the server response.")
* Scroll to the element with the specified selector, over a specified period of time. [spUtil - scrollTo(String selector, Number time)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-scrollTo "Scrolls to the element with the specified selector, over a specified period of time.")
* Update the header breadcrumbs. [spUtil - setBreadCrumb(Object $scope, Array breadcrumbs)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-setBreadCrumb "Updates the header breadcrumbs.")
* Set a user preference. [spUtil - setPreference(String pref, String value)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-setPreference "Sets a user preference.")
* Update the search page. [spUtil - setSearchPage(String searchPage)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-setSearchPage "Updates the search page.")
* Update the data object on the server within a given scope. [spUtil - update(Object $scope)](https://www.servicenow.com/docs/PkmGHNNtp9Xj6QmnLYYZFg#SPU-update_O "Updates the data object on the server within a given scope.")

For additional information on widgets, see [Service Portal widgets](https://www.servicenow.com/docs/access?context=service-portal-widgets&version=zurich&pubname=zurich-platform-user-interface&ft:locale=en-US).

## spUtil - addErrorMessage(String message) {#ariaid-title2}

Displays a notification error message.
{#SPU-addErrorMessage_S__table_yjp_zpz_31b__entry__3}

| Name | Type | Description |
|-|-|-|
| message | String | Error message to display. |
[Table 1. Parameters]

{#SPU-addErrorMessage_S__table_yjp_zpz_31b} {#SPU-addErrorMessage_S__table_zjp_zpz_31b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 2. Returns]

{#SPU-addErrorMessage_S__table_zjp_zpz_31b}  

    spUtil.addErrorMessage("There has been an error processing your request")

## spUtil - addInfoMessage(String message) {#ariaid-title3}

Displays a notification info message.
{#SPU-addInfoMessage_S__table_b2m_bqz_31b__entry__3}

| Name | Type | Description |
|-|-|-|
| message | String | Message to display. |
[Table 3. Parameters]

{#SPU-addInfoMessage_S__table_b2m_bqz_31b} {#SPU-addInfoMessage_S__table_c2m_bqz_31b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 4. Returns]

{#SPU-addInfoMessage_S__table_c2m_bqz_31b}  

    spUtil.addInfoMessage("Your order has been placed")

## spUtil - addTrivialMessage(String message) {#ariaid-title4}

Displays a trivial notification message.
Trivial messages disappear after a short period of time.
{#SPU-addTrivialMessage_S__table_kcx_dqz_31b__entry__3}

| Name | Type | Description |
|-|-|-|
| message | String | Message to display. |
[Table 5. Parameters]

{#SPU-addTrivialMessage_S__table_kcx_dqz_31b} {#SPU-addTrivialMessage_S__table_lcx_dqz_31b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 6. Returns]

{#SPU-addTrivialMessage_S__table_lcx_dqz_31b}  

    spUtil.addTrivialMessage("Thanks for your order")

## spUtil - createUid() {#ariaid-title5}

Create a
unique
identifier.
{#SPU-createUid__table_ccv_cbr_t2b__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 7. Parameters]

{#SPU-createUid__table_ccv_cbr_t2b} {#SPU-createUid__table_dcv_cbr_t2b__entry__2}

| Type | Description |
|-|-|
| String | A unique 32 character ID. |
[Table 8. Returns]

{#SPU-createUid__table_dcv_cbr_t2b}

## spUtil - get(String widgetId Object data) {#ariaid-title6}

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](https://www.servicenow.com/docs/access?context=service-portal-widgets&version=zurich&pubname=zurich-platform-user-interface&ft:locale=en-US).
{#SPU-get_S__table_bcy_fqz_31b__entry__3}

| 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. |
[Table 9. Parameters]

{#SPU-get_S__table_bcy_fqz_31b} {#SPU-get_S__table_ccy_fqz_31b__entry__2}

| Type | Description |
|-|-|
| Object | Model of the embedded widget. |
[Table 10. Returns]

{#SPU-get_S__table_ccy_fqz_31b}  
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() {#ariaid-title7}

Retrieves all headers to use for API calls.
{#SPU-getHeaders__table_dns_ldr_t2b__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 11. Parameters]

{#SPU-getHeaders__table_dns_ldr_t2b} {#SPU-getHeaders__table_ens_ldr_t2b__entry__2}

| Type | Description |
|-|-|
| Object | All headers to use for API calls. |
[Table 12. Returns]

{#SPU-getHeaders__table_ens_ldr_t2b}

## spUtil - getHost() {#ariaid-title8}

Returns the complete host domain.
{#SPU-getHost__table_olb_vkr_t2b__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 13. Parameters]

{#SPU-getHost__table_olb_vkr_t2b} {#SPU-getHost__table_plb_vkr_t2b__entry__2}

| Type | Description |
|-|-|
| String | The complete host domain, for example `hi.servicenow.com` |
[Table 14. Returns]

{#SPU-getHost__table_plb_vkr_t2b}

## spUtil - getPreference(String preference, Function callback) {#ariaid-title9}

Executes the callback with User Preference response by passing the preference
name.
{#SPU-getPreference__table_rvb_34r_t2b__entry__3}

| Name | Type | Description |
|-|-|-|
| preference | String | Name of the preference. |
| callback | Function | Define the callback function. |
[Table 15. Parameters]

{#SPU-getPreference__table_rvb_34r_t2b} {#SPU-getPreference__table_svb_34r_t2b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 16. Returns]

{#SPU-getPreference__table_svb_34r_t2b}

## spUtil - getURL() {#ariaid-title10}

Returns the current service portal URL information.
{#SPU-getURL__table_sbh_dls_t2b__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 17. Parameters]

{#SPU-getURL__table_sbh_dls_t2b} {#SPU-getURL__table_tbh_dls_t2b__entry__2}

| Type | Description |
|-|-|
| String | Current service portal URL. |
[Table 18. Returns]

{#SPU-getURL__table_tbh_dls_t2b}

## spUtil - format(String template, Object data) {#ariaid-title11}

Formats a string that contains variables.
Use this method as an alternative to string concatenation.
{#SPU-format_S_O__table_yrh_hqz_31b__entry__3}

| 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. |
[Table 19. Parameters]

{#SPU-format_S_O__table_yrh_hqz_31b} {#SPU-format_S_O__table_zrh_hqz_31b__entry__2}

| Type | Description |
|-|-|
| String | String containing the variable values instead of the variable nomenclature. |
[Table 20. Returns]

{#SPU-format_S_O__table_zrh_hqz_31b}  

    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() {#ariaid-title12}

Checks if the current client is a mobile device.
{#SPU-isMobile__table_gz2_pcd_v2b__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 21. Parameters]

{#SPU-isMobile__table_gz2_pcd_v2b} {#SPU-isMobile__table_hz2_pcd_v2b__entry__2}

| 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. {#SPU-isMobile__ul_fpx_gsv_fvb} |
[Table 22. Returns]

{#SPU-isMobile__table_hz2_pcd_v2b}

## spUtil - parseAttributes(String attributes) {#ariaid-title13}

Parses the comma-separated attributes within a specified string.
{#SPU-parseAttributes__table_jkb_tvm_w2b__entry__3}

| Name | Type | Description |
|-|-|-|
| attributes | String | String containing comma separated attributes, such as the Attributes field of a dictionary record. |
[Table 23. Parameters]

{#SPU-parseAttributes__table_jkb_tvm_w2b} {#SPU-parseAttributes__table_kkb_tvm_w2b__entry__2}

| Type | Description |
|-|-|
| Array | Array of objects containing the parsed attributes. |
[Table 24. Returns]

{#SPU-parseAttributes__table_kkb_tvm_w2b}  

    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) {#ariaid-title14}

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.  
Note:  
When passing the `$scope` argument into the recordWatch() function, inject `$scope` into the parameters of your client script function.
{#SPU-recordWatch_O_S_S_F__table_vys_mqz_31b__entry__3}

| 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. |
[Table 25. Parameters]

{#SPU-recordWatch_O_S_S_F__table_vys_mqz_31b} {#SPU-recordWatch_O_S_S_F__table_wys_mqz_31b__entry__2}

| Type | Description |
|-|-|
| Promise | Return value of the callback function. |
[Table 26. Returns]

{#SPU-recordWatch_O_S_S_F__table_wys_mqz_31b}  

    //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) {#ariaid-title15}

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.
{#SPU-refresh_O__table_p2k_kqz_31b__entry__3}

| Name | Type | Description |
|-|-|-|
| $scope | Object | Scope defined for the update. |
[Table 27. Parameters]

{#SPU-refresh_O__table_p2k_kqz_31b} {#SPU-refresh_O__table_q2k_kqz_31b__entry__2}

| Type | Description |
|-|-|
| Object | Updated options and data objects. |
[Table 28. Returns]

{#SPU-refresh_O__table_q2k_kqz_31b}

## spUtil - scrollTo(String selector, Number time) {#ariaid-title16}

Scrolls to the element with the specified selector, over a specified period of
time.
{#SPU-scrollTo__table_drd_wzp_v2b__entry__3}

| Name | Type | Description |
|-|-|-|
| selector | String | Selector to scroll to. |
| time | Number | Time taken to scroll to the specified selector. Unit: Milliseconds |
[Table 29. Parameters]

{#SPU-scrollTo__table_drd_wzp_v2b} {#SPU-scrollTo__table_erd_wzp_v2b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 30. Returns]

{#SPU-scrollTo__table_erd_wzp_v2b}

## spUtil - setBreadCrumb(Object $scope, Array breadcrumbs) {#ariaid-title17}

Updates the header breadcrumbs.
{#SPU-setBreadCrumb__table_sqx_jkr_v2b__entry__3}

| Name | Type | Description |
|-|-|-|
| $scope | Object | Scope defined for the table. |
| breadcrumbs | Array | Conditions used to create the breadcrumb filter. |
[Table 31. Parameters]

{#SPU-setBreadCrumb__table_sqx_jkr_v2b} {#SPU-setBreadCrumb__table_tqx_jkr_v2b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 32. Returns]

{#SPU-setBreadCrumb__table_tqx_jkr_v2b}

## spUtil - setPreference(String pref, String value) {#ariaid-title18}

Sets a user preference.
{#SPU-setPreference__table_m1m_1hl_w2b__entry__3}

| Name | Type | Description |
|-|-|-|
| pref | String | Preference name |
| value | String | Preference value |
[Table 33. Parameters]

{#SPU-setPreference__table_m1m_1hl_w2b} {#SPU-setPreference__table_n1m_1hl_w2b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 34. Returns]

{#SPU-setPreference__table_n1m_1hl_w2b}

## spUtil - setSearchPage(String searchPage) {#ariaid-title19}

Updates the search page.
{#SPU-setSearchPage__table_hm4_v4l_w2b__entry__3}

| Name | Type | Description |
|-|-|-|
| searchPage | String | Name of the search page. |
[Table 35. Parameters]

{#SPU-setSearchPage__table_hm4_v4l_w2b} {#SPU-setSearchPage__table_im4_v4l_w2b__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 36. Returns]

{#SPU-setSearchPage__table_im4_v4l_w2b}

## spUtil - update(Object $scope) {#ariaid-title20}

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.
{#SPU-update_O__table_hpd_4qz_31b__entry__3}

| Name | Type | Description |
|-|-|-|
| $scope | Object | Scope defined for the update. |
[Table 37. Parameters]

{#SPU-update_O__table_hpd_4qz_31b} {#SPU-update_O__table_ipd_4qz_31b__entry__2}

| Type | Description |
|-|-|
| Object | Updated data object. |
[Table 38. Returns]

{#SPU-update_O__table_ipd_4qz_31b}  
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);
       }
    });