Verify the functionality of menus and modules in the application navigator.

Application Menu Visibility

Verifies the visibility, or lack thereof, of selected application menus in the application navigator (left navigation bar). For example, you create a test that first impersonates a user, then verifies that specified application menus (such as Self-Service and Reports) are visible, or are not visible, to that user.

Table 1. Inputs
FieldDescription
Execution order Integer specifying the order in which the test executes this step.

As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
Active Option to activate this test step for use.
Application The application scope in which the system runs this test or test suite.
Test Read-only name of the test that you're adding the step to.
Step config Read-only name of the step.
Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
Notes Notes about the test step.
Navigator Navigator version to assert against
  • Core UI (UI16): If you are creating new steps, you will have Core UI by default.
  • Next Experience: If you have Next Experience enabled, Next Experience is the default navigator. If it is disabled, Core UI is the default navigator.
Visible assert type Specifies how application menus selected in the Visible application menus field should be tested for visibility in the application navigator.
  • At least these application menus are visible: At minimum, all the selected application menus are visible in the application navigator.
  • Only these application menus are visible: Only the selected application menus are visible in the application navigator.
Visible application menus Application menus whose visibility in the application navigator is being verified.
Not visible assert type Specifies how application menus selected in the Not visible application menus field should be tested for lack of visibility in the application navigator.
  • At least these application menus are not visible: At minimum, all the selected application menus are not visible in the application navigator.
  • Only these application menus are not visible: Only the selected application menus are not visible in the application navigator.
Not visible application menus Application menus whose lack of visibility in the application navigator is being verified.

Create an application menu

Application menus define the main content that users can access in the application navigator. You can configure which applications appear in the application navigator.

Before you begin

Role required: admin

About this task

When creating an application menu, consider grouping like modules into a consolidated application menu. When editing an existing menu, add more useful modules to the application menu, and remove unneeded ones.

Procedure

  1. Navigate to All > System Definition > Application Menus.
  2. Click New.
  3. Complete the form.
    Field Description
    Title Defines the display name of the application menu.
    Roles Restricts access to the specified roles. All users can view the application menu when it is active.
    Category Specifies the menu category that defines the navigation menu style (default value is Custom Applications).
    Hint Defines the text that appears in a tooltip when a user points to this application menu.
    Active Select the check box to activate the application menu. Only active application menus appear in the application navigator.
    Description Provide a more detailed explanation of what this application does.
    Other fields
    Order Defines the relative position of the application menu in the application navigator. If you do not specify an order, the default order of the menu category is used.
    Default device type This field is not used. You can define application menus for mobile devices in a separate table.
    Note: You may need to configure the form to see all fields.
  4. Click Submit.
  5. Create modules to appear in the application menu.
    Only application menus that contain modules appear in the application navigator.

Create a module

Modules are the children, or the second tier navigation options to the applications in the application navigator. Modules often link to other pages or records in the platform. You can configure which modules appear in the application navigator using Application Menus module.

Watch this five-minute video to learn about adding application menus and modules to the application navigator.

Before you begin

Role required: admin

Procedure

  1. Open the application menu record using one of the following methods.
    • Navigate to System Definition > Application Menus and select the application menu from the list.
    • Point to the application menu and click the edit application (pencil) icon.
    Figure 1. Two methods for creating a module
    Gif showing the first and second methods for creating a module
  2. Scroll down to the Modules related list and click New.
  3. Define the module by completing the fields on the Module form.
    Table 2. Module form
    FieldDescription
    Title Defines the module name. Choose a title that clearly identifies the module.
    Application menu Specifies the name of the application menu under which the module appears.
    Hint Defines the tooltip that appears when a user points to the module name.
    Note: Module Hints are deprecated in Core UI
    Order The order in which the module displays relative to other modules.
  4. On the Visibility tab, complete the fields.
    Table 3. Visibility tab
    Field Description
    Roles Restricts module access to the specified roles. If this field is left blank, the module is visible to all users who have access to the application menu.
    Active Defines whether the module appears in the application navigator.
    Override application menu roles Allows users to access this module even if they do not have permission to view the containing application menu. Users must still meet the role requirements for this module.
  5. On the List Type tab, complete the fields.

    The fields displayed depend on the Link type you choose. All module URIs must be encoded. If you supply arguments to the module URI, either you or ServiceNow. For more information about encoding module URIs, see Encoding module URIs.

    Table 4. List Type tab
    FieldDescription
    Link type Specifies what type of link this module opens. You must specify additional information based on the link type. See Module link types.
    Table Specifies the table used by the module.
    Note: The list shows only tables and database views that are in the same scope as the module.
    Filter Conditions for the items presented in the module, for example, Active is true.
    Argument String appended to the URI to create the module URI. Can be a sysparm_query. These values must be encoded either by you or ServiceNow. For more information about encoding module URIs, see Encoding module URIs.
    Order Specifies the order in which the modules appear under the application.

