Update Set

What It Is

An Update Set is ServiceNow's change tracking and deployment mechanism that automatically captures configuration modifications as you make them and packages those changes for promotion between instances. When you create a business rule, modify a form, or add a field, ServiceNow writes those changes to update set records that can be exported as XML and imported into target environments. This solves the fundamental problem of maintaining configuration consistency across development, test, and production instances without manual recreation of every customization.

Update Sets live in the System Update Sets application and operate at the platform layer, sitting between the configuration interface and the underlying database tables. The system maintains two core tables: sys_update_set stores the container records, while sys_update_xml holds the actual change records as XML payloads. Every configuration change triggers the creation of update records that capture the before and after state of modified objects, along with dependency information needed for proper sequencing during deployment.

The data model relationship centers on the concept of trackable objects — any configuration element that extends sys_metadata gets automatically tracked when modified. This includes business rules, script includes, UI actions, form layouts, workflows, and hundreds of other configuration elements. The system maintains a registry of trackable tables and uses database triggers to intercept changes, serialize the affected records to XML, and store them in the active update set. Dependencies between objects are calculated using reference field analysis and table inheritance hierarchies.

You cannot function without Update Sets in any ServiceNow implementation that spans multiple instances — which means virtually every enterprise deployment. Without them, every business rule, form modification, workflow change, and script include would need manual recreation in each environment, making change control impossible and introducing massive risk of configuration drift. The business necessity becomes critical during major releases, emergency fixes, and routine deployments where dozens or hundreds of configuration changes need coordinated promotion. Organizations attempting to manage configurations manually across instances inevitably face data inconsistencies, broken integrations, and failed deployments.

System administrators own Update Set management strategy, policy, and instance-level configuration, while developers and application builders create and populate them through their daily configuration work. Platform owners establish governance around naming conventions, approval workflows, and promotion schedules. The relationship requires coordination since developers must work within active update sets configured by admins, and admins must understand the scope and impact of changes before approving deployments. In larger organizations, dedicated deployment managers often handle the actual promotion process while maintaining oversight of the entire pipeline.

Recent ServiceNow releases introduced significant improvements to Update Set handling, particularly around scoped application management and collision detection. Vancouver enhanced the preview process with better dependency analysis and conflict resolution, while Xanadu added improved rollback capabilities and more granular tracking for delegated development scenarios. The introduction of DevOps features in recent releases provides alternative deployment methods through CI/CD pipelines, but Update Sets remain the primary mechanism for most configuration changes and the fallback option when automated deployments encounter issues.

Where to Find and Configure It

Navigate to System Update Sets > Local Update Sets for the primary management interface where you create, configure, and track update sets on the current instance. Access System Update Sets > Retrieved Update Sets to view imported update sets awaiting preview and commit. Use System Update Sets > Update Sources to configure instance connections for direct remote retrieval of update sets between environments.

Within Studio, access update set controls through the application header where you can switch between update sets or create new ones scoped to your current application. App Engine Studio provides similar controls in the development environment section for citizen developers working on scoped applications. The sys_update_set and sys_update_xml tables provide direct access to the underlying records for troubleshooting and advanced management scenarios.

Scoped applications automatically create application-specific update sets that isolate changes within the application scope, while global update sets capture changes to platform-level configurations and cross-application modifications. Find the current active update set displayed in the system header's settings menu, and switch between available update sets using System Settings > Developer > Update Set Picker. The sys_update_version table tracks individual update records within update sets for detailed analysis and selective rollback operations.

How It Works Step by Step

Update Sets operate through a sophisticated change tracking system that intercepts configuration modifications at the database layer and serializes them into portable XML records. When you modify any trackable object, ServiceNow's metadata framework triggers update record creation that captures the complete state of the changed object along with dependency information. The system maintains a registry of all trackable tables and uses database triggers to ensure comprehensive change capture without requiring developer intervention.

The XML serialization process converts each configuration object into a standardized format that includes not only the field values but also metadata about the object type, scope, and relationships to other objects. During export, the system packages all related update records into a single XML file with proper sequencing based on dependency analysis. Import operations reverse this process, parsing the XML into temporary staging records that undergo collision detection and dependency validation before final commitment to the target instance's configuration tables.

The preview phase allows administrators to examine exactly what changes will be applied and resolve conflicts before permanent modification of the target instance. ServiceNow compares incoming changes against existing configurations, identifies conflicts, and provides resolution options including accepting incoming changes, keeping local modifications, or manual merge operations. Caching mechanisms optimize this process by maintaining dependency maps and change history to accelerate conflict detection and resolution.

The Execution Order

1. Configuration change occurs (business rule creation, form modification, etc.)
2. Database trigger fires on the affected metadata table
3. System checks if the table is trackable and an update set is active
4. Object gets serialized to XML including all field values and metadata
5. Dependencies are calculated based on reference fields and inheritance
6. Update record is created in sys_update_xml linked to the active update set
7. System updates dependency maps and change sequence ordering
8. Change tracking completes and normal system processing continues

