{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1157,"path":"api-reference/ui-builder-api-reference/apiAPI.md","title":"api - UI Builder","bundle":null,"doc_type":null,"release":"australia","body":"\n# api - UI Builder\n\nThe api API provides methods that you can use when developing client scripts in the UI Builder.\n\nThis API is exposed to client scripts, also known as page scripts. Client scripts are executed in response to something happening on a page, such as:\n\n-   User interaction events/actions, such as a button click.\n-   Lifecycle events, such as a data broker execution started.\n\nThese scripts do not have to return anything to the framework and can be written as an asynchronous function.\n\nThis API is also exposed to scripted property values. These scripts are executed whenever the framework-runtime needs to calculate a value, such as:\n\n-   Passing to a component property.\n-   Determining component visibility.\n-   Emitting an event with a payload.\n\nThese scripts cannot be written as an asynchronous function. They also cannot invoke side-effect methods on the api object, such as, api.emit\\(\\), api.setState\\(\\), and api.data.&lt;data\\_resource\\_id&gt;.\\*\\(\\).\n\nThe 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.\n\n**Parent Topic:**[UIB API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/ui-builder-api-reference/api-uib.md)\n\n## api - api.context.props.&lt;page\\_property\\_name&gt;\n\nPage properties can be configured within UI Builder. The configuration values depend on the context in which the page is used.\n\n<table id=\"table_pnc_bkb_n4b\"><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\n&lt;page\\_property\\_name&gt;\n\n</td><td>\n\nAny\n\n</td><td>\n\nAvailable values are dependant on the client script implementation.To access these properties, use the following: `api.context.props.<page_property_name>`.\n\n For example:\n\n```\n`// A record page with property table could be accessed with\nfunction isActivityStreamVisible({api}) {\n  return api.context.props.table === 'incident';\n} `\n```\n\n **Note:** These property values are read-only. Mutating nested object values from scripts is not supported.\n\n</td></tr></tbody>\n</table>## api - api.context.session.&lt;session\\_property&gt;\n\nContext session properties associated with the current user.\n\n<table id=\"table_e24_hkc_n4b\"><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\nisLoggedIn\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the current user is logged in to the system.Possible values:\n\n-   true: Current user is logged in to\n-   false: Current user is not logged in.\n\n</td></tr><tr><td>\n\nproperties.awaEnabled\n\n</td><td>\n\nString\n\n</td><td>\n\nThe system property glide.awa.enabled that indicates whether the auto assignment for work items for Advanced Work Assignment \\(AWA\\) is enabled for the current user.Possible values:\n\n-   true: AWA is enabled for the user.\n-   false: AWA is not enabled for the user.\n\n For additional information, see [Components installed with Advanced Work Assignment](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/installed-with-awa.md).\n\n</td></tr><tr><td>\n\nproperties.forgetMe.value\n\n</td><td>\n\nString\n\n</td><td>\n\nThe property glide.ui.forgetme that indicates whether to remove the **Remember Me** check box from the login page to prevent login information from being cached.Possible values:\n\n-   true: Remove the **Remember Me** check box.\n-   false: Display the **Remember Me** check box.\n\n For additional information, see [Remove remember me](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/sc-remove-remember-me.md).\n\n</td></tr><tr><td>\n\nproperties.sessionTimeLeft.value\n\n</td><td>\n\nStringNumber coerced to string\n\n</td><td>\n\nThe system property glide.ui.session\\_timeleft that determines the mount of time left before the current session times out. Use this property to prompt the user to extent the current session before it times out.Unit: Minutes\n\n</td></tr><tr><td>\n\nproperties.sessionTimeout.value\n\n</td><td>\n\nStringNumber coerced to string\n\n</td><td>\n\nThe system property glide.ui.session\\_timeout that determines the initial session time out value.Unit: Minutes - Values greater than 1440 minutes are treated as one day.\n\n For additional information, see [Session activity timeout](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/sc-session-activity-timeout.md)\n\n</td></tr><tr><td>\n\nproperties.trackingEnabled.value\n\n</td><td>\n\nString\n\n</td><td>\n\nThe system property glide.uxbuilder.tracking.enabled that indicates whether to enable/disable web analytics library loading and instantiation for UI Builder based applications.Possible values:\n\n-   true: Enabled for the user.\n-   false: Disabled for the user.\n\n</td></tr><tr><td>\n\nuser.avatar\n\n</td><td>\n\nString\n\n</td><td>\n\nURL of the current user's avatar.\n\n</td></tr><tr><td>\n\nuser.dateFormat\n\n</td><td>\n\nString\n\n</td><td>\n\nDefault date format.\n\n</td></tr><tr><td>\n\nuser.domain\n\n</td><td>\n\nString\n\n</td><td>\n\nDomain path for the current user.\n\n</td></tr><tr><td>\n\nuser.firstName\n\n</td><td>\n\nString\n\n</td><td>\n\nFirst name of the current user.\n\n</td></tr><tr><td>\n\nuser.fullName\n\n</td><td>\n\nString\n\n</td><td>\n\nFirst and last name of the current user.\n\n</td></tr><tr><td>\n\nuser.initials\n\n</td><td>\n\nString\n\n</td><td>\n\nInitials of the current user.\n\n</td></tr><tr><td>\n\nuser.language\n\n</td><td>\n\nString\n\n</td><td>\n\nPrimary language spoken by the current user.\n\n</td></tr><tr><td>\n\nuser.preferences\n\n</td><td>\n\nArray of objects\n\n</td><td>\n\nName-value pairs that describe the user preferences. These user preferences are stored as records in the User Preference \\[sys\\_user\\_preference\\] table, and are updated each time the user changes their settings.For additional information, see [Exploring user administration](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/exploring-user-administration.md).\n\n</td></tr><tr><td>\n\nuser.roles\n\n</td><td>\n\nArray\n\n</td><td>\n\nComma-separated list of roles assigned to the current user.**Note:** If the user has no roles assigned, this context session property returns null rather than an empty array.\n\n</td></tr><tr><td>\n\nuser.sys\\_id\n\n</td><td>\n\nString\n\n</td><td>\n\nSys\\_id of the user in the User \\[sys\\_user\\] table.\n\n</td></tr><tr><td>\n\nuser.timeFormat\n\n</td><td>\n\nString\n\n</td><td>\n\nDefault time format to use for the user.\n\n</td></tr><tr><td>\n\nuser.timeZone\n\n</td><td>\n\nString\n\n</td><td>\n\nTime zone of the current user.\n\n</td></tr><tr><td>\n\nuser.timeZoneOffset\n\n</td><td>\n\nString\n\n</td><td>\n\nTime zone offset of the current user.\n\n</td></tr></tbody>\n</table>## api - api.data.&lt;data\\_resource\\_id&gt;.lifecycle.lastFetchSucceeded\n\nBoolean flag that indicates whether the last fetch attempt for the specified data resource instance finished successfully.\n\nIf the value is true, the last fetch attempt for the data resource instance finished successfully; otherwise, false.\n\n<table id=\"table_svj_czb_n4b\"><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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr></tbody>\n</table>## api - api.data.&lt;data\\_resource\\_id&gt;.addErrorMessage\\(Object payload\\)\n\nDisplays the specified error message at the top of the current form.\n\n<table id=\"table_pct_ffd_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the error message to display.```\n\"payload\": {\n  \"message\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.message\n\n</td><td>\n\nString\n\n</td><td>\n\nError message to display.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.addErrorMessage({message: 'Error message'});\n```\n\n## api -api.data.&lt;data\\_resource\\_id&gt;.addInfoMessage\\(Object payload\\)\n\nDisplays the specified informational message at the top of the current form.\n\n<table id=\"table_pqr_wdd_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the informational message to display.```\n\"payload\": {\n  \"message\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.message\n\n</td><td>\n\nString\n\n</td><td>\n\nInformational message to display.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.addInfoMessage({message: 'Test message'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.addOption\\(Object payload\\)\n\nAdds an option to the specified choice type field.\n\n<table id=\"table_okr_21j_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field value to update.```\n\"payload\": {\n  \"choiceIndex\": \"String\",\n  \"choiceLabel\": \"String\",\n  \"choiceValue\": \"String\",\n  \"fieldName\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.choiceIndex\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Index into the choice list at which to insert the option.Default: End of the choice list.\n\n</td></tr><tr><td>\n\npayload.choiceLabel\n\n</td><td>\n\nString\n\n</td><td>\n\nLabel of the option to add to the specified field.\n\n</td></tr><tr><td>\n\npayload.choiceValue\n\n</td><td>\n\nString\n\n</td><td>\n\nValue of the option to add to the specified field.\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the choice type form field to add the specified option to.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.addOption({fieldName: 'priority', choiceLabel: 'Extremely High', choiceValue: '10'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.addWarningMessage\\(Object payload\\)\n\nDisplays the specified warning message at the top of the current form.\n\n<table id=\"table_mgf_v2d_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the warning message to display.```\n\"payload\": {\n  \"message\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.message\n\n</td><td>\n\nString\n\n</td><td>\n\nWarning message to display.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.addWarningMessage({message: 'Test message'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.clearMessage\\(\\)\n\nRemoves all informational and error messages from the top of the current form.\n\n<table id=\"table_g4t_qfd_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.clearMessage();\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.clearOptions\\(Object payload\\)\n\nClears all options from the specified choice type field.\n\n<table id=\"table_c3x_4dj_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the choice type field whose options are to be cleared.```\n\"payload\": {\n  \"fieldName\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the choice type field whose options are to be cleared.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.clearOptions({fieldName: 'priority'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.executeUiAction\\(Object payload\\)\n\nExecutes the specified UI action.\n\n<table id=\"table_l41_s2j_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nDescription of the UI action to execute.```\n\"payload\": {\n  \"actionSysId\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.actionSysId\n\n</td><td>\n\nString\n\n</td><td>\n\nSys\\_id of the UI action to execute. Table: UI Action \\[sys\\_ui\\_action\\]\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows how to call this method.\n\n```\napi.data.gform.executeUiAction({actionSysId: '60615ff90f730010ac7de6f8c4767e9a'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.execute\\(Object inputValues\\)\n\nTriggers an execute operation on the specified data resource.\n\nThis method is only available if the data resource is one of the following types:\n\n-   Composite\n-   GraphQL\n-   REST\n-   Scriptlet\n-   Transform\n\n**Note:** This method is only exposed if the **mutates\\_server\\_data** field is set to `true` on the corresponding data resource \\(sys\\_ux\\_data\\_broker\\_\\* table\\) record. It is accessible under api.data.&lt;data\\_resource\\_Id&gt;.refresh\\(\\).\n\n|Name|Type|Description|\n|----|----|-----------|\n|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.|\n|inputValues|Object|Object to pass to the specified data resource. This object must conform to the data resource's input parameters.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThis 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.\n\n```\nfunction handler({api}) {\n  if (api.state.movieYear === 2020) {\n    // The data resource used in this case specifies two input parameters: name and year\n    api.data.create_movie_record.execute({\n      name: api.state.movieName,\n      year: api.state.movieYear\n    });\n  }\n}\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.hideFieldMessage\\(Object payload\\)\n\nHides the oldest message next to the specified field or clears all messages associated with the field.\n\n<table id=\"table_jl3_b33_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field message to hide.```\n\"payload\": {\n  \"clearAll\": Boolean,\n  \"fieldName\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.clearAll\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nOptional. Flag that indicates whether to clear all messages associated with the specified form field.Valid values:\n\n-   true: Clear all messages associated with the specified field.\n-   false: Do not clear all messages associated with the specified field.\n\n Default: false\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the form field for which to hide the oldest message or clear all associated messages.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.hideFieldMessage({fieldName: 'short_description'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.hideRelatedList\\(Object payload\\)\n\nHides the specified related list on the current form.\n\n<table id=\"table_yxg_jq3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the related list to hide.```\n\"payload\": {\n  \"listTableName \": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.listTableName\n\n</td><td>\n\nString\n\n</td><td>\n\nName 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\\]\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows how to call this method.\n\n```\napi.data.gform.hideRelatedList({listTableName:'incident.parent_incident'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.hideRelatedLists\\(\\)\n\nHides all related lists on the current form.\n\n<table id=\"table_cy4_cm3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.hideRelatedLists();\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.refresh\\(\\)\n\nTriggers a refresh operation for the specified non-mutating data resource instance.\n\nCall 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.\n\nThis 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/event-mapping.md).\n\nThis method is only available if the data resource is one of the following types:\n\n-   Composite\n-   GraphQL\n-   REST\n-   Scriptlet\n-   Transform\n\n**Note:** This method is only exposed if the **mutates\\_server\\_data** field is set to `false` on the corresponding data resource \\(sys\\_ux\\_data\\_broker\\_\\* table\\) record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|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.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThis 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.\n\n```\nfunction handler({api, event}) {\n  const value = event.payload.value[0];\n  if (value === 'problem')\n    api.data.problem_list_1.refresh();\n  else if(value === 'incident')\n    api.data.incident_list_1.refresh();\n}\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.reload\\(\\)\n\nReloads the current form using the same table and sys\\_id.\n\n<table id=\"table_cwc_kw3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.reload();\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.removeOption\\(Object payload\\)\n\nRemoves an option from the specified choice type field.\n\n<table id=\"table_gky_wcj_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the choice type field to update.```\n\"payload\": {\n  \"choiceValue\": \"String\",\n  \"fieldName\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.choiceValue\n\n</td><td>\n\nString\n\n</td><td>\n\nValue of the option to remove from the specified choice type field.\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the choice type form field from which to remove the specified value.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.removeOption({fieldName: 'priority', choiceValue: '1'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.save\\(\\)\n\nTriggers form submission using the Save UI action.\n\n<table id=\"table_fn1_vw3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.save();\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.setMandatory\\(Object payload\\)\n\nSets whether the specified form field is mandatory.\n\n<table id=\"table_yws_2v3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field whose mandatory information to update.```\n\"payload\": {\n  \"fieldName\": \"String\",\n  \"mandatory\": Boolean\n}\n```\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the form field whose mandatory value is to be set.\n\n</td></tr><tr><td>\n\npayload.mandatory\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates the specified form field is mandatory, meaning the form cannot be saved without this field containing a valid value.Valid values:\n\n-   true: Field is mandatory.\n-   false: Field is optional.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.setMandatory({fieldName: 'short_description', mandatory: false});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.setReadOnly\\(Object payload\\)\n\nSets the read/write capabilities of the specified form field.\n\n<table id=\"table_d13_ps3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field whose readability information to update.```\n\"payload\": {\n  \"fieldName\": \"String\",\n  \"readonly\": Boolean\n}\n```\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the form field whose readability is to be set.\n\n</td></tr><tr><td>\n\npayload.readonly\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates the read/write capabilities of the specified form field.Valid values:\n\n-   true: Field is read only.\n-   false: Field is read/write.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.setReadOnly({fieldName: 'short_description', readonly: false});\n```\n\n## api -api.data.&lt;data\\_resource\\_id&gt;.setValue\\(Object payload\\)\n\nUpdates a specified GlideForm field with the specified value. Optionally, you can also update the display value with the same specified value.\n\nOnly the value on the form is updated. The value is not saved in the database.\n\n<table id=\"table_tyh_31d_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field whose value to update.```\n\"payload\": {\n  \"displayValue\": \"String\",\n  \"fieldName\": \"String\",\n  \"value\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.displayValue\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Name of the display value to update. If left blank, the display value is not modified.\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the form field to update.\n\n</td></tr><tr><td>\n\npayload.value\n\n</td><td>\n\nString\n\n</td><td>\n\nValue to update the field with.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.setValue({fieldName: 'short_description', value: 'short description'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.setVisible\\(Object payload\\)\n\nSets the visibility of the specified form field.\n\n<table id=\"table_j5k_gr3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field on which to set visibility.```\n\"payload\": {\n  \"fieldName\": \"String\",\n  \"visibility\": Boolean\n}\n```\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the form field whose visibility is to be set.\n\n</td></tr><tr><td>\n\npayload.visibility\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the associated field is visible on the current form.Valid values:\n\n-   true: Field will display on the form.\n-   false: Field will not display on the form.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.setVisible({fieldName: 'short_description', visibility: false});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.showFieldMessage\\(Object payload\\)\n\nDisplays the specified message next to the specified field.\n\n<table id=\"table_o35_xgd_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the field message to display.```\n\"payload\": {\n  \"fieldName\": \"String\",\n  \"message\": \"String\",\n  \"type\": \"String\"\n```\n\n</td></tr><tr><td>\n\npayload.fieldName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the field next to which the message should appear.\n\n</td></tr><tr><td>\n\npayload.message\n\n</td><td>\n\nString\n\n</td><td>\n\nMessage to display.\n\n</td></tr><tr><td>\n\npayload.type\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Type of message to display.Valid values:\n\n-   error\n-   info\n-   warning\n\n Default: info\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.showFieldMessage({fieldName: 'short_description', message: 'Error message', type: 'error'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.showRelatedList\\(Object payload\\)\n\nDisplays the specified related list on the current form.\n\n<table id=\"table_xc2_tn3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the related list to display.```\n\"payload\": {\n  \"listTableName \": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.listTableName\n\n</td><td>\n\nString\n\n</td><td>\n\nName 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\\]\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows how to call this method.\n\n```\napi.data.gform.showRelatedList({listTableName:'incident.parent_incident'});\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.showRelatedLists\\(\\)\n\nDisplays all related lists associated with the current form.\n\n<table id=\"table_wzd_sl3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.showRelatedLists();\n```\n\n## api - api.data.&lt;data\\_resource\\_id&gt;.submit\\(\\)\n\nTriggers form submission using the specified UI action.\n\n<table id=\"table_zc1_hx3_n4b\" 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\ndata\\_resource\\_id\n\n</td><td>\n\nString\n\n</td><td id=\"data_resource_id-entry-api\">\n\nUnique 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\\).\n\nThe available data resource instances are configuration-dependent and defined when you add the data resource to your page in UI Builder.\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nObject that describes the UI action to use to submit the current form.```\n\"payload\": {\n  \"submitActionName\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\npayload.submitActionName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the UI action to execute to submit the current form.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\napi.data.gform.submit({submitActionName:'sysverb_ws_save'});\n```\n\n## api - api.emit\\(String eventName, Object payload\\)\n\nEmits an event with the specified name and payload.\n\nThe 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.\n\nFor additional information on events, see [Work with events](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/work-events.md).\n\n<table id=\"table_yyz_njj_n4b\" 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\neventName\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the event to emit. This name should follow the UI Framework action naming guidelines:-   Should be upper snake case, such as ITEM\\_CHANGED. All letters in upper case and all spaces replaced with underscores.\n-   Should be past tense, such as BUTTON\\_CLICKED or USER\\_SELECTED.\n\n 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](https://developer.servicenow.com/dev.do#!/reference/now-experience/sandiego/ui-framework/main-concepts/dispatching-actions).\n\n</td></tr><tr><td>\n\npayload\n\n</td><td>\n\nObject\n\n</td><td>\n\nOptional. 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.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThe following code example shows emitting an event called **NOW\\_UXF\\_PAGE\\#ADD\\_NOTIFICATIONS** with an associated **items** payload.\n\n```\nfunction handler({api}) { \n  api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', { \n    items: [\n      { \n        id: 'alert1', \n        status: 'positive', \n        icon: 'check-circle-outline', \n        content: 'Here is some information!', \n        textLinkProps: { \n          label: 'More info',\n          href: 'https://www.servicenow.com' \n        }, \n      action: {type: 'acknowledge'} \n      } \n    ] \n  }); \n} \n```\n\n## api - setState\\(String stateParam, Any value\\)\n\nSets the value of the specified client state parameter.\n\nUse 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.\n\napi.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.\n\n<table id=\"table_lgw_35q_n4b\" 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\nstateParm\n\n</td><td>\n\nString\n\n</td><td id=\"stateParm-entry-api\">\n\nName 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/state-parameters.md).\n\n</td></tr><tr><td>\n\nvalue\n\n</td><td>\n\nAny - Must be the same as the client state parameter declaration.\n\n</td><td>\n\nValue to set the specified client state parameter to.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThis 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.\n\n```\nfunction handler({api, event}) {\n    api.setState('email', event.payload.value);\n}\n```\n\n## api - setState\\(String stateParam, Function callbackFn\\)\n\nSets the value of the specified client state parameter to the value returned by the specified callback function.\n\nThe 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.\n\nUse 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.\n\napi.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.\n\n<table id=\"table_vlt_gyq_n4b\" 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\nstateParm\n\n</td><td>\n\nString\n\n</td><td id=\"stateParm-entry-api\">\n\nName 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/state-parameters.md).\n\n</td></tr><tr><td>\n\ncallbackFn\n\n</td><td>\n\nFunction\n\n</td><td>\n\nCallback function to execute to obtain the value.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\nThis example shows how to use api.setState to log users into a page.\n\n```\nfunction handler({api, event}) {\n  const {name, value} = event.payload;\n  if (name === 'username' || name === 'password') {\n    // Update the loginParameters state object with the username/password value\n    api.setState('loginParameters', ({currentValue}) => {\n      return {\n        ...currentValue,\n        [name]: value\n      };\n    });\n  }\n}\n```\n\n## api - api.state.&lt;client\\_state\\_parameter\\_name&gt;\n\nCurrent value of the specified client state parameter.\n\n<table id=\"table_yk3_rmb_n4b\"><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\n&lt;client\\_state\\_parameter\\_name&gt;\n\n</td><td>\n\nAny. The available client state parameters are dependent on the page configuration.\n\n</td><td>\n\nName of the client state parameter. Available client states are dependant on the client script implementation.To access the available client states, use the following: `api.state.<client_state_name>`.\n\n For example:\n\n```\nfunction showRelatedLists({api}) { \n  return !api.state.isCustomListSelected; \n} \n```\n\n **Note:** These property values are read-only. To update a client state parameter, use [api.setState\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/ui-builder-api-reference/apiAPI.md). Mutating nested object values from scripts is not supported.\n\n</td></tr></tbody>\n</table>"}}