GlideSystem.setProperty() — ServiceNow API

gs.setProperty(key, value, description)→ void

intermediateTested on Xanadu

What It Does

The setProperty method creates a new system property or updates an existing one in the sys_properties table. When called, it performs an immediate database operation — either inserting a new record if the property key doesn't exist, or updating the existing record's value and description fields.

ServiceNow's property cache is immediately invalidated when this method executes, forcing a cache refresh on the next property read. This ensures that subsequent calls to gs.getProperty() return the updated value, even within the same transaction. The property becomes available system-wide immediately after the method completes.

The method returns void and provides no indication of success or failure. If the operation fails due to database constraints or permissions, the script will throw an exception rather than returning a status value. All parameter values are converted to strings before storage, regardless of the input type.

Property keys are case-sensitive and must be unique across the entire instance. If you attempt to create a property with a key that matches an existing system property, the existing property's value and description will be overwritten. This behavior makes it possible to accidentally modify critical system configurations.

⚠️

This method can overwrite existing system properties without warning. Always check if a property exists before creating it unless you specifically intend to update an existing value.

Unlike gs.getProperty() which reads from cache, setProperty performs direct database writes. This makes it significantly slower than property reads and unsuitable for high-frequency operations or tight loops.

When to Use This

Use setProperty for application-specific properties that need to be created or updated programmatically during installation, upgrade, or automated configuration processes. This is appropriate for scoped applications that need to establish their own configuration properties or for migration scripts that need to set system-wide settings.

Most property management should happen through the System Properties UI or during application installation. Avoid using this method in business rules or frequently-executed scripts because it bypasses normal change management processes and creates properties that administrators might not know exist. For runtime configuration that changes frequently, consider using custom tables with proper UI pages instead of system properties.

Never use this method to store user-specific data, session information, or values that change frequently. System properties are global, cached, and intended for configuration values that remain relatively stable over time.

Return Value

This method returns void and provides no feedback about the success or failure of the operation. The absence of a return value means you cannot programmatically verify that the property was created or updated without making a subsequent call to gs.getProperty() to confirm the change.

If the operation fails due to insufficient permissions, database constraints, or system errors, the method will throw an exception that halts script execution. Wrap calls in try-catch blocks if you need to handle potential failures gracefully.

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

Business rules on the sys_properties table will fire, including before/after insert and update rules
Audit records are created if auditing is enabled on the sys_properties table
Property cache is immediately invalidated across all application nodes in the cluster
Database write operation occurs immediately, not deferred until transaction commit
Performance is significantly slower than property reads due to cache invalidation overhead
ACL evaluations occur based on the current user's permissions to the sys_properties table
Properties created programmatically do not appear in any specific category in the System Properties UI unless explicitly categorized

Parameters

Name	Type	Required	Description
key	string	Yes	The system property name. Must be unique across the instance. If the property already exists, its value and description will be updated.
value	string	Yes	The property value to set. All values are stored as strings regardless of input type. Empty strings and null values are both stored as empty strings.
description	string	Yes	Human-readable description of the property's purpose. Appears in the System Properties table and helps administrators understand the property's function.

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 creation for application configurationbasic

// Create a new application-specific property
// Check if it exists first to avoid overwriting
var propertyKey = 'my_app.email.notification.enabled';
var currentValue = gs.getProperty(propertyKey);

if (!currentValue) {
    gs.setProperty(
        propertyKey,
        'true',
        'Enable email notifications for My Application incidents'
    );
    gs.info('Created property: ' + propertyKey);
} else {
    gs.info('Property already exists with value: ' + currentValue);
}

// Verify the property was created
var newValue = gs.getProperty(propertyKey);
gs.info('Current property value: ' + newValue);

This example shows the safe way to create application properties by checking for existence first. Always verify property creation with a subsequent read.

Batch property creation during application setupintermediate

// Application setup script that creates multiple properties
var appProperties = {
    'incident.auto_assign.enabled': {
        value: 'false',
        description: 'Enable automatic assignment of incident tickets'
    },
    'incident.auto_assign.assignment_group': {
        value: 'IT Service Desk',
        description: 'Default assignment group for auto-assigned incidents'
    },
    'incident.sla.default_priority': {
        value: '3',
        description: 'Default priority for SLA calculations'
    }
};

// Create properties with error handling
for (var key in appProperties) {
    try {
        gs.setProperty(key, appProperties[key].value, appProperties[key].description);
        gs.info('Successfully created property: ' + key);
    } catch (e) {
        gs.error('Failed to create property ' + key + ': ' + e.message);
    }
}

Demonstrates batch property creation with proper error handling. This pattern is useful in application installers or setup scripts that need to configure multiple properties.

The classic mistake — using properties as runtime storageadvanced

// WRONG: Using properties for frequently changing data
// This will kill performance and flood the audit log
function updateUserSession(userId) {
    var sessionKey = 'user.session.' + userId;
    var timestamp = new GlideDateTime().toString();
    
    // This is terrible - creates a property for every user session
    gs.setProperty(sessionKey, timestamp, 'Last login time for user');
}

// RIGHT: Use appropriate storage for runtime data
function updateUserSession(userId) {
    var userGr = new GlideRecord('sys_user');
    if (userGr.get(userId)) {
        userGr.last_login_time = new GlideDateTime();
        userGr.update();
    }
}

Properties are for configuration, not runtime data storage. Using setProperty for frequently changing data creates performance problems and clutters the system with unnecessary properties.

Gotchas

Property keys are case-sensitive, so 'my.property' and 'My.Property' are treated as completely different properties.

All values are stored as strings regardless of input type — numbers, booleans, and objects are automatically converted.

The method can overwrite existing system properties without any warning, potentially breaking platform functionality.

Property cache invalidation happens immediately but may take a few seconds to propagate across all cluster nodes.

Properties created programmatically don't appear in any UI category unless you manually set the 'category' field in sys_properties.

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