Module link types

The Link type field on the Module form specifies what type of link the module opens.

Table 5. Module link types
Link TypeDescription
Assessment Links to the assessment-based survey you select in the Assessment reference field. See Create a survey module.
Content Page Displays the content page you select in the Content page reference field. See Create a content page.
Documentation Link Links to a documentation page and opens in a new tab or window. This link type is used with embedded metadata in documentation topics. To open an internal document from a module, use the URL (from Arguments) module link type.
Homepage Displays the homepage you select in the Homepage reference field.
HTML (from Arguments) Places HTML in the application navigator. This link type is used for more complicated links, where a flat URL is not customizable enough.
Note:
  • The HTML (from Arguments) link type is supported in the legacy UI15 and UI11 interfaces only. In Core UI, use the URL (from Arguments) link type instead.
  • Enter a value for the Arguments field.
List Filter Displays an unpopulated list view for the table you select in the Table field. Allows users to specify a filter without loading the list first. Use the Filter field to define the default filter for the list. Use the View name field to specify a View management.
List of Records Displays the list view for the table you select in the Table field. Use the Filter field to define the default filter for the list. Use the View name field to specify a view.
Map Page Displays the map page you select in the Map page reference field.
New Record Displays a form for creating a record in the table you select in the Table field.
Run a Report Runs the saved report you select in the Report field.
Script (from Arguments) Runs a script, as defined in the Arguments field.
Note: Enter a value for the Arguments field.
Search Screen Link that displays a blank form for searching records in the table. Use the View name field to specify a view.
Note: Use the parameter &sysparm_result_view=view_name to define the view the results are rendered in.

All searches use a [starts with] query to search for matching text. Other query types are not supported in search screens.
Separator Creates a division between modules. Enter a name in the Title field to add a section name that users can collapse or expand.
Single Record Displays a form for a single record on the table. Use the View name field to specify a view.
Survey Links to the legacy survey you select in the Survey reference field. Use the Survey overwrite check box to determine whether the survey can be taken multiple times.
Note: The Survey link type is for use with legacy surveys only, which assessment-based surveys replace. Select the Assessment link type to link the module to an assessment-based survey.
Timeline Page Displays the timeline page you select in the Timeline Page reference field. See Timeline pages.
URL (from Arguments) Opens any URL, as defined in the Arguments field.

[Optional] Use the Window name field to define a link that opens in a new window.

Note:
  • For internal links, always use a relative link such as ./catalog_home.do?sysparm_view=catalog_default or catalog_home.do?sysparm_view=catalog_default. Do not use an absolute link to a ServiceNow instance. It creates problems when you move an update set from a development instance to a production instance because the URL still references the development instance.
  • Enter a value for the Arguments field.

Encoding module URIs

Clicking a module name in the navigation pane executes a URI that opens the module's page in the content pane. All the characters in module URIs must be URL-encoded or the link breaks.

Note: If you're upgrading to the New York release or later from a pre-New-York release, your module UIs may break if they do not follow the conventions presented in this topic.

When you create modules, you have the option of adding arguments and filter conditions that sort and/or reduce the number of results displayed in the content pane. When you click a module name in System Definitions > Application Definitions, you can see those conditions and arguments on the Link Type tab.

Link type tab

The argument definition in Arguments and filter conditions defined in Filter become part of the module's URI and must be URL-encoded. ServiceNow automatically URL-encodes filter conditions and appends them to the module URI using sysparm_query. For example, adding the filter condition, Active is true appends sysparm_query=active%3Dtrue to the module's URI; %3D is the URL-encoding for the equals sign (=).

