api - UI Builder
-
- UpdatedJan 30, 2025
- 18 minutes to read
- Yokohama
- API reference
The api API provides methods that you can use when developing client scripts in the UI Builder.
- User interaction events/actions, such as a button click.
- Lifecycle events, such as a data broker execution started.
- Passing to a component property.
- Determining component visibility.
- Emitting an event with a payload.
The api object contains both configuration dependent and configuration independent properties that you can access within the context of the associated page or component. You cannot directly modify the properties within this object. Modification can only be made through the available methods.
api - api.context.props.<page_property_name>
Page properties can be configured within UI Builder. The configuration values depend on the context in which the page is used.
Name | Type | Description |
---|---|---|
<page_property_name> | Any | Available values are dependant on the client script implementation. To access
these properties, use the following:
For example:
Note: These
property values are read-only. Mutating nested object values from scripts is not
supported. |
api - api.context.session.<session_property>
Context session properties associated with the current user.
api - api.data.<data_resource_id>.lifecycle.lastFetchSucceeded
Boolean flag that indicates whether the last fetch attempt for the specified data resource instance finished successfully.
If the value is true, the last fetch attempt for the data resource instance finished successfully; otherwise, false.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
api - api.data.<data_resource_id>.addErrorMessage(Object payload)
Displays the specified error message at the top of the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the error message to display. |
payload.message | String | Error message to display. |
Type | Description |
---|---|
None |
Example
api -api.data.<data_resource_id>.addInfoMessage(Object payload)
Displays the specified informational message at the top of the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the informational message to display. |
payload.message | String | Informational message to display. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.addOption(Object payload)
Adds an option to the specified choice type field.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.addWarningMessage(Object payload)
Displays the specified warning message at the top of the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the warning message to display. |
payload.message | String | Warning message to display. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.clearMessage()
Removes all informational and error messages from the top of the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.clearOptions(Object payload)
Clears all options from the specified choice type field.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the choice type field whose options are to be cleared. |
payload.fieldName | String | Name of the choice type field whose options are to be cleared. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.executeUiAction(Object payload)
Executes the specified UI action.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Description of the UI action to execute. |
payload.actionSysId | String | Sys_id of the UI action to execute. Table: UI Action [sys_ui_action] |
Type | Description |
---|---|
None |
Example
The following code example shows how to call this method.
api - api.data.<data_resource_id>.execute(Object inputValues)
Triggers an execute operation on the specified data resource.
- Composite
- GraphQL
- REST
- Scriptlet
- Transform
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
inputValues | Object | Object to pass to the specified data resource. This object must conform to the data resource's input parameters. |
Type | Description |
---|---|
None |
Example
This code example shows a page script that is invoked when the Submit button on the page is clicked. The page is configured wit a Server Data Resource tat creates a new record.
api - api.data.<data_resource_id>.hideFieldMessage(Object payload)
Hides the oldest message next to the specified field or clears all messages associated with the field.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.hideRelatedList(Object payload)
Hides the specified related list on the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the related list to hide. |
payload.listTableName | String | Name of the related list to hide. If the list to hide is through a relationship, provide the sys_id of the list instead of the name. Table: Related List [sys_ui_related_list] |
Type | Description |
---|---|
None |
Example
The following code example shows how to call this method.
api - api.data.<data_resource_id>.hideRelatedLists()
Hides all related lists on the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.refresh()
Triggers a refresh operation for the specified non-mutating data resource instance.
Call this method if the underlying data being fetched by the data resource changes. A data resource is considered non-mutating if the mutates_server_data field on the record is set to false.
This method is asynchronous and emits an internal event to trigger the refresh of the specified data resource instance. The UI Builder allows you to trigger client scripts in response to data resource lifecycle events, such as DATA_FETCH_SUCCEEDED and DATA_FETCH_FAILED. For additional information on these events, see Event mapping.
- Composite
- GraphQL
- REST
- Scriptlet
- Transform
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
Type | Description |
---|---|
None |
Example
This code example shows a page script that is invoked when a dropdown item is selected in a page. The page is configured with two Server Data Resources that query problem and incident tables.
api - api.data.<data_resource_id>.reload()
Reloads the current form using the same table and sys_id.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.removeOption(Object payload)
Removes an option from the specified choice type field.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.save()
Triggers form submission using the Save UI action.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.setMandatory(Object payload)
Sets whether the specified form field is mandatory.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.setReadOnly(Object payload)
Sets the read/write capabilities of the specified form field.
Type | Description |
---|---|
None |
Example
api -api.data.<data_resource_id>.setValue(Object payload)
Updates a specified GlideForm field with the specified value. Optionally, you can also update the display value with the same specified value.
Only the value on the form is updated. The value is not saved in the database.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.setVisible(Object payload)
Sets the visibility of the specified form field.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.showFieldMessage(Object payload)
Displays the specified message next to the specified field.
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.showRelatedList(Object payload)
Displays the specified related list on the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the related list to display. |
payload.listTableName | String | Name of the related list to display. If the list to display is through a relationship, provide the sys_id of the list instead of the name. Table: Related List [sys_ui_related_list] |
Type | Description |
---|---|
None |
Example
The following code example shows how to call this method.
api - api.data.<data_resource_id>.showRelatedLists()
Displays all related lists associated with the current form.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
Type | Description |
---|---|
None |
Example
api - api.data.<data_resource_id>.submit()
Triggers form submission using the specified UI action.
Name | Type | Description |
---|---|---|
data_resource_id | String | Unique identifier of the associated data resource. In most cases, you can use the Form Controller CTRL_RECORD#SAVE_FORM action. If the record page has the Record Page Tabs component, the data resource for this method must be based off of GlideForm (g_form). The available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder. |
payload | Object | Object that describes the UI action to use to submit the current form. |
payload.submitActionName | String | Name of the UI action to execute to submit the current form. |
Type | Description |
---|---|
None |
Example
api - api.emit(String eventName, Object payload)
Emits an event with the specified name and payload.
The event name being emitted must be part of the associated page definition's dispatched events list, which is stored in the UX Macroponent Definition [sys_ux_macroponent] table. Any api.emit call that dispatches events not declared in this table are ignored.
For additional information on events, see Work with events.
Name | Type | Description |
---|---|---|
eventName | String | Name of the event to emit. This name should follow the UI Framework action
naming guidelines:
For additional information on these action naming guidelines, see https://developer.servicenow.com/dev.do#!/reference/now-experience/sandiego/ui-framework/main-concepts/dispatching-actions. |
payload | Object | Optional. Object that contains the data to send with the emitted event. This
object is free-form and can contain whatever data is necessary by the entity
receiving the data. Note: Payloads of primitive type work, but could result in
inconsistent behavior. |
Type | Description |
---|---|
None |
Example
The following code example shows emitting an event called NOW_UXF_PAGE#ADD_NOTIFICATIONS with an associated items payload.
api - setState(String stateParam, Any value)
Sets the value of the specified client state parameter.
Use client state parameters to maintain a shared state on a page. The shared state can then be passed as values to properties of components used on the page. You can also access and update client states in multiple page scripts. A common use case is to keep track of values input by users in multiple form controls on a page. When the form is submitted, a client script could then use all of the values stored in client state parameters to create a new record with a data broker. A page can have one or more client state parameters, which you can declare for a page through the UI Builder. You can then bind a client state parameter to one or more components to share or act on the client state parameter.
api.setState() calls are executed asynchronously and do not necessarily update the UI immediately. If the value to set depends on the currentValue of the client state parameter, or any of the properties provided in the api object, you should use this variant of the api.setState() method to avoid using outdated values.
Name | Type | Description |
---|---|---|
stateParm | String | Name of the client state parameter to update. This
name must be declared in the client state parameters of the associated page. For additional information on declaring client state parameters, see Work with client state parameters. |
value | Any - Must be the same as the client state parameter declaration. | Value to set the specified client state parameter to. |
Type | Description |
---|---|
None |
Example
This example shows a script that could be executed to update the email client state parameter when an input value is set on a now-input component.
api - setState(String stateParam, Function callbackFn)
Sets the value of the specified client state parameter to the value returned by the specified callback function.
The callback function is invoked with an object that has two properties: currentValue and api. The function should never mutate the currentValue property or the api object directly.
Use client state parameters to maintain a shared state on a page. The shared state can then be passed as values to properties of components used on the page. You can also access and update client states in multiple page scripts. A common use case is to keep track of values input by users in multiple form controls on a page. When the form is submitted, a client script could then use all of the values stored in client state parameters to create a new record with a data broker. A page can have one or more client state parameters, which you can declare for a page through the UI Builder. You can then bind a client state parameter to one or more components to share or act on the client state parameter.
api.setState() calls are executed asynchronously and do not necessarily update the UI immediately. If the value to set depends on the currentValue of the client state parameter, or any of the properties provided in the api object, you should use this variant of the api.setState() method to avoid using outdated values.
Name | Type | Description |
---|---|---|
stateParm | String | Name of the client state parameter to update. This
name must be declared in the client state parameters of the associated page. For additional information on declaring client state parameters, see Work with client state parameters. |
callbackFn | Function | Callback function to execute to obtain the value. |
Type | Description |
---|---|
None |
Example
This example shows how to use api.setState to log users into a page.
api - api.state.<client_state_parameter_name>
Current value of the specified client state parameter.
Name | Type | Description |
---|---|---|
<client_state_parameter_name> | Any. The available client state parameters are dependent on the page configuration. | Name of the client state parameter. Available client states are dependant on
the client script implementation. To access the available client states, use the
following: For example:
Note: These
property values are read-only. To update a client state parameter, use api.setState(). Mutating nested object
values from scripts is not supported. |
On this page
- api - api.context.props.<page_property_name>
- api - api.context.session.<session_property>
- api - api.data.<data_resource_id>.lifecycle.lastFetchSucceeded
- api - api.data.<data_resource_id>.addErrorMessage(Object payload)
- api -api.data.<data_resource_id>.addInfoMessage(Object payload)
- api - api.data.<data_resource_id>.addOption(Object payload)
- api - api.data.<data_resource_id>.addWarningMessage(Object payload)
- api - api.data.<data_resource_id>.clearMessage()
- api - api.data.<data_resource_id>.clearOptions(Object payload)
- api - api.data.<data_resource_id>.executeUiAction(Object payload)
- api - api.data.<data_resource_id>.execute(Object inputValues)
- api - api.data.<data_resource_id>.hideFieldMessage(Object payload)
- api - api.data.<data_resource_id>.hideRelatedList(Object payload)
- api - api.data.<data_resource_id>.hideRelatedLists()
- api - api.data.<data_resource_id>.refresh()
- api - api.data.<data_resource_id>.reload()
- api - api.data.<data_resource_id>.removeOption(Object payload)
- api - api.data.<data_resource_id>.save()
- api - api.data.<data_resource_id>.setMandatory(Object payload)
- api - api.data.<data_resource_id>.setReadOnly(Object payload)
- api -api.data.<data_resource_id>.setValue(Object payload)
- api - api.data.<data_resource_id>.setVisible(Object payload)
- api - api.data.<data_resource_id>.showFieldMessage(Object payload)
- api - api.data.<data_resource_id>.showRelatedList(Object payload)
- api - api.data.<data_resource_id>.showRelatedLists()
- api - api.data.<data_resource_id>.submit()
- api - api.emit(String eventName, Object payload)
- api - setState(String stateParam, Any value)
- api - setState(String stateParam, Function callbackFn)
- api - api.state.<client_state_parameter_name>