// Create and activate a new update set programmatically
var updateSet = new GlideRecord('sys_update_set');
updateSet.initialize();
updateSet.name = 'INC-Enhancement-' + gs.nowDateTime();
updateSet.description = 'Incident management workflow improvements';
updateSet.application = gs.getCurrentApplicationId();
updateSet.state = 'build';
updateSet.is_default = false;
var updateSetSysId = updateSet.insert();

// Activate the new update set
var updateSetManager = new UpdateSetAPI();
updateSetManager.setCurrentUpdateSet(updateSetSysId);

// Verify activation
gs.info('Active update set: ' + gs.getProperty('glide.sys.update_set'));

// Track a specific object change
var tracker = new GlideUpdateManager2();
tracker.saveRecord('sys_script', businessRuleSysId);

Real-World Scenarios

Deploying Incident Workflow Changes Across Environments

Your organization needs to deploy a complex incident management enhancement that includes new business rules, modified forms, additional workflow activities, and updated UI actions across development, test, and production instances. The change involves multiple interdependent components that must be deployed atomically to maintain system integrity.

Create a new update set named INC-Workflow-Enhancement-v2.1 in development and make it active via System Update Sets > Local Update Sets. Configure all workflow modifications, business rules, and form changes while this update set remains active. Complete development work, mark the update set as Complete, export it as XML, import to test environment via System Update Sets > Retrieved Update Sets, preview for conflicts, commit changes, validate functionality, then repeat the process for production deployment.

Watch for dependency conflicts when workflow activities reference business rules or UI actions modified in the same update set — preview will catch these but resolution requires understanding the proper sequence. Form modifications can conflict with concurrent changes to the same forms, requiring manual merge of form sections. Test the complete workflow path in the test environment since workflow changes often have cascading effects not visible in the preview phase.

Managing Collision Resolution for Concurrent Development

Two development teams simultaneously modified the same business rule in separate update sets, and now both need deployment to production without losing either team's enhancements. The collision detection system flagged this conflict during preview, requiring manual resolution to merge both sets of changes.

Import the first update set and commit it normally to establish the baseline configuration in the target environment. Import the second update set containing the conflicting business rule, which will appear in Retrieved Update Sets with collision warnings. Click Preview Update Set to view the Update Set Preview Problems list. Select the conflicted business rule, choose Skip to ignore the incoming change, then manually edit the target business rule to incorporate both teams' modifications before committing the update set.

Pay close attention to the collision details screen which shows exact field-level differences between versions — script changes often conflict on white space or comments that aren't functionally significant. Document the manual merge process for audit purposes since the update set won't reflect the final resolved state. Consider implementing update set naming conventions that identify the developer and change scope to help predict potential conflicts before import.

Implementing Selective Rollback for Failed Deployment

A major update set deployment caused performance issues in production due to an inefficient business rule, requiring immediate rollback of specific components while preserving other successful changes from the same update set. Complete rollback would eliminate beneficial changes that are working correctly and don't need reverting.

Navigate to System Update Sets > Committed Update Sets and open the problematic update set record. Click View Update Records to access the sys_update_xml records within the update set. Locate the specific business rule causing issues by filtering on Type equals sys_script. Right-click the update record and select Revert to restore the previous version of just that business rule while leaving other update set changes intact.

The Classic Mistake

The classic scenario: production breaks, pressure mounts, and someone creates an update set directly in production to "just fix this one field quickly." They navigate to System Update Sets > Local Update Sets, create a new set called PROD_HOTFIX_USER_TABLE, and modify the User table directly. They add a new field, update some business rules, maybe tweak an ACL. The fix works immediately. Then they export the update set and try to "promote it backwards" to development and test environments to maintain consistency. This seems logical – after all, the change is now captured in an update set.

This approach fails catastrophically because update sets aren't designed for reverse promotion, and production changes create massive merge conflicts when legitimate development work tries to promote forward. The sys_update_xml records generated in production have different timestamps and source instance metadata, causing ServiceNow's collision detection to treat them as conflicting changes rather than the authoritative version. When the next legitimate development update set promotes forward, it either overwrites the production fix or creates preview errors that force manual resolution of "conflicts" that shouldn't exist.

// CORRECT: Emergency change in development first
// 1. Create hotfix update set in DEV
// 2. Make changes in DEV
// 3. Export and promote DEV -> TEST
// 4. Test and validate
// 5. Export and promote TEST -> PROD
// 6. If critical, skip TEST but never start in PROD

// Emergency Documentation:
// Update Set: HOTFIX_USER_FIELD_20240115
// Source: Development instance
// Target: Production (via TEST or direct)
// Reason: Critical user field missing validation
// Rollback plan: Exported baseline before changes

When to Use This vs Alternatives

Update sets are the correct choice for configuration changes that need to move between instances in a controlled, traceable manner. Use them for business rules, UI policies, form layouts, workflow modifications, and custom applications – anything that modifies the sys_metadata or configuration tables. Update sets provide atomic deployment, rollback capability, and collision detection that other mechanisms lack.

