gs.getProperty() in ServiceNow — Reading System Properties in Scripts

gs.getProperty() reads system properties stored in the sys_properties table. It is the standard way to make ServiceNow scripts configurable without hardcoding values — feature flags, API endpoints, thresholds, and toggles all belong in system properties.

Basic Usage

// Read a system property
var value = gs.getProperty('my.app.setting');
gs.log(value);
// Returns the property value as a string, or null if not found

With a Default Value

Always provide a default value. If the property does not exist, gs.getProperty() returns null without a default, which will cause null reference errors if you use the value directly.

// Returns 'default_value' if property not found
var value = gs.getProperty('my.app.setting', 'default_value');

// Practical examples
var maxRetries = gs.getProperty('my.integration.max_retries', '3');
var apiEndpoint = gs.getProperty('my.api.endpoint', 'https://api.example.com');
var featureEnabled = gs.getProperty('my.feature.enabled', 'false');

Type Handling — Everything is a String

System properties are always stored and returned as strings. You must convert them to the right type in your script:

// Boolean properties
var isEnabled = gs.getProperty('my.feature.enabled', 'false') === 'true';
if (isEnabled) {
    // feature is on
}

// Integer properties
var maxItems = parseInt(gs.getProperty('my.max.items', '100'));
var threshold = parseFloat(gs.getProperty('my.threshold', '0.75'));

// JSON properties (store complex config as JSON string)
var configStr = gs.getProperty('my.app.config', '{}');
var config = JSON.parse(configStr);
var timeout = config.timeout || 30;

Creating System Properties

Navigate to System Properties > All Properties > New to create a property. Key fields:

• Name — use dot notation: myapp.module.setting
• Value — the property value
• Description — always fill this in — document what the property controls
• Type — String, Integer, Boolean, Date, Password2
• Private — true for sensitive values (passwords, API keys)

Caching Behaviour

System properties are cached. When you update a property, the new value is available to new sessions almost immediately (typically within a few seconds). Long-running background scripts that loop indefinitely may see stale values — if you need real-time property reads in a loop, use a GlideRecord query against sys_properties directly instead.

// For real-time reads in long-running scripts
var propGR = new GlideRecord('sys_properties');
propGR.get('name', 'my.app.setting');
var liveValue = propGR.getValue('value');

gs.getProperty() in Client Scripts

gs.getProperty() is a server-side method — it is not available in Client Scripts directly. To read a property on the client side, use a GlideAjax call to a Script Include, or pass the value through a hidden field or UI Action.

// Script Include (server side)
var MyUtils = Class.create();
MyUtils.prototype = Object.extendsObject(AbstractAjaxProcessor, {
    getAppSetting: function() {
        return gs.getProperty(
            this.getParameter('prop_name'),
            this.getParameter('default')
        );
    }
});

// Client Script (calling the Script Include)
var ga = new GlideAjax('MyUtils');
ga.addParam('sysparm_name', 'getAppSetting');
ga.addParam('prop_name', 'my.app.setting');
ga.addParam('default', 'fallback');
ga.getXMLAnswer(function(answer) {
    console.log('Property value: ' + answer);
});

Naming Conventions

Use consistent dot-notation naming for system properties:

• myapp.feature.enabled — feature flags
• myapp.integration.endpoint — external system URLs
• myapp.limits.max_records — configurable thresholds
• myapp.notifications.enabled — notification toggles

Always prefix with your application or scope name to avoid conflicts with ServiceNow's own properties.

Sensitive Values — Use Password2 Type

For API keys, passwords, or secrets stored as system properties, set the type to Password2. Password2 properties are encrypted at rest, masked in the UI, and not exported in Update Sets. Never store secrets as plain String properties.

// Reading a Password2 property (decrypts automatically)
var apiKey = gs.getProperty('my.api.secret_key');
// Value is decrypted and available as plain text in the script
// but is stored encrypted in the database