---
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


---

# helpers - UI Builder

# helpers - UI Builder {#ariaid-title1}

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

The helpers API provides general functionality that is common across
page scripts, eliminating the need to write scripts for simple functionality such as opening and
closing a modal.  
This API is only available to page scripts, it is not available in any other UI Builder scripts including:

* component property value scripts
* component visibility scripts
* event payload scripts
* UX client script includes

## helpers - helpers.modal.close(String modalId) {#ariaid-title2}

Closes the specified modal on the current page.
{#helpers-modal-close_S__table_o3x_fyy_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| modalId | String | Modal component ID of the modal to close. Component IDs are auto generated when a component is dragged and dropped on the UI Builder stage. You can locate the ID on the property page. |
[Table 1. Parameters]

{#helpers-modal-close_S__table_o3x_fyy_n4b} {#helpers-modal-close_S__table_p3x_fyy_n4b__entry__2}

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

{#helpers-modal-close_S__table_p3x_fyy_n4b}  
This example shows closing a modal with a component ID that ends with
`alert-modal`.

    function handler({api, event, imports, helpers}) {
      helpers.modal.close("[component-id$='alert_modal']")
    }

## helpers - helpers.modal.open(String modalId, Object options) {#ariaid-title3}

Opens the specified modal on the current page.
You can only display one modal at a time within a page. If a modal is currently open, and
you call this method, the existing modal is hidden and the new modal appears.
{#helpers-modal-open_S_O__table_mmh_5ky_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| modalId | String | Component ID of the modal to open. Component IDs are auto generated when a component is dragged and dropped on the UI Builder stage. You can locate the ID on the property page. |
| options | Object | Optional. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" } |
| options.content | String | Text content for the modal. |
| options.contentFullWidth | Boolean | Flag that indicates whether to remove the horizontal padding around the body of the modal in order to fit wider content. Valid values: * true: Remove the padding. * false: Do not remove the padding. Default: false |
| options.headerLabel | String | Text content for the modal header. |
| options.size | String | Size of the modal container. Most sizes automatically expand to fill the viewport when the screen size is small. Valid values: * sm * md * lg * fullscreen Default: sm |
[Table 3. Parameters]

{#helpers-modal-open_S_O__table_mmh_5ky_n4b} {#helpers-modal-open_S_O__table_nmh_5ky_n4b__entry__2}

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

{#helpers-modal-open_S_O__table_nmh_5ky_n4b}  
This example shows opening a modal with ca omponent ID that ends with
`alert-modal`.

    function handler({api, event, imports, helpers}) {
      helpers.modal.open("[component-id$='alert_modal']")
    }

## helpers - helpers.navigate.setRouteParams(Object params) {#ariaid-title4}

Passes the specified parameters down to other components on the same page.
Use this method in any page component that wants to add a parameter in a URL. You may want
to add a parameter to a URL when another component needs to know the current value of that
parameter when it changes, so it can react to it. For example, use this method to pass the
`selectedIndex` of a tab component so it reflected in the URL to give focus
to that tab.
{#helpers-nav-setRteParms_O__table_jnx_kf1_p4b__entry__3}

| Name | Type | Description |
|-|-|-|
| params | Object | Key-value pairs of optional parameters to pass to other components. This must be a plain, flat object with only primitive values. Array or object references are ignored and not added to the URL. All specified keys  must be part of  the optional parameters  in the route configuration or they are also ignored. For additional information on optional parameters, see [Create a page in UI Builder.](https://www.servicenow.com/docs/access?context=create-page&version=zurich&pubname=zurich-application-development&ft:locale=en-US) |
[Table 5. Parameters]

{#helpers-nav-setRteParms_O__table_jnx_kf1_p4b} {#helpers-nav-setRteParms_O__table_knx_kf1_p4b__entry__2}

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

{#helpers-nav-setRteParms_O__table_knx_kf1_p4b}  
This code example shows how to append the URL `params/selected-tab-index/2`.
Note that the parameter in the actual URL is changed from camel case to snake case, so
`selectedTabIndex` becomes `selected-tab-index`.

    function handler({api, event, helpers, imports}) {  
      helpers.navigate.setRouteParams({'params': {'selectedTabIndex':  2}});  
    } 

## helpers - helpers.navigate.to(String route, Object fields, Object params, Boolean redirect,
Boolean passiveNavigation, String targetRoute) {#ariaid-title5}

Navigates from one screen to another based on the specified route and field
information. URL changes and the respective screen loads are observed.
{#helpers-nav-to_S_O_O_B_B_S__table_htg_jzy_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| route | String | Name of the route. Must be a valid entry from UX App Routes (sys_ux_app_route.list). This value is reflected in the URL, and the URL is created based on the route, fields, and optionalParams column values: `/<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2>` For example: `/record/incident/12345/params/selectedTabIndex/4` |
| fields | Object | Optional. Key-value pairs of required parameters. For example: `'fields' : {'table': 'incident', 'sysId': '12345'}`. |
| params | Object | Optional. Key-value pairs of optional parameters. For example: `'params' : {'selectedTabIndex': 4}`. |
| redirect | Boolean | Flag that indicates whether to remove the latest history entry from the browser history. For example, if you navigate to sites A, B and then C. If redirect is set to `true` while navigating to C, the history entry for B is removed. The browser history only shows only A and C. Valid values: * true: Removes the latest history entry, and redirects to the latest URL. * false: Does not remove any history entries. {#helpers-nav-to_S_O_O_B_B_S__ul_rl3_jc1_p4b} Default: false |
| passiveNavigation | Boolean | Flag that indicates whether to perform background navigation. Background navigation is when a page is opened but it is not active or shown. For example, opening an inactive tab for the page, but it is not visible but loaded in the background. Valid values: * true: Perform background navigation. * false: Do not perform background navigation. {#helpers-nav-to_S_O_O_B_B_S__ul_ctk_sc1_p4b} Default: false |
| targetRoute | String or Object | Sub navigation to a drill-down, deep-link, or sub-tab. If set to `current`, the current route does a sub-navigation under the current URL. For example, if `/record/incident/123` is the current URL, and the following call is made: `helper.navigate.to('record', {'table': 'problem', 'sysId': '567'}, {}, false, false, 'current');` The following URL is generated: `/record/incident/123/sub/record/problem/567` Note: targetRoute can be either a string such as `'current'` or an object, such as `navigation NAV_ITEM_SELECTED payload`. |
[Table 7. Parameters]

{#helpers-nav-to_S_O_O_B_B_S__table_htg_jzy_n4b} {#helpers-nav-to_S_O_O_B_B_S__table_itg_jzy_n4b__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 8. Returns]

{#helpers-nav-to_S_O_O_B_B_S__table_itg_jzy_n4b}  
This example shows how to navigate to a page passing just the route
parameter.

    function handler({api, event, imports, helpers}) {
      helpers.navigate.to('test');
    }

This example shows how to navigate to a page passing the route and
fields parameters.

    function handler({api, event, imports, helpers}) {
      helpers.navigate.to('test', {'key': 'value'});
    }

This example shows how to navigate to a page passing the route,
fields, and params parameters.

    function handler({api, event, helpers, imports}) {
      helpers.navigate.to('test', {'key': 'value'}, {'first': 'FirstName', 'last': 'Last Name'});
    }

## helpers - helpers.screen.updateStatus(Object statusObj) {#ariaid-title6}

Enables pages to report their status updates, such as title, icon, dirty state,
message, and error changes.
Status updates are reported to WorkspaceChrome or AppShell, whichever the outer layer is,
and acting as the host.
{#helpers-screen-updateStatus_O__table_hwx_j31_p4b__entry__3}

| Name | Type | Description |
|-|-|-|
| statusObj | Object | Payload to send to the current page to report that the content has been updated. Valid values: * dirtyModalId: (String) ID of the modal that has changed. * hasError: (Boolean) Flag that indicates that there are errors on the page. * hasUpdate: (Boolean) Flag that indicates that there were updates to the page. * icon: (String) Name of the updated or new icon. * isDirty: (Boolean) Flag that indicates whether the page is dirty (values have changed). * message: (String) Updated/new message. * screenKey: (String) ID of the screen on which the change occurred. Every screen has a screenKey as a property on the screen macroponent inside sn-canvas-screen. * status: (String) Status operation for this action. This value must be one of the following: inserted, deleted, saved, or closed. * title: (String) Updated/new display title. * tooltipPreview: (JSON) Updated or new tool tip. For example, `tooltipPreview : { primaryTitle, secondaryContent: {} }` |
[Table 9. Parameters]

{#helpers-screen-updateStatus_O__table_hwx_j31_p4b} {#helpers-screen-updateStatus_O__table_iwx_j31_p4b__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 10. Returns]

{#helpers-screen-updateStatus_O__table_iwx_j31_p4b}  
<br />

    screen.updateStatus({'dirtyModalId': 'customModalId', 'isDirty': true});

## helpers - helpers.snHttp(String url, Object options) {#ariaid-title7}

Makes an HTTP request to the ServiceNow instance and returns a
promise with the results.
Note:  
There is a known issue where objects named options are omitted from the HTTP response.

    {
      options: {},
      otherFields: {}
    }

    becomes

    {
      otherFields: {}
    }

{#helpers-snHttp_S_O__table_o4d_4rr_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| url | String | HTTP endpoint relative to the instance URL. For example, `/api/now/table/incident` or `/api/now/table/incident/a83820b58f723300e7e16c7827bdeed`. |
| options | Object | Describes the contents of the HTTP request. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" } |
| options.batch | Boolean | Optional. Flag that indicates whether this HTTP request should be batched with other HTTP requests made to the instance. Valid values: * true: Make request as part of a batch request. * false: Make dedicated request. Default: true |
| options.body | Object | Optional. Data to send as the request body. Only applicable for request methods `PUT`, `POST`, and `PATCH`. Elements in the object depend on the type of HTTP method. For details, refer to the code examples below. Default: `{}` |
| options.headers | Object | Optional. Additional HTTP request headers. For example: headers: { "Content-Type": "application/json", "Accept": "application/xml" } |
| options.method | String | Optional. HTTP method. Valid values: * DELETE * GET * PATCH * POST * PUT Default: GET |
[Table 11. Parameters]

{#helpers-snHttp_S_O__table_o4d_4rr_n4b} {#helpers-snHttp_S_O__table_p4d_4rr_n4b__entry__2}

| Type | Description |
|-|-|
| error | Object that describes any error returned by the REST API. Data type: Object "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" } |
| error.data | Response returned from the HTTP API. Data type: Defined by REST API |
| error.message | Message describing the error encountered when trying to process the HTTP request. Note: This parameter is not always returned. Data type: String |
| error.options | Describes the original HTTP request. Data type: Object "options": { "headers": {Object}, "responseHeader": {Object} } |
| error.options.headers | Object containing a list of all of the request headers sent in the request. Data type: Object |
| error.options.responseHeaders | Object containing a list of all of the response headers sent in the request. Data type: Object |
| error.status | Returned HTTP error status code, such as 400, 405, or 500. Data type: Number |
| error.statusText | Returned HTTP status message, such as Bad Request. Data type: String |
| response | Returned when HTTP request is successful. The response to the HTTP request. Data type: Any |
[Table 12. Returns]

{#helpers-snHttp_S_O__table_p4d_4rr_n4b}  
The following example show how to call snHttp() which returns a
promise.

    function handler({api, event, helpers, imports}) {
      helpers.snHttp('/api/now/table/u_movie', {method: 'GET'})
        .then(({response}) => {
          // do something with the table data
        })
        .catch(({error}) => {
          const message = `Error: ${error.data.error.message}`;
          console.error(message);
          api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
            id: 'alert5',
            status: 'high',
            icon: 'info-circle-outline',
            content: message,
            action: { type: 'dismiss' }
        });
      });
    }

The following example show how to call snHttp() using
<var class="keyword varname">async</var> and <var class="keyword varname">await</var>.

    async function handler({helpers}) {
      try {
        const result = await helpers.snHttp('/api/now/table/u_movie', {method: 'GET'});
      } catch ({error}) {
          const message = `Error: ${error.data.error.message}`;
          console.error(message);
          api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
            id: 'alert5',
            status: 'high',
            icon: 'info-circle-outline',
            content: message,
            action: { type: 'dismiss' }
          });
      }
    }

The following example show how to set up a POST request.

    function handler({api, helpers, event, imports}) {
      helpers
        .snHttp("/api/now/table/incident", {
          method: "POST",
          body: {
            description: "Sample description",
            close_notes: "Sample close notes",
            order: "-1"
          }
        })
        .then(({ response }) => {
          // handle POST request response
        })
        .catch(({ error }) => {
          // handle POST request errors
        });
    }

The following example show how to set up a PUT request.

    function handler({api, helpers, event, imports}) {
      helpers
        .snHttp("/api/now/table/incident/a83820b58f723300e7e16c7827bdeed2", {
          method: "PUT",
          body: {
            activity_due: "1970-04-02 18:26:17"
          },
          headers: {
            "Content-Type": "application/json",
            "Accept": "application/xml"
          }
        })
        .then(({ response }) => {
          // handle PUT request response
        })
        .catch(({ error }) => {
          // handle PUT request errors
        });
    }

## helpers - helpers.timing.clearInterval(Number timeoutId) {#ariaid-title8}

Cancels the execution of the function that was scheduled through a prior
setInterval() call.
{#helpers-timing-clrInterval_N__table_sm4_kjx_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| timeoutId | Number | Unique identifier of the scheduled function to clear. This value is returned by the corresponding setInterval() call. |
[Table 13. Parameters]

{#helpers-timing-clrInterval_N__table_sm4_kjx_n4b} {#helpers-timing-clrInterval_N__table_tm4_kjx_n4b__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 14. Returns]

{#helpers-timing-clrInterval_N__table_tm4_kjx_n4b}  
This example shows using clearInterval() to cancel a timing operation
that was previously set using thesetInterval() method. This function
could be invoked by a user clicking a Disable Auto-refresh button on
a page.

    function handler({api, helpers}) {
      api.setState('intervalId', ({currentValue}) => {
        if (currentValue > -1) {
          helpers.timing.clearInterval(currentValue);
        }
        return -1;
      });
    }

## helpers - helpers.timing.clearTimeout(Number timeoutId) {#ariaid-title9}

Cancels the execution of the function that was scheduled through a prior
setTimeout() call.
{#helpers-timing-clrTimeout_N__table_w1r_vhy_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| timeoutId | Number | Unique identifier of the scheduled function to clear. This value is returned by the corresponding setTimeout() call. |
[Table 15. Parameters]

{#helpers-timing-clrTimeout_N__table_w1r_vhy_n4b} {#helpers-timing-clrTimeout_N__table_x1r_vhy_n4b__entry__2}

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

{#helpers-timing-clrTimeout_N__table_x1r_vhy_n4b}  
This code example shows how to terminate a timer with the specified
<var class="keyword varname">timeoutId</var>.

    function handler({api, helpers}) {
      api.setState('timeoutId', ({currentValue}) => {
        if (currentValue > -1) {
          helpers.timing.clearTimeout(currentValue);
        }
        return -1;
      });
    }

## helpers - helpers.timing.setInterval(Function fn, Number delay) {#ariaid-title10}

Repeatedly executes the specified function, using the specified delay value as the
interval between function calls.
Unlike the native JavaScript setInterval() method, this method does not
support passing a code string to evaluate as the first argument. Any additional arguments
are passed to the function itself.
{#helpers-timing-setInterval_F_N__table_t4h_sdy_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| fn | Function | Function to repeatedly execute. |
| delay | Number | Length of the time-interval between each function execution. Unit: Milliseconds |
[Table 17. Parameters]

{#helpers-timing-setInterval_F_N__table_t4h_sdy_n4b} {#helpers-timing-setInterval_F_N__table_u4h_sdy_n4b__entry__2}

| Type | Description |
|-|-|
| Number | Unique identifier of the function execution operation. Use this value in the [helpers - helpers.timing.clearInterval(Number timeoutId)](https://www.servicenow.com/docs/4upaDP3gwvXG_3M2n~_i1A#helpers-timing-clrInterval_N "Cancels the execution of the function that was scheduled through a prior setInterval() call.") method if you need to cancel this operation. |
[Table 18. Returns]

{#helpers-timing-setInterval_F_N__table_u4h_sdy_n4b}  
This code example shows how to refresh the timestamp on a page every second. This function
could be invoked by a user clicking an Enable Auto-refresh button on
a page.

    function handler({api, helpers}) {
      // Every one second, refresh the value of current timestamp client state parameter
      const intervalId = helpers.timing.setInterval(() => {
        api.setState('currentTimestamp', new Date().toString())
      }, 1000);

      // The interval ID is kept in state to use when calling the helpers.timing.clearInterval() method at a later point
      api.setState('intervalId', intervalId);
    }

## helpers - helpers.timing.setTimeout(Function fn, Number delay) {#ariaid-title11}

Executes the specified function, after the specified delay.
Unlike the native JavaScript setTimeout() method, this method does not
support passing a code string to evaluate as the first argument. Any additional arguments
are passed to the function itself.
{#helpers-timing-setTimeout_F_N__table_xrg_53y_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| fn | Function | Function to execute. |
| delay | Number | Length of the time to wait before calling the specified function. Unit: Milliseconds |
[Table 19. Parameters]

{#helpers-timing-setTimeout_F_N__table_xrg_53y_n4b} {#helpers-timing-setTimeout_F_N__table_yrg_53y_n4b__entry__2}

| Type | Description |
|-|-|
| Number | Unique identifier of the function execution operation. Use this value in the [helpers - helpers.timing.clearTimeout(Number timeoutId)](https://www.servicenow.com/docs/4upaDP3gwvXG_3M2n~_i1A#helpers-timing-clrTimeout_N "Cancels the execution of the function that was scheduled through a prior setTimeout() call.") method if you need to cancel this operation. |
[Table 20. Returns]

{#helpers-timing-setTimeout_F_N__table_yrg_53y_n4b}  
This code example shows how to set a 20 minute timer. You could associate this function
with a button Remind me in 20 minutes.

    function handler({api, helpers}) {
      const timeoutId = helpers.timing.setTimeout(() => {
        api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
          id: 'alert5',
          status: 'high',
          icon: 'info-circle-outline',
          content: 'Try to look away at something that is 20 feet away from you for a total of 20 minutes.',
          action: { type: 'dismiss' }
        });
      }, 20 * 60 * 1000);

      // The timeout ID is kept in state to use when calling the helpers.timing.clearTimeout() method at a later point
      api.setState('timeoutId', timeoutId);
    }

## helpers - helpers.translate(String message, String tokens) {#ariaid-title12}

Asynchronously retrieves and translates the specified message based on the current
user's session language.
You can use this method with the [api - setState(String stateParam, Any value)](https://www.servicenow.com/docs/3LzMQsN1EtXEkklhegMziQ#api-setState_S_A "Sets the value of the specified client state parameter.")
to bind the translated value to other fields on the page.  
Note:  
You can call this method using a promise or `async` and `await`. The code examples below show both implementations. {#helpers-translate_S_S__table_xjy_kxw_n4b__entry__3}

| Name | Type | Description |
|-|-|-|
| message | String | Message to translate. |
| tokens | String | Optional. Comma-separated list of parameters to use for replacing string variables. For example: helpers.translate('Text {0} {1}', 'to', 'translate'); |
[Table 21. Parameters]

{#helpers-translate_S_S__table_xjy_kxw_n4b} {#helpers-translate_S_S__table_yjy_kxw_n4b__entry__2}

| Type | Description |
|-|-|
| String | Translated text string. |
[Table 22. Returns]

{#helpers-translate_S_S__table_yjy_kxw_n4b}  
The following example shows how to pass in table field references to embed in the
corresponding variables in a string, using a promise.

    function handler ({api, helpers}) {
      helpers.translate('Welcome {0} {1}!', user.firstName, user.lastName)
        .then((translatedText) => {
          api.setState('greeting', translatedText);
        });
    }

The following example shows how to use `async` and `await` in
your function instead of a promise.

    async function handler ({api, helpers}) {
      const translatedText = await helpers.translate('Welcome to {0}', 'ServiceNow');
        api.setState('greeting', translatedText);
    }