The following table shows when you must URL-encode the argument in the Arguments field and when ServiceNow URL-encodes the argument.

Table 6. Rules for encoding arguments
Has a filter condition?Argument definition starts withWho encodes the argument?How argument is handled
No ^

ServiceNow

 Removes the caret (^) from the argument, encodes it and uses sysparm_query to append it to the module URI.
No & You Removes the ampersand (&) from the argument and appends it to the module URI.
No Anything else ServiceNow Encodes the argument and uses sysparm_query to append it to the module URI.
Yes ^ ServiceNow URL-encodes the filter definition and the argument and uses sysparm_query to append the combination to the module URI.
Yes Anything else You URL-encodes the filter definition and uses sysparm_query to append it and the (unaltered) arguments to the module URI.

You can turn on (the default) and off the URL-encoding requirement for module UIs using the glide.ui.encode_module_uri property.

Examples

The following examples demonstrate when you have to URL-encode the argument definition in Arguments:
  • There are no filter conditions and the argument definition in Arguments starts with an ampersand, for example,&sysparm_fixed_query=assigned_to=javascript:gs.user_id().

    This argument breaks the module URI because the equals sign and the colon are not URL-encoded, and the ampersand prevents ServiceNow from URL-encoding the argument. URL-encode the argument: &sysparm_fixed_query=assigned_to%3Djavascript%3Ags.user_id().

  • There are filter conditions and the argument definition in Arguments does not start with a caret (^), for example, sysparm_name=Barnes & Noble's.

    This argument breaks the module URI because the ampersand and spaces are not URL-encoded. URL-encode the argument: sysparm_name=Barnes%20%26%20Nobel's

Module Visibility

Verify the visibility, or lack thereof, of selected modules in the application navigator (left navigation bar). For example, create a test that first impersonates a user, then verifies that specified modules (such as Homepage and My Requests) are visible, or are not visible, to that user.

Table 7. Inputs
FieldDescription
Execution order Integer specifying the order in which the test executes this step.

As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
Active Option to activate this test step for use.
Application The application scope in which the system runs this test or test suite.
Test Read-only name of the test that you're adding the step to.
Step config Read-only name of the step.
Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
Notes Notes about the test step.
Navigator Navigator version to assert against
  • Core UI (UI16): If you are creating new steps, you will have Core UI by default.
  • Next Experience: If you have Next Experience enabled, Next Experience is the default navigator. If it is disabled, Core UI is the default navigator.
Visible assert type Specifies how modules selected in the Visible modules field should be tested for visibility in the application navigator.
  • At least these modules are visible: At minimum, the modules selected in the Visible modules field are visible in the application navigator.
  • Only these modules are visible: Only the specific modules selected in the Visible modules field are visible in the application navigator.
Visible modules Modules whose visibility in the application navigator is being verified.
Not visible assert type Specifies how modules selected in the Not visible modules field should be tested for lack of visibility in the application navigator.
  • At least these modules are not visible: At minimum, the modules selected in the Not visible modules field are not visible in the application navigator.
  • Only these modules are not visible: Only the specific modules selected in the Not visible modules field are not visible in the application navigator.
Not visible modules Modules whose lack of visibility in the application navigator is being verified.

Navigate to Module

Open a module from the application navigator, as if a user had clicked it. The module must be visible to the currently executing user to navigate to it.

Note: Not all pages are currently testable. Wherever the module takes you is your responsibility.
Table 8. Inputs
FieldDescription
Execution order Integer specifying the order in which the test executes this step.

As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
Active Option to activate this test step for use.
Timeout Number of seconds allowed before the step fails. If the validation fails, the system repeats the step until it reaches the duration of the timeout. If the validation fails after the timeout duration has passed, the step fails.
Application Application scope in which the system runs this step.
Test Read-only name of the test that you're adding the step to.
Step config Read-only name of the step.
Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
Notes Notes about the test step.
Module Module that should be opened. To navigate to the selected module, the module must be visible to the currently executing user in the application navigator.
The following modules are not supported and cannot be tested:
  • Modules that are separators
  • Modules that do not link to a specific page, but instead execute client-side JavaScript (such as Studio and the Script Debugger)
  • Modules that link to external websites, such as the ServiceNow documentation site (servicenow.com/docs)
  • Modules that reload or redirect the entire page