GlideSystem.getProperty() — ServiceNow API

gs.getProperty(key, defaultValue)→ string

beginnerTested on Xanadu

What It Does

The gs.getProperty() method queries the sys_properties table for a record where the name field matches your key parameter. It returns the value field as a string, regardless of what type of data the property actually contains. This is ServiceNow's primary mechanism for storing and retrieving configuration values that should be adjustable without code changes.

Internally, ServiceNow caches property values in memory after the first access, making subsequent calls to the same property very fast. The platform reads from the database only when the property hasn't been cached yet or when the cache is invalidated. This caching behavior means property changes don't take effect immediately in running sessions.

The method always returns a string data type, even if the property value looks like a number or boolean. If the property doesn't exist and you didn't provide a defaultValue, it returns null. If the property exists but has an empty value field, it returns an empty string.

Property names are case-sensitive and must match exactly what's stored in the sys_properties table. The platform includes hundreds of built-in properties with names following dot notation conventions like glide.servlet.max_filename_length or email.smtp.port. You can also create custom properties for your applications.

This method is closely related to gs.setProperty() for writing property values and gs.getPropertyValue() which attempts to convert the string result to the appropriate JavaScript data type. Most developers use getProperty() and handle type conversion manually for better control.

When to Use This

Use gs.getProperty() whenever you need configurable values that administrators should be able to modify without touching code. This includes timeout values, API endpoints, feature flags, maximum record counts, email addresses for notifications, and any other setting that might need to change between environments or over time. System properties provide a clean separation between configuration and business logic.

Don't use this method for data that belongs in regular tables or for values that should be stored per-user or per-record. System properties are instance-wide settings. If you need user preferences, use the User Preference API. If you need application-specific configuration with more complex data structures, consider creating a dedicated configuration table instead of cramming everything into system properties.

Avoid using gs.getProperty() in loops or frequently-called functions without caching the result locally. While the platform caches properties, every call still has overhead. Store the result in a variable if you'll use it multiple times within the same script execution.

Return Value

The method always returns a string when the property exists, even if the stored value looks like a number, boolean, or other data type. If you need the value as a specific type, you must convert it yourself using parseInt(), parseFloat(), or boolean comparison. When the property doesn't exist, the method returns either null or your provided defaultValue.

Always check for null returns when you don't provide a default value, especially in production code. The safest pattern is to always provide a sensible default value as the second parameter. This prevents null reference errors and makes your code's behavior predictable even when properties are missing or misconfigured.

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

Platform Behavior & Side Effects

No Business Rules, ACLs, or notifications fire when reading properties — this is a direct database read with caching
Property values are cached in memory after first access, making subsequent calls very fast but changes don't appear immediately
No database writes occur — this method is read-only and safe to call in any script context
Performance is excellent after caching, but first access requires a database query — consider caching results locally in loops
Works identically in Business Rules, Script Includes, Scheduled Jobs, and UI Actions — no behavioral differences based on context
Property access is not logged in system logs unless the property itself controls logging behavior
Scoped applications can only access properties they own or global properties — cross-scope property access is restricted

Parameters

Name	Type	Required	Description
key	string	Yes	The name of the system property to retrieve from the sys_properties table. Case-sensitive and must match exactly. Property names typically use dot notation like 'glide.servlet.max_filename_length'.
defaultValue	string	No	The value to return if the property doesn't exist or has no value. Optional parameter that prevents null returns when properties are missing or empty.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Code Examples

Basic property retrieval with defaultsbasic

// Get timeout value for external API calls
var apiTimeout = gs.getProperty('custom.api.timeout', '30000');
var timeoutMs = parseInt(apiTimeout);

// Get feature flag for new functionality
var newFeatureEnabled = gs.getProperty('custom.feature.new_dashboard', 'false');
var isEnabled = (newFeatureEnabled === 'true');

// Get email address for notifications
var adminEmail = gs.getProperty('custom.admin.email', 'admin@company.com');

gs.info('API timeout: ' + timeoutMs + 'ms');
gs.info('New feature enabled: ' + isEnabled);
gs.info('Admin email: ' + adminEmail);

This example shows the essential pattern of always providing default values and manually converting strings to appropriate types. The defaults ensure your script works even when properties are missing.

Caching properties in frequently-called functionsintermediate

var MyUtils = Class.create();
MyUtils.prototype = {
    initialize: function() {
        // Cache properties once during initialization
        this.maxRetries = parseInt(gs.getProperty('custom.api.max_retries', '3'));
        this.retryDelay = parseInt(gs.getProperty('custom.api.retry_delay', '5000'));
        this.debugMode = gs.getProperty('custom.debug.enabled', 'false') === 'true';
    },
    
    processRecord: function(record) {
        // Use cached values instead of calling gs.getProperty() repeatedly
        for (var i = 0; i < this.maxRetries; i++) {
            if (this.debugMode) {
                gs.info('Processing attempt ' + (i + 1) + ' for ' + record.number);
            }
            // Processing logic here
            break; // Success case
        }
    },
    
    type: 'MyUtils'
};

This pattern caches property values during object initialization to avoid repeated database calls. Essential for Script Includes that might be called many times in a single transaction.

The null return gotchaadvanced

// WRONG: This can cause null pointer errors
var maxSize = gs.getProperty('custom.file.max_size');
if (maxSize.length > 0) { // Crashes if property doesn't exist
    // Process with max size
}

// RIGHT: Always handle null returns
var maxSize = gs.getProperty('custom.file.max_size');
if (maxSize && maxSize.length > 0) {
    var sizeLimit = parseInt(maxSize);
    // Safe to use sizeLimit
}

// BETTER: Use default values to avoid null entirely
var maxSize = gs.getProperty('custom.file.max_size', '10485760'); // 10MB default
var sizeLimit = parseInt(maxSize); // Always safe

The classic mistake is forgetting that properties can return null when they don't exist. Always check for null or provide default values to prevent runtime errors.

Gotchas

Property values are always returned as strings, even if they contain numbers or booleans — you must convert types manually.

Properties are cached after first access, so changes made through the UI or other scripts won't appear immediately in running sessions.

Property names are case-sensitive and must match exactly — 'Custom.Property' is different from 'custom.property'.

Null is returned when properties don't exist and no default value is provided, which can cause null pointer errors in string operations.

Scoped applications can only read properties they own or global properties — cross-scope access is blocked even if you know the property name.

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue