System Properties and Configuration Management

Introduction

System Properties are ServiceNow's key-value store for instance configuration. They allow administrators and developers to externalize configuration values — API endpoints, feature flags, timeout thresholds, email addresses — out of hardcoded scripts and into manageable records that can be changed without code deployments.

---

What Are System Properties?

System Properties (sys_properties) are simple records with:

• Name: A dot-notation key (e.g., myapp.integration.api_url)
• Value: The stored value
• Type: String, Integer, Boolean, Password, etc.
• Description: What this property controls
• Private: Hides the value in UI (for credentials)

---

Reading and Writing Properties

Reading in Server-Side Scripts

// Read a string property
var apiUrl = gs.getProperty('myapp.integration.api_url');

// Read with a default value (if property doesn't exist)
var timeout = gs.getProperty('myapp.timeout', '30');

// Read a boolean property
var featureEnabled = gs.getProperty('myapp.new_feature.enabled') === 'true';

// Read an integer property
var maxRetries = parseInt(gs.getProperty('myapp.max_retries', '3'));

Writing Properties Programmatically

// Create or update a property
gs.setProperty('myapp.last_sync', new GlideDateTime().toString());

Reading in Client Scripts (via GlideAjax)

System Properties are not directly accessible in Client Scripts for security reasons. Use a GlideAjax Script Include if you need a property value on the client side.

---

Property Naming Conventions

Use reverse-domain notation to namespace your properties and avoid collisions:

[company_prefix].[application].[module].[property_name]

Examples:
  acme.incident.auto_close.enabled
  acme.incident.auto_close.days
  acme.integrations.jira.base_url
  acme.integrations.jira.project_key
  acme.hr.onboarding.manager_notification.enabled

Avoid generic names like timeout or api_url that will conflict with other applications.

---

Creating a Property Category Page

For custom applications, create a dedicated System Properties page so admins can manage your app's settings in one place:

System Properties > Categories > New

• Category: Your application name (e.g., ACME Incident Manager)
• Properties: List the sys_properties names to display
• Module link: Optionally add to the Application Navigator

This creates a form-style UI showing all your properties with descriptions, making them discoverable without knowing exact property names.

---

Property Types

Type	Use Case
string	URLs, names, codes
integer	Numeric thresholds, timeouts, limits
boolean	Feature flags (use 'true'/'false' strings)
choice	Dropdown selection
password2	Encrypted credentials (never use password type)
date	Date configuration values

For sensitive values like API keys, always use password2 type — values are encrypted at rest and masked in the UI.

---

Feature Flags Pattern

System Properties are ideal for feature flags — enabling or disabling functionality without code changes:

// In a Business Rule
if (gs.getProperty('acme.incident.auto_assign.enabled') === 'true') {
    // Auto-assignment logic
    var assignee = new IncidentAutoAssigner(current).getAssignee();
    current.setValue('assigned_to', assignee);
}

To disable the feature in production: change the property value to false. No code change, no Update Set needed.

---

Including Properties in Update Sets

System Properties are not automatically captured in Update Sets. You must manually add them:

On the sys_property record → Right-click the header → Add to Update Set

This is a common deployment gap — developers change a property for development and forget it won't follow to production. Include a property checklist in your deployment runbook.

---

Best Practices

• Use namespaced dot-notation for all custom properties
• Always provide a meaningful Description on every property
• Use password2 type for any sensitive values
• Create a Property Category page for each custom application
• Manually add changed properties to Update Sets before deployment
• Document default values in the Description field
• Audit unused properties annually and remove stale ones
• Never hardcode values in scripts that could change between environments

---

Conclusion

System Properties are one of the simplest and most powerful tools for building maintainable ServiceNow applications. Externalizing configuration makes your code environment-agnostic, enables feature flags, and gives administrators control without requiring code changes. Adopt a consistent naming convention from day one, and your properties will remain organized as your instance grows.