{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":674,"path":"api-reference/scripts/r_UIPages.md","title":"UI pages","bundle":null,"doc_type":null,"release":"australia","body":"\n# UI pages\n\nUI pages can be used to create and display forms, dialogs, lists, and other UI components.\n\nUse UI pages as widgets on dashboards. To find the UI pages, navigate to **System UI** &gt; **UI Pages**.\n\nThis functionality requires a knowledge of HTML or Jelly. You can also create simple AngularJS applications using UI pages.\n\nThe UI page form contains the following fields:\n\n<table id=\"table_lxj_31h_y4\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nName used to invoke the page via a URL \\(must not contain spaces\\).\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nDisplays the current application scope.\n\n</td></tr><tr><td>\n\nDescription\n\n</td><td>\n\nThe description of the UI page and what it’s used for.\n\n</td></tr><tr><td>\n\nDirect\n\n</td><td>\n\nSelect this check box for a direct UI page \\[sys\\_ui\\_page\\]. A direct UI page doesn't include the common HTML, CSS, and scripts. This setting requires adding custom CSS and JavaScript to use in the page.\n\n</td></tr><tr><td>\n\nHTML\n\n</td><td>\n\nMain component of the page where you define what is rendered when the page is shown. It can contain either static XHTML, dynamically generated content defined as Jelly, or call script includes and UI Macros.**Note:** If GlideRecord/GlideDBQuery is used instead of GlideRecordSecure, a security recommendation message displays.\n\n</td></tr><tr><td>\n\nClient Script\n\n</td><td>\n\nInclude client-side JavaScript that runs in the browser, such as functions called by buttons. It’s intended to handle any client-side processing needed, like setting focus to a field or other interactive DHTML features after a page is loaded. Client scripts for the UI page are deployed to the browser within a `<script/>` tag, so the content can similarly be defined within the HTML field. The Client Script field can be used instead to define these scripts concisely to maintain the Jelly and HTML manageability.\n\n</td></tr><tr><td>\n\nProcessing Script\n\n</td><td>\n\nScript that runs on the server when the page is submitted. This is useful if your page has a form defined with the &lt;`g:ui_form/`&gt; or &lt;`g:form/`&gt; tags.**Note:** If GlideRecord/GlideDBQuery is used instead of GlideRecordSecure, a security recommendation message displays.\n\n</td></tr><tr><td>\n\nobsolete-custom-processors\n\n</td><td>\n\n**Note:** This feature is deprecated. While legacy, existing custom processors continue to be supported, creating new custom processors has been deprecated. Instead, use the [Scripted REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n</td></tr><tr><td colspan=\"2\">\n\nRelated lists on the form view:\n\n</td></tr><tr><td>\n\nAccess Controls\n\n</td><td>\n\nView and configure access controls for the UI page. See [Use access controls on UI pages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/r_UIPages.md) for more information.\n\n</td></tr><tr><td>\n\nVersions\n\n</td><td>\n\nShows all versions of the UI page. Use this list to compare versions or to revert to a previous version.\n\n</td></tr></tbody>\n</table>## Access control\n\nYou can secure a UI page by creating an ACL with the following parameters:\n\n-   **Type**: `ui_page`\n-   **Operation**: `read`\n-   **Name**: Name of the UI page to protect\n-   **Role**: User role that is allowed to access the record\n\nWhen saving a new UI page, you are prompted to assign a role for access control.\n\n**Note:** An entry with the same name as the UI page is created in the Access Control table.\n\nFor details on creating an ACL rule, see [Create an ACL rule](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/t_CreateAnACLRule.md).\n\n## High risk UI pages\n\nUI pages are considered high risk with any of the following attributes:\n\n-   Uses GlideRecord or GlideDBQuery instead of GlideRecordSecure.\n\n    **Note:** This is applicable for HTML and Processing script fields and not Client scripts.\n\n-   Doesn't have a corresponding ACL configured.\n-   Indicates to be a public UI page and is entered in the sys\\_public record.\n-   Shows a message to indicate high risk UI page.\n-   For instances with glide.installation.developer is set to **true**.\n-   If resource is customized content for a customer instance.\n\n**Parent Topic:**[Creating custom UI Pages and UI macros](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/create-custom-ui-pages.md)\n\n## UI page access\n\nEach UI page has a URL computed from the application scope, page name, and the `.do` file extension.\n\nFor example, to display the page called glidewindow\\_example on the demo system, you would navigate to `https://<instance name>.service-now.com/glidewindow_example.do`. If the page was part of a custom application called example\\_app, you would instead navigate to `https://<instance name>.service-now.com/x_example_app_glidewindow_example.do`.\n\nYou can also add additional parameters to a URL that can be accessed within a page's HTML section as jelly variables. That is, appending arguments to the URL as follows: `/my_test_page.do?sysparm_verbose=true` creates jelly variables called **verbose** that can be accessed as follows:\n\n```\n<j2:if test=\"$[!empty(sysparm_verbose)]\"> <span>show extra stuff </span> </j2:if >\n```\n\nA common practical example of this might be retrieving a database record for display. To build a list of a user's roles, pass in a parameter with the user's sys\\_id. Invoke the following UI page to display a list of roles for that user with Jelly code:\n\n`role_select.do?sysparm_user=5137153cc611227c000bbd1bd8cd2007`\n\n```\n<j:set var = \"jvar_user_id\" value = \"${sysparm_user}\" />\n \n  <g:evaluate> var userRoles = new GlideRecord('sys_user_has_role');\n    userRoles.addQuery('user','${jvar_user_id}');\n    userRoles.query(); \n  </g:evaluate>\n \n  <select id='select_role'> \n      <j:while test = \"${userRoles.next()}\"> \n          <option value = \"${userRoles.sys_id}\"> ${userRoles.role.name} </option> \n      </j:while> \n  </select>\n```\n\nAn exception to be careful of, though, is the reserved variable name sys\\_id. This variable always contains the ID of the UI page itself, regardless of what is specified in the URL. A common substitute variable name is sysparm\\_id.\n\nDo not use URL parameters to load client scripts in UI pages. The system no longer evaluates scripts that are passed by URL parameter. If your implementation depends on this behavior, you can [add the system property](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/t_AddAPropertyUsingSysPropsList.md) \\[glide.security.disable\\_ui\\_pages\\_sysparm\\_client\\_script\\] and set it to **false** to temporarily allow the evaluation of URL parameters passing scripts in UI pages.\n\n## Use access controls on UI pages\n\nSee access controls directly from the UI Page form and add role-based access control when creating or editing a UI Page record.\n\n### Before you begin\n\nAccess controls that have been added to an existing UI page can be accessed and edited by opening the UI page record under related links.\n\nRole required: security\\_admin and admin\n\n### Procedure\n\n1.  Elevate to the **security\\_admin** role.\n\n    For details on role elevation, see [Elevate to a privileged role](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/t_ElevateToAPrivilegedRole.md).\n\n2.  Navigate to **All** &gt; **System UI** &gt; **UI Pages**.\n\n3.  Select **New**.\n\n4.  Complete the form.\n\n    See [UI pages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/r_UIPages.md) for additional information for UI field descriptions.\n\n5.  Select **Submit** or **Save**.\n\n    A modal displays prompting you to create a role-based access control for the UI page.\n\n6.  Select a role.\n\n7.  Select **OK** to assign the role.\n\n    You are returned to the UI pages list.\n\n8.  Add, edit, or view access controls for an existing UI page:\n9.  Open a UI page from the UI pages table.\n\n10. View the **Access Controls** under the related lists.\n\n11. Select **New** to create a new access control or select an existing entry for editing.\n\n    The Access Control form loads. UI Page details are displayed.\n\n12. Complete the form and assign a role to the UI page.\n\n    For additional information on access control, see [Create an ACL rule](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/t_CreateAnACLRule.md).\n\n13. Select **Submit** for a new access control or **Update** for edits.\n\n    **Note:** There can be multiple access controls per UI page.\n\n\n### Secure UI pages\n\nAccess controls and related security messages are integrated on high risk UI Pages for increased security.\n\nAn informational message displays on high risk UI pages to inform the customer to add a role-based Access Control to the UI page.\n\n\\[Omitted image \"new-ui-html-processing-errors.png\"\\] Alt text: UI page security recommendation messages.\n\nThe message displays under the following conditions:\n\n-   If an ACL \\(access control list\\) is missing\n-   If GlideRecord/GlideDBQuery is used instead of GlideRecordSecure in either the **HTML** or **Processing script** fields.\n-   If the UI page is configured as public in sys\\_public\n\n    **Note:** Public UI Pages that are public or that use GlideRecord don’t show a missing ACL warning.\n\n\nSee [UI pages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/r_UIPages.md) for details on high risk UI pages.\n\n#### Conditions that display the security recommendations message\n\nThe message displays under the following conditions:\n\n-   All internal instances eclipse/IJ where glide.installation.developer=true.\n-   All customer scoped UI Page resources.\n-   Any customized UI Page when the **glide.script.ui\\_page.customer\\_scoped.security\\_msgs\\_enabled** property is set to true. \\(The default value is true\\).\n\n#### Conditions that don’t display the security recommendations message\n\nThe message won’t display under the following conditions:\n\n-   UI Page is public.\n-   UI Page is in the **Global** scope.\n-   The **glide.script.ui\\_page.customer\\_scoped.security\\_msgs\\_enabled** is set to false.\n\n**Note:** To disable the role-based ACL creation prompt, set the **glide.ui\\_page.enable\\_acl\\_create\\_ux** property to **false**. The property is set to **true** by default.\n\n## UI page process scripts\n\nIf your UI page contains a form \\(uses the *&lt;g:form&gt;* tag\\), you can submit the form and have the process script run.\n\nThe processing script can naturally access fields on the form. For example, if your form contained the *application\\_sys\\_id* field:\n\n```\n<g:ui_form>\n  <p>Click OK to run the processing script.</p>\n  <g:dialog_buttons_ok_cancel ok=\"return true\" />\n  <input type=\"hidden\" name=\"application_sys_id\" value=\"499836460a0a0b1700003e7ad950b5da\" />\n</g:ui_form>\n```\n\nYou can access the field using *application\\_sys\\_id*:\n\n```\nvar application = new GlideRecord('hr_application');\n application.get(application_sys_id);\n application.status = \"Rejected\";\n application.update();\n var urlOnStack = GlideSession.get().getStack().bottom();\n response.sendRedirect(urlOnStack);\n```\n\n**Important:** The preceding script is usable only with Global applications.\n\nIf you are using the UI page for a dialog, you can also reference the most recent URL on the stack using the code above and then send the response to that location. This is useful if you want to have the dialog's processing script update something and then redisplay the screen that brought up the dialog.\n\n"}}