Mastering URL Navigation with g_navigation in ServiceNow

Welcome back, developers and administrators! Today, we’re diving deep into a powerful, yet sometimes overlooked, aspect of ServiceNow development: manipulating URLs and navigating within the platform using the g_navigation object. In the fast-paced world of ServiceNow, efficient and dynamic user experiences are key, and understanding how to programmatically control where users go is crucial. This article will unpack the intricacies of g_navigation, drawing from practical examples and offering insights that will elevate your scripting skills.

You might have encountered situations where you need to redirect a user to a specific record, a list view, or even a custom page after a certain action. This is precisely where g_navigation shines. It’s your go-to tool for crafting seamless transitions and guiding users through your workflows. Let’s get started!

Understanding the Core: What is g_navigation?

At its heart, g_navigation is a client-side JavaScript object available in ServiceNow’s browser-based interface. Its primary purpose is to provide methods for programmatically controlling the browser’s navigation. Think of it as your scripting interface to the browser’s address bar and history.

While we’ll touch upon server-side concepts that often precede or follow navigation actions, g_navigation itself operates in the client context. This means you’ll typically find it used in client scripts, UI policies, and UI actions that are executed in the user’s browser.

Key Methods of g_navigation

The g_navigation object offers several handy methods. We’ll focus on the most common and impactful ones:

1. Navigating to a Specific Record

This is perhaps the most frequent use case. You’ve just completed an operation (like creating a user or a group, as shown in our references) and want to take the user directly to the newly created record or an existing one.

The method for this is g_navigation.openRecord(). It takes the table name and the sys_id of the record you want to navigate to.

// Example: Navigate to a newly created user record
var userGr = new GlideRecord('sys_user');
userGr.initialize();
userGr.username = 'jsmith';
userGr.firstName = 'John';
userGr.lastName = 'Smith';
userGr.email = 'jsmith@example.com';
var newSysId = userGr.insert(); // Get the sys_id of the inserted record

if (newSysId) {
    // Navigate to the newly created user record
    g_navigation.openRecord('sys_user', newSysId);
    gs.addInfoMessage('User ' + userGr.username + ' created successfully!'); // Server-side message
} else {
    gs.addErrorMessage('Error creating user.'); // Server-side message
}

Explanation: In this snippet, after successfully inserting a new user record, we capture its sys_id. We then use g_navigation.openRecord('sys_user', newSysId) to redirect the user’s browser to the form view of that specific user record. The gs.addInfoMessage and gs.addErrorMessage are server-side messages for confirmation or error reporting, respectively. Note that g_navigation is client-side, so you’d typically call it from a client script, UI action, or similar client-executing context.

2. Navigating to a List View

Sometimes, you don’t need to show a single record but a filtered list of records. This is common after bulk operations or when presenting results.

The method for this is g_navigation.openList(). It requires the table name and can optionally accept query parameters to filter the list.

// Example: Navigate to a list of all active groups
g_navigation.openList('sys_user_group');

// Example: Navigate to a list of groups with a specific name
g_navigation.openList('sys_user_group', 'name=testing');

// Example: Navigate to a list of users with a specific last name
g_navigation.openList('sys_user', 'last_name=Doe');

Explanation: g_navigation.openList('sys_user_group') will take the user to the default list view for the ‘User Group’ table. By providing a query string like 'name=testing', we can pre-filter the list to show only groups named “testing”. This is incredibly useful for guiding users to relevant data sets quickly.

3. Navigating to a URL

For more general navigation, including internal platform links or external websites, g_navigation.gotoURL() is your friend.

This method takes a URL string as an argument.

// Example: Navigate to the ServiceNow homepage
g_navigation.gotoURL('/');

// Example: Navigate to a specific module (e.g., all incidents)
g_navigation.gotoURL('/nav_to.do?uri=%2Fincident.list%3F');

// Example: Navigate to an external website
g_navigation.gotoURL('https://www.servicenow.com');

// Example: Navigate to a specific record using a direct URL
// This is less common with g_navigation.openRecord(), but possible
var incidentSysId = 'a1b2c3d4e5f678901234567890abcdef';
g_navigation.gotoURL('/nav_to.do?uri=incident.do?sys_id=' + incidentSysId + '&sysparm_view=default');

Explanation: g_navigation.gotoURL('/') is equivalent to navigating to the root of your ServiceNow instance. The more complex URLs like '/nav_to.do?uri=%2Fincident.list%3F' are often generated by the platform itself when you click on modules or links. You can construct these URLs programmatically to reach specific modules, lists, or even forms.

4. Opening in a New Window/Tab

Sometimes, you want to open a link without disrupting the user’s current context. This is where g_navigation.openInWindow() comes in handy.

This method takes a URL and optionally the window name (useful for targeting specific frames or named tabs).

// Example: Open a specific record in a new tab
var userSysId = 'some_user_sys_id';
var url = '/sys_user.do?sys_id=' + userSysId + '&sysparm_view=default';
g_navigation.openInWindow(url);

// Example: Open an external page in a new tab
g_navigation.openInWindow('https://community.servicenow.com/');

Explanation: Using g_navigation.openInWindow() is the client-side equivalent of right-clicking a link and selecting “Open link in new tab”. It’s great for opening documentation, external resources, or detailed record views without forcing the user to lose their place on the current page.

When to Use g_navigation (and When Not To)

g_navigation is a client-side object, meaning it executes in the user’s web browser. This makes it ideal for:

• Client Scripts: Reacting to field changes, form submissions, or button clicks.
• UI Actions: The “Save,” “Submit,” “Approve” buttons are classic examples where you might navigate after an action.
• UI Policies: Though less common for direct navigation, they can trigger client scripts that use g_navigation.

You cannot use g_navigation directly in:

• Business Rules: These run on the server. You’d use server-side scripting (like gs.redirect(), though this is generally discouraged in favor of client-side redirects for user experience) or set a client-callable script include to return instructions for the client.
• Script Includes (server-side): Similar to Business Rules, server-side script includes can’t directly manipulate the client’s browser.

Putting It All Together: Advanced Scenarios

Let’s explore some practical scenarios where g_navigation becomes indispensable, often in conjunction with other ServiceNow scripting concepts.

Scenario 1: Creating a User and Navigating

This directly mirrors reference question 6. After creating a user, you want to immediately open their record.

// This code would typically be in a UI Action's "Client-side" script
function createUserAndNavigate() {
    // Server-side call to a script include that creates the user
    // and returns the sys_id of the new user.
    var ga = new GlideAjax('UserManagementUtils');
    ga.addParam('sysparm_name', 'createUser'); // Method name in the script include
    ga.addParam('username', 'newuser');
    ga.addParam('firstName', 'New');
    ga.addParam('lastName', 'User');
    ga.addParam('email', 'newuser@example.com');
    ga.getXMLAnswer(function(answer) {
        // The 'answer' here is expected to be the sys_id of the created user
        if (answer && answer !== 'error') {
            g_navigation.openRecord('sys_user', answer);
            g_form.addInfoMessage('User created and record opened.');
        } else {
            g_form.addErrorMessage('Failed to create user.');
        }
    });
}

Explanation: Here, a UI Action calls a server-side Script Include (UserManagementUtils) to perform the actual user creation using GlideRecord. The script include returns the sys_id. The client-side callback then uses g_navigation.openRecord() to take the user to their new record.

Scenario 2: Conditional Navigation Based on Form Data

You might want to redirect a user to different places based on values in the current form.

// Example in a UI Action's "Client-side" script
function processRequest() {
    var requestType = g_form.getValue('request_type'); // e.g., 'hardware', 'software', 'service'

    if (requestType === 'hardware') {
        // Open the hardware catalog item
        g_navigation.gotoURL('/catalog_home.do?sysparm_catalog=282301e6c0a8010e006310242f066f68&sysparm_catalog_section=&sysparm_category=f1234567c0a8010e006310242f066f57'); // Replace with actual URL
    } else if (requestType === 'software') {
        // Open a list of software requests
        g_navigation.openList('sc_req_item', 'cat_item.category=f1234567c0a8010e006310242f066f57'); // Example query
    } else {
        // Default action or navigate to a general dashboard
        g_navigation.gotoURL('/');
    }
}

Explanation: This code checks the value of the ‘request_type’ field on the current form. Based on its value, it uses g_navigation.gotoURL() or g_navigation.openList() to guide the user to the most relevant page. This creates a much more intuitive and efficient user experience.

Deep Dive into Related Concepts

Understanding g_navigation is also enhanced by understanding related ServiceNow scripting features. Let’s briefly touch upon some mentioned in your references that play a role in building these navigation-driven workflows.

GlideRecord: The Foundation of Data Manipulation

As seen in references 6, 7, 8, and 10, GlideRecord is fundamental to interacting with ServiceNow data. Whether you’re creating users, groups, adding roles, or managing group members, GlideRecord is your server-side tool. The sys_id you obtain from a GlideRecord.insert() or GlideRecord.get() operation is often what you’ll pass to g_navigation.openRecord().

The `current` Object: Context on the Form

Reference 46 and 47 discuss the current object. This object is available in server-side scripts (like Business Rules) and represents the record being processed. While g_navigation is client-side, server-side scripts can prepare data or trigger client actions based on the current record’s values. For example, a Business Rule might update a field on current, and then a related client-side event (like a form submit that triggers a UI Action) could use the updated value to decide where to navigate.

Reference Qualifiers and Dependent Values: Influencing User Input

References 48 and 49 discuss Reference Qualifiers and Dependent Values. These are critical for shaping the data users interact with *before* any navigation happens. By filtering reference fields or creating cascaded dropdowns, you ensure users select valid data. This improved data quality indirectly aids navigation, as you’re less likely to encounter errors or unexpected behavior when navigating based on well-formed data.

For instance, if you have a reference qualifier on a “Configuration Item” field that only shows active CIs, any navigation driven by selecting a CI will be more reliable.

Troubleshooting Common Navigation Issues

While powerful, g_navigation can sometimes lead to unexpected behavior if not used correctly. Here are some common pitfalls and how to address them:

// Example with encoding
var searchTerm = "User Accounts";
var encodedSearchTerm = encodeURIComponent(searchTerm);
g_navigation.gotoURL('/nav_to.do?uri=%2Fsys_search.do%3Fsearch%3D' + encodedSearchTerm);

Conclusion

Mastering g_navigation is an essential step in becoming a proficient ServiceNow developer. It empowers you to create dynamic, user-friendly interfaces that guide users seamlessly through your custom applications and workflows. By understanding its methods, its client-side nature, and how it interacts with server-side operations and other ServiceNow features, you can build more sophisticated and intuitive user experiences.

Remember to always test your navigation logic thoroughly. A well-placed redirect can make all the difference in user adoption and efficiency. Keep experimenting, keep learning, and happy coding!