GlideSystem API

GlideSystem API: Complete Guide for ServiceNow CAD Exam

Understanding the GlideSystem API in ServiceNow

The GlideSystem API is one of the most fundamental and frequently used APIs in ServiceNow development. Known commonly by its shorthand gs, this API provides a collection of convenient methods that allow developers to interact with system-level properties, user sessions, logging mechanisms, and other platform utilities. For anyone preparing for the ServiceNow Certified Application Developer (CAD) exam, mastering the GlideSystem API is absolutely essential.

Why is the GlideSystem API Important?

The GlideSystem API is important for several key reasons:

1. Ubiquitous Usage: Almost every server-side script in ServiceNow leverages the gs object in some capacity. Whether you are writing Business Rules, Script Includes, Scheduled Jobs, or UI Actions, you will encounter GlideSystem methods regularly.

2. Session and User Context: It provides critical methods for retrieving information about the currently logged-in user, their roles, and their session data. This is vital for building secure, role-based application logic.

3. Debugging and Logging: GlideSystem offers powerful logging methods that are indispensable for debugging and monitoring scripts in production and development environments.

4. System Properties and Configuration: It allows developers to read and set system properties dynamically, enabling flexible and configurable application behavior.

5. Exam Relevance: The CAD exam frequently tests your understanding of GlideSystem methods, their correct usage, and the contexts in which they operate.

What is the GlideSystem API?

The GlideSystem API is a server-side API accessible through the global object gs. It is available in all server-side scripting contexts within ServiceNow, including Business Rules, Script Includes, Scheduled Jobs, Fix Scripts, UI Actions (server-side), and more. It acts as a utility toolkit providing access to system-level functions without needing to instantiate any objects.

Key characteristics of the GlideSystem API:

- It is a server-side only API (not available in client-side scripts like Client Scripts or UI Policies).
- It is accessed via the gs global object.
- It does not need to be instantiated — you simply call gs.methodName().
- It provides methods related to users, sessions, logging, date/time, properties, events, and messages.

How Does the GlideSystem API Work?

The GlideSystem API works by exposing a set of predefined methods through the gs object. Here is a comprehensive breakdown of the most important method categories:

1. User and Session Methods

These methods retrieve information about the current user and their session:

- gs.getUserID() — Returns the sys_id of the currently logged-in user.
- gs.getUserName() — Returns the username (user_name field) of the current user.
- gs.getUserDisplayName() — Returns the display name (first and last name) of the current user.
- gs.hasRole('role_name') — Returns true if the current user has the specified role. Important: Users with the 'admin' role will always return true for any role check unless the second parameter is set to true.
- gs.hasRole('role_name', true) — The second parameter, when set to true, ensures that the admin override is excluded, meaning it checks for the exact role only.
- gs.getUser() — Returns a GlideUser object representing the current user, which provides additional methods for user-related queries.
- gs.getSession() — Returns the current session object (GlideSession), allowing access to session-level data.
- gs.isLoggedIn() — Returns true if the current user is logged in (as opposed to an anonymous/public user).
- gs.isInteractive() — Returns true if the current session is interactive (i.e., a user is actively using the browser, not a background process or scheduled job).

2. Logging Methods

Logging is critical for debugging and monitoring. GlideSystem provides several logging levels:

- gs.info('message') — Logs an informational message to the system log.
- gs.warn('message') — Logs a warning message to the system log.
- gs.error('message') — Logs an error message to the system log.
- gs.debug('message') — Logs a debug-level message (only visible when debug mode is enabled for the session or script).
- gs.log('message', 'source') — Logs a message with a specified source identifier. Note: gs.log() is considered legacy and gs.info(), gs.warn(), gs.error(), and gs.debug() are preferred in modern development.
- gs.print('message') — Outputs a message, primarily used in background scripts for testing purposes. It writes output to the screen in the background script executor.

All modern logging methods (info, warn, error, debug) support parameterized messages using curly braces as placeholders:
gs.info('User {0} has role {1}', userName, roleName);

3. System Property Methods

System properties allow configurable values to be stored and retrieved:

- gs.getProperty('property_name') — Returns the value of the specified system property as a string.
- gs.getProperty('property_name', 'default_value') — Returns the property value, or the default value if the property does not exist.
- gs.setProperty('property_name', 'value', 'description') — Sets the value of a system property. If the property does not exist, it creates one.

Important exam note: gs.getProperty() always returns a string. If the property stores a boolean-like value such as 'true', you need to compare it as a string or convert it appropriately.

4. Date and Time Methods

- gs.now() — Returns the current date and time in the format yyyy-MM-dd HH:mm:ss in the user's time zone.
- gs.nowDateTime() — Returns the current date and time in UTC format.
- gs.daysAgo(days) — Returns a date/time value for the specified number of days ago. Often used in queries.
- gs.hoursAgo(hours) — Returns a date/time value for the specified number of hours ago.
- gs.minutesAgo(minutes) — Returns a date/time value for the specified number of minutes ago.
- gs.beginningOfLastMonth() — Returns the date/time of the beginning of the previous month.
- gs.endOfLastMonth() — Returns the date/time of the end of the previous month.
- gs.beginningOfThisMonth() — Returns the date/time of the beginning of the current month.
- gs.beginningOfThisYear() — Returns the date/time of the beginning of the current year.

5. Event and Message Methods

- gs.eventQueue('event_name', gr, parm1, parm2) — Queues a system event. This is commonly used to trigger notifications or other event-driven processes. The gr parameter is a GlideRecord representing the current record, and parm1 and parm2 are optional string parameters passed to the event.
- gs.addInfoMessage('message') — Displays a blue informational message banner at the top of the page for the user.
- gs.addErrorMessage('message') — Displays a red error message banner at the top of the page for the user.

Key distinction: gs.addInfoMessage() and gs.addErrorMessage() are server-side methods that display messages to the user in the UI. They are commonly used in Business Rules and UI Actions.

6. Utility Methods

- gs.nil(value) — Returns true if the value is null, undefined, or an empty string. This is a very handy null-check utility.
- gs.tableExists('table_name') — Returns true if the specified table exists in the instance.
- gs.generateGUID() — Generates and returns a new globally unique identifier (GUID/sys_id).
- gs.include('script_include_name') — Includes a non-class-based (on-demand) Script Include. Note: This is used for legacy-style Script Includes that are not class-based.
- gs.urlEncode('string') — URL-encodes the specified string.
- gs.urlDecode('string') — URL-decodes the specified string.
- gs.base64Encode('string') — Encodes a string to Base64.
- gs.base64Decode('string') — Decodes a Base64 string.

Common Use Cases and Examples

Example 1: Checking User Role in a Business Rule
In a Business Rule, you might want to prevent non-admin users from modifying a record:
if (!gs.hasRole('admin')) {
  current.setAbortAction(true);
  gs.addErrorMessage('You do not have permission to modify this record.');
}

Example 2: Logging with Parameters
gs.info('Incident {0} was assigned to {1}', current.number, current.assigned_to.getDisplayValue());

Example 3: Using gs.getProperty()
var maxRetries = parseInt(gs.getProperty('my_app.max_retries', '3'));
This retrieves a property value and converts it to an integer, with a default of 3.

Example 4: Queuing an Event
gs.eventQueue('incident.assigned', current, current.assigned_to, gs.getUserID());

Example 5: Using gs.nil()
if (gs.nil(current.assigned_to)) {
  gs.addInfoMessage('Please assign this incident to a technician.');
}

GlideSystem API vs. Other APIs

It is important to distinguish GlideSystem from other commonly tested APIs:

- GlideSystem (gs) — System-level utilities, logging, user info, properties (server-side only).
- GlideRecord — Database query and manipulation (server-side and scoped).
- GlideAjax — Client-to-server communication for asynchronous calls.
- GlideForm (g_form) — Client-side form manipulation.
- GlideUser (g_user) — Client-side user information. Do not confuse gs.getUser() (server-side) with g_user (client-side).


Exam Tips: Answering Questions on GlideSystem API

Tip 1: Remember that gs is Server-Side Only
If an exam question presents a scenario using gs in a Client Script or UI Policy, the answer is likely incorrect. The GlideSystem API is exclusively a server-side API. Client-side equivalents include g_user for user information and g_form for form manipulation.

Tip 2: Know the Difference Between gs.log() and gs.info()/gs.warn()/gs.error()
The exam may test whether you know that gs.log() is considered legacy. Best practice is to use gs.info(), gs.warn(), gs.error(), and gs.debug() for logging. These newer methods also support parameterized messages with placeholders like {0}, {1}, etc.

Tip 3: Understand gs.hasRole() Admin Override Behavior
A very common exam topic: gs.hasRole('itil') returns true for a user with the admin role, even if they do not explicitly have the itil role. This is because admin overrides all role checks by default. To check for the exact role without admin override, use gs.hasRole('itil', true) — but note that this second-parameter behavior may be tested.

Tip 4: gs.getProperty() Always Returns a String
Even if a property stores a number or boolean, gs.getProperty() returns it as a string. Be cautious in exam questions that involve conditional logic based on property values — you may need to parse or compare as a string (e.g., gs.getProperty('prop') == 'true').

Tip 5: Know When to Use gs.addInfoMessage() vs. gs.addErrorMessage()
These methods display banners in the user interface. gs.addInfoMessage() shows a blue informational banner, while gs.addErrorMessage() shows a red error banner. They are server-side methods but affect the client UI. They are commonly used in Business Rules and server-side UI Actions.

Tip 6: gs.nil() is a Comprehensive Null Check
The gs.nil() method checks for null, undefined, and empty strings all in one call. This is more thorough than a simple == null check. Exam questions may present scenarios where gs.nil() is the best choice for validation.

Tip 7: Understand gs.eventQueue() Parameters
The method signature is gs.eventQueue(eventName, glideRecord, parm1, parm2). The first parameter is the event name (must be registered in the Event Registry), the second is typically the current GlideRecord, and parm1/parm2 are optional string parameters. These parameters can be referenced in notification scripts and email templates.

Tip 8: Date/Time Methods for Queries
Methods like gs.daysAgo(), gs.hoursAgo(), and gs.minutesAgo() are frequently used in GlideRecord queries to filter records by relative time. For example, finding all incidents created in the last 7 days would use gr.addQuery('sys_created_on', '>=', gs.daysAgo(7)).

Tip 9: gs.isInteractive() for Background vs. Interactive Context
Use gs.isInteractive() to determine if the script is running in an interactive user session versus a background process like a Scheduled Job. This is useful when you want to display messages only when a user is actively using the system (since gs.addInfoMessage() would be meaningless in a background script).

Tip 10: Distinguish Server-Side gs Methods from Client-Side Equivalents
The exam often tests whether you can identify the correct API for the correct context:
- Server-side user info: gs.getUserID(), gs.getUserName(), gs.hasRole()
- Client-side user info: g_user.userID, g_user.userName, g_user.hasRole()
These serve similar purposes but operate in different scripting contexts. Mixing them up is a common exam trap.

Tip 11: Read Questions Carefully for Context Clues
Exam questions will often describe a specific scripting context (Business Rule, Client Script, Scheduled Job, etc.). Use this context to determine whether gs methods are valid. If the scenario is a Client Script, any answer involving gs is likely wrong.

Tip 12: Practice Writing Scripts Using gs Methods
The best way to prepare for GlideSystem-related exam questions is hands-on practice. Use a ServiceNow Personal Developer Instance (PDI) to write Business Rules and Background Scripts that leverage various gs methods. Familiarity through practice will help you quickly identify correct answers on the exam.

Summary

The GlideSystem API (gs) is a cornerstone of ServiceNow server-side development. It provides essential utilities for user and session management, logging, system properties, date/time operations, event handling, and user messaging. For the CAD exam, focus on understanding which methods belong to GlideSystem, their correct usage contexts, return types, and the distinction between server-side and client-side APIs. Mastering these concepts will help you confidently answer GlideSystem-related questions and build robust ServiceNow applications.