{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1155,"path":"api-reference/spUtilAPI.md","title":"spUtil - Client","bundle":null,"doc_type":null,"release":"australia","body":"\n# spUtil- Client\n\nThe spUtil API provides utility methods to perform common functions in a Service Portal widget client script.\n\nThese functions include:\n\n-   Display a notification error message. [spUtil - addErrorMessage\\(String message\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Display a notification info message. [spUtil - addInfoMessage\\(String message\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Display a trivial notification message. [spUtil - addTrivialMessage\\(String message\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Create a unique identifier. [spUtil - createUid\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Format a string with variables. [spUtil - format\\(String template, Object data\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Embed a widget model in a widget client script. [spUtil - get\\(String widgetId Object data\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Retrieve all headers to use for API calls. [spUtil - getHeaders\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Return the complete host domain. [spUtil - getHost\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Execute the callback with User Preference response by passing the preference name. [spUtil - getPreference\\(String preference, Function callback\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Return the current service portal URL information. [spUtil - getURL\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Check if the current client is a mobile device. [spUtil - isMobile\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Parse the comma-separated attributes within a specified string. [spUtil - parseAttributes\\(String attributes\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Call the server and replaces the current **options** and **data** with the server response. [spUtil - refresh\\(Object $scope\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Scroll to the element with the specified selector, over a specified period of time. [spUtil - scrollTo\\(String selector, Number time\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Update the header breadcrumbs. [spUtil - setBreadCrumb\\(Object $scope, Array breadcrumbs\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Set a user preference. [spUtil - setPreference\\(String pref, String value\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Update the search page. [spUtil - setSearchPage\\(String searchPage\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n-   Update the data object on the server within a given scope. [spUtil - update\\(Object $scope\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/spUtilAPI.md)\n\nFor additional information on widgets, see [Service Portal widgets](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-user-interface/service-portal-widgets.md).\n\n**Parent Topic:**[Client API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/api-client.md)\n\n## spUtil - addErrorMessage\\(String message\\)\n\nDisplays a notification error message.\n\n|Name|Type|Description|\n|----|----|-----------|\n|message|String|Error message to display.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nspUtil.addErrorMessage(\"There has been an error processing your request\")\n```\n\n## spUtil - addInfoMessage\\(String message\\)\n\nDisplays a notification info message.\n\n|Name|Type|Description|\n|----|----|-----------|\n|message|String|Message to display.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nspUtil.addInfoMessage(\"Your order has been placed\")\n```\n\n## spUtil - addTrivialMessage\\(String message\\)\n\nDisplays a trivial notification message.\n\nTrivial messages disappear after a short period of time.\n\n|Name|Type|Description|\n|----|----|-----------|\n|message|String|Message to display.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\nspUtil.addTrivialMessage(\"Thanks for your order\")\n```\n\n## spUtil - createUid\\(\\)\n\nCreate a unique identifier.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|A unique 32 character ID.|\n\n## spUtil - get\\(String widgetId Object data\\)\n\nEmbeds a widget model in a widget client script.\n\nThe callback function returns the full widget model. For additional information on widgets, see [Service Portal widgets](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-user-interface/service-portal-widgets.md).\n\n|Name|Type|Description|\n|----|----|-----------|\n|widgetId|String|Widget ID or sys\\_id of the widget to embed.|\n|data|Object|Optional. Name/value pairs of parameters to pass to the widget model.|\n\n|Type|Description|\n|----|-----------|\n|Object|Model of the embedded widget.|\n\nWithout data passed.\n\n```\nspUtil.get(\"widget-cool-clock\").then(function(response) {\n  c.coolClock = response;\n});\n```\n\nWith data passed.\n\n```\nspUtil.get('pps-list-modal', {title: c.data.editAllocations, \n  table: 'resource_allocation', \n  queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, \n  view: 'resource_portal_allocations' }).then(function(response) {\n    var formModal = response;\n    c.allocationListModal = response;\n  });  \t\n\n```\n\n## spUtil - getHeaders\\(\\)\n\nRetrieves all headers to use for API calls.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Object|All headers to use for API calls.|\n\n## spUtil - getHost\\(\\)\n\nReturns the complete host domain.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|The complete host domain, for example `hi.servicenow.com`|\n\n## spUtil - getPreference\\(String preference, Function callback\\)\n\nExecutes the callback with User Preference response by passing the preference name.\n\n|Name|Type|Description|\n|----|----|-----------|\n|preference|String|Name of the preference.|\n|callback|Function|Define the callback function.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## spUtil - getURL\\(\\)\n\nReturns the current service portal URL information.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|Current service portal URL.|\n\n## spUtil - format\\(String template, Object data\\)\n\nFormats a string that contains variables.\n\nUse this method as an alternative to string concatenation.\n\n|Name|Type|Description|\n|----|----|-----------|\n|template|String|String template that contains values for variable substitution.|\n|data|Object|Object containing the values for the variables defined in the template string.|\n\n|Type|Description|\n|----|-----------|\n|String|String containing the variable values instead of the variable nomenclature.|\n\n```\nspUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})\n```\n\nOutput:\n\n```\n'An error occurred: 404 when loading sp-widget'\n```\n\n## spUtil - isMobile\\(\\)\n\nChecks if the current client is a mobile device.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n<table id=\"table_hz2_pcd_v2b\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the current client is a mobile device.Valid values:\n\n-   true: Current client is a mobile device.\n-   false: Current client is not a mobile device.\n\n</td></tr></tbody>\n</table>## spUtil - parseAttributes\\(String attributes\\)\n\nParses the comma-separated attributes within a specified string.\n\n|Name|Type|Description|\n|----|----|-----------|\n|attributes|String|String containing comma separated attributes, such as the Attributes field of a dictionary record.|\n\n|Type|Description|\n|----|-----------|\n|Array|Array of objects containing the parsed attributes.|\n\n```\nfunction getRefQualElements() {\n  var refQualElements = [];\n  if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {\n    var attributes = spUtil.parseAttributes(field.attributes);\n    refQualElements = attributes['ref_qual_elements'].split(';');\n  }\n  return refQualElements;\n}\n```\n\n## spUtil - recordWatch\\(Object $scope, String table, String filter, Function callback\\)\n\nWatches for updates to a table or filter and returns the value from the callback function.\n\nAllows 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.\n\n**Note:** When passing the `$scope` argument into the recordWatch\\(\\) function, inject `$scope` into the parameters of your client script function.\n\n|Name|Type|Description|\n|----|----|-----------|\n|$scope|Object|Scope of the data object updated by the callback function.|\n|table|String|Watched table.|\n|filter|String|Filter for fields to watch.|\n|callback|Function|Optional. Parameter to define the callback function.|\n\n|Type|Description|\n|----|-----------|\n|Promise|Return value of the callback function.|\n\n```\n//A simple recordWatch function.\nspUtil.recordWatch($scope, \"live_profile\", \"sys_id=\" + liveProfileId);\n\n//In a widget client script\nfunction(spUtil, $scope) {\n  /* widget controller */\n  var c =this;\n\n  // Registers a listener on the incident table with the filter active=true, \n  // meaning that whenever something changes on that table with that filter, \n  // the callback function is executed.    \n  // The callback function takes a single parameter 'response', which contains \n  // the property 'data'. The 'data' property contains information about the changed record. \n  spUtil.recordWatch($scope, \"incident\", \"active=true\", function(response) {\n        \n    // Returns the data inserted or updated on the table \n    console.log(response.data);   \n    \n    });\n}\n```\n\n## spUtil - refresh\\(Object $scope\\)\n\nCalls the server and replaces the current **options** and **data** with the server response.\n\nCalling `spUtil.refresh()` is similar to calling `server.refresh()`. However, when you call `spUtil.refresh()`, you can define the $scope object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|$scope|Object|Scope defined for the update.|\n\n|Type|Description|\n|----|-----------|\n|Object|Updated options and data objects.|\n\n## spUtil - scrollTo\\(String selector, Number time\\)\n\nScrolls to the element with the specified selector, over a specified period of time.\n\n<table id=\"table_drd_wzp_v2b\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nselector\n\n</td><td>\n\nString\n\n</td><td>\n\nSelector to scroll to.\n\n</td></tr><tr><td>\n\ntime\n\n</td><td>\n\nNumber\n\n</td><td>\n\nTime taken to scroll to the specified selector.Unit: Milliseconds\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n## spUtil - setBreadCrumb\\(Object $scope, Array breadcrumbs\\)\n\nUpdates the header breadcrumbs.\n\n|Name|Type|Description|\n|----|----|-----------|\n|$scope|Object|Scope defined for the table.|\n|breadcrumbs|Array|Conditions used to create the breadcrumb filter.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## spUtil - setPreference\\(String pref, String value\\)\n\nSets a user preference.\n\n|Name|Type|Description|\n|----|----|-----------|\n|pref|String|Preference name|\n|value|String|Preference value|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## spUtil - setSearchPage\\(String searchPage\\)\n\nUpdates the search page.\n\n|Name|Type|Description|\n|----|----|-----------|\n|searchPage|String|Name of the search page.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## spUtil - update\\(Object $scope\\)\n\nUpdates the data object on the server within a given scope.\n\nThis method is similar to `server.update()`, but includes a $scope parameter that defines the scope to pass over.\n\n|Name|Type|Description|\n|----|----|-----------|\n|$scope|Object|Scope defined for the update.|\n\n|Type|Description|\n|----|-----------|\n|Object|Updated data object.|\n\nThe 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.\n\n```\nvar q = \"priority=1^active=true^EQ\";\nspUtil.recordWatch($scope, \"incident\", q, function(event, data) {\n   if (data.changes.includes(\"state\")) { // only update if state was updated.\n      spUtil.update($scope);\n   }\n});\n```\n\n"}}