ServiceNow Update Sets: A Complete Guide to Clean Migrations

An update set records the configuration changes you make on one ServiceNow instance so you can move them to another. The idea is simple. The problems come from what update sets do not capture, from changes recorded in the wrong set, and from committing sets in the wrong order.

This guide walks through the whole path, from creating an update set in development to committing it in production.

How update sets work

When you change a tracked record, ServiceNow writes a Customer Update record to the sys_update_xml table and attaches it to your current update set. The record holds an XML snapshot of the whole configuration record, not a diff.

Two consequences follow:

• The last captured version of a record wins. If two developers edit the same business rule in different update sets, the set committed second overwrites the first.
• A table is only tracked when its dictionary entry has the update_synch attribute. Most configuration tables have it. Data tables do not.

What update sets capture and what they miss

Captured:

• Business rules, script includes, client scripts, UI policies, and UI actions
• Tables, fields, and dictionary changes
• Form and list layouts, views, and related lists
• Flows, catalog items, variables, and notifications
• Access controls and roles

Not captured:

• Task records such as incidents, changes, and requests
• Users, groups, and group memberships
• Configuration items and other CMDB data
• Most records in data lookup and custom data tables

If a flow assigns work to a group, the flow moves but the group does not. The flow then points at a sys_id that does not exist on the target. Create the group on the target with the same sys_id by exporting it as XML from the source and importing it, or load it through an import set.

Create and name update sets

Create one update set per story or defect, in the application scope where the work lives. An update set belongs to a single scope, so work that touches two scopes needs two sets.

Use a name that sorts well and explains itself:

STRY0012345 - Incident - Auto-assign by category - v1

Put the story number first, then the area, a short description, and a version. When you need a fix after the first set is complete, create v2 instead of reopening v1.

Never do real work in the Default update set. It exists to catch changes made when nobody picked a set, and it should not be moved between instances.

Check which update set you are in

Most misplaced changes happen because a developer switched application scope and the update set picker changed with it. Confirm the picker before you save anything.

To review what a set contains before you complete it, run this in Scripts - Background on a development instance:

var setName = 'STRY0012345 - Incident - Auto-assign by category - v1';

var update = new GlideRecord('sys_update_xml');
update.addQuery('update_set.name', setName);
update.orderBy('type');
update.query();

gs.info(update.getRowCount() + ' updates in "' + setName + '"');
while (update.next()) {
  gs.info(update.getValue('type') + ' | ' + update.getValue('target_name') +
    ' | ' + update.getValue('sys_created_by'));
}

Look for updates you did not expect, such as a form layout you opened by accident, and for updates made by someone else. See the GlideRecord query performance guide for more on writing queries like this one.

Add a record that was not captured

Sometimes you need to carry a single data record, such as a system property value or a lookup row, inside an update set. Open the record, then run this with its table and sys_id:

var record = new GlideRecord('sys_properties');
if (record.get('name', 'x_acme.feature.enabled')) {
  new GlideUpdateManager2().saveRecord(record);
  gs.info('Added ' + record.getDisplayValue() + ' to the current update set');
}

Use this sparingly. It suits a handful of supporting records. It is the wrong tool for bulk data.

Batch related update sets

A release usually contains many update sets. Committing them one at a time, in the right order, is slow and easy to get wrong.

Use a batch instead. Create a parent update set for the release and set the Parent field on each child. On the target instance you preview and commit the parent, and ServiceNow processes every child in one operation and resolves the order of updates to the same record by timestamp.

Batches are a better choice than merging. A merge produces one new set and loses the link between each change and its story. A batch keeps every child intact, which makes it possible to pull one story out of a release.

Move the update set

1. On the source instance, set the update set State to Complete.
2. On the target instance, open System Update Sets > Update Sources and select Retrieve Completed Update Sets. If the instances cannot connect, export the set to XML on the source and use Import Update Set from XML on the target.
3. Open the set under Retrieved Update Sets.

Move sets through every environment in the same order. A set that skipped test should not reach production.

Preview and resolve problems

Select Preview Update Set. The preview compares each update with the target and reports problems. Do not commit until every problem has a decision.

Common preview problems:

Accept remote update applies your version over the target. Skip remote update leaves the target as it is. Decide per record and write the reason in the update set description, because the next person to investigate a defect will ask.

Commit and verify

Select Commit Update Set. When it finishes:

• Open the commit log and check for warnings and errors.
• Run your smoke tests. An ATF regression suite makes this repeatable.
• Create any data records the change depends on.

Back out with care

Back Out reverses a committed update set by restoring earlier versions of each record. It also deletes tables and fields that the set created, along with their data. Later update sets that changed the same records make a back-out unreliable.

In production, a forward fix in a new update set is usually safer than a back-out. Keep back-out for a change you committed minutes ago that nothing else depends on.

A short checklist

• One update set per story, in the correct scope
• Nothing in Default
• Review the contents before marking the set Complete
• Never reopen a completed set; create the next version
• Group a release with a batch, not a merge
• Preview, resolve every problem, then commit
• Record why you accepted or skipped each collision
• Prefer a forward fix to a back-out

Update sets also affect upgrades, because every customised record becomes a candidate for the skipped list. The upgrade skipped changes checklist covers that side. For ready-made examples to put in your next update set, browse the script library.