When Update Sets Are Correct

Choose update sets for any change that appears in System Update Sets > Preview Update Set when you modify it – this includes table schemas, client scripts, server scripts, and application files. Update sets excel at promoting complete features because they capture dependencies automatically and maintain referential integrity across related configuration elements. Export controls and remote update sets fail at dependency management, making update sets the only viable option for complex changes spanning multiple tables and applications.

When to Use Alternatives Instead

Use Export Controls for data migration when you need to move actual records (incidents, users, knowledge articles) rather than configuration. Choose Remote Update Sets only for one-way synchronization of simple configuration changes where you need real-time updates without manual export/import cycles. Update sets become unwieldy for data because they create massive XML files and don't handle record relationships properly across instances with different sys_ids.

When You Need Both Together

Large application deployments require update sets for configuration plus export controls for reference data and sample records. Deploy the update set first to create the table structure and business logic, then import the data using export controls to populate choice lists, default records, and template data. This sequence prevents import errors and ensures that business rules and data policies apply correctly to imported records during the data migration phase.

Platform Interactions & Side Effects

• Business Rules with When: before execute during update set commits, potentially modifying records being updated and creating additional sys_update_xml entries not captured in the original update set
• Update set operations write to sys_update_set, sys_update_xml, sys_remote_update_set, and sys_update_preview tables, with audit records in sys_audit for every modified configuration item
• Dictionary overrides and field-level security break when update sets contain table extensions that haven't been applied to the target instance's base system dictionary
• Email notifications triggered by workflow updates in update sets fire immediately upon commit, potentially sending emails before the complete application is functional
• Application scope changes force update set preview errors when moving scoped applications between instances with different scope configurations or missing dependencies
• Transform maps and data sources in update sets fail when target instances have different external system connections or missing MID server configurations
• Performance impact during large update set commits can lock configuration tables for several minutes, blocking concurrent administrative changes and user session updates
• Client script caching breaks temporarily after update set deployment, requiring users to refresh browsers or clear cache to see new form behaviors and validations
• Knowledge base articles and service catalog items in update sets lose their published state and require manual re-publishing in target instances
• Scheduled jobs and business rule conditions referencing gs.getProperty() values fail when system properties aren't included in update sets or have different values across instances

Debugging and Troubleshooting

Update set failures typically manifest as preview errors during import, missing functionality after deployment, or collision warnings that prevent clean promotion. Users report that new features aren't visible, forms display incorrectly, or business logic doesn't execute as expected. The most common symptom is successful update set import with no errors, but the expected changes simply don't appear in the target instance.

Check System Logs > All for entries containing "UpdateSet" or "Preview" during the import timeframe. Look for messages like "Skipped update, newer version exists" or "Preview problem: Missing dependent record." The sys_update_preview_problem table contains detailed collision and dependency information that doesn't appear in the UI. For performance issues, monitor System Diagnostics > Session Debug > Debug Security during update set operations to identify ACL conflicts preventing proper deployment.

Error messages like "Cannot read property of null" in business rules indicate missing reference records, while "Access Denied" during preview suggests insufficient ACL permissions for the importing user. The cryptic message "Update skipped - record not updated" means the target instance already has a newer version of the configuration item, typically from manual changes or competing update sets. Look for "java.lang.OutOfMemoryError" in application logs when importing massive update sets with thousands of configuration changes.

Diagnostic Checklist:

• Verify the importing user has admin role and security_admin if ACLs are included in the update set
• Check sys_update_preview_problem table for detailed collision information not visible in the preview UI
• Compare sys_updated_on timestamps between source and target instances for skipped records
• Validate application scope settings match between instances for scoped application updates
• Review System Properties > Update Sets for size limits and timeout configurations
• Test update set import in a development clone before attempting production deployment
• Clear browser cache and session state after deployment to ensure client-side changes are visible

Quick Reference

• Update sets larger than 100MB cause memory errors during import; split large deployments into multiple smaller update sets with clear dependencies
• The Default update set captures ALL configuration changes automatically; create specific named update sets to avoid accidentally promoting unrelated changes
• System properties, email accounts, and LDAP server configurations don't transfer in update sets – document these separately for manual configuration
• Update sets become "Complete" automatically after export and cannot be modified; clone completed update sets to add additional changes
• Rollback functionality only works if you export a baseline update set before making changes – ServiceNow doesn't create automatic backups
• Preview operations are read-only and can be run multiple times safely; commit operations are permanent and cannot be undone without a rollback update set
• Update sets respect ACL inheritance but ignore field-level encryption; encrypted field values appear in plain text within update set XML
• Remote update sets bypass preview entirely and commit immediately; use only for trusted sources with identical instance configurations
• Application scope restrictions prevent global update sets from modifying scoped application objects; scope changes require separate scoped update sets
• Dictionary changes in update sets trigger automatic table schema modifications during commit, potentially causing downtime for tables with millions of records