Review Instance Changes in NOW SDK Apps

Someone can change your app on the instance while you work in the source: a colleague edits a Script Include in Studio, or a UI page is fixed on a form. ScriptSync notices those changes and lets you decide what happens to each one, so a deploy does not quietly undo them. This page covers the change check, accepting a change, keeping your source version, and pulling. For building and installing, see Deploy NOW SDK Apps.

Choose an Action

Accept can handle some changes that a regular Pull cannot, including supported edits to generated UI content and fields that need $override. It tells you when a change still needs a manual source edit.

How ScriptSync Knows What Changed

After every deploy or pull, ScriptSync keeps a copy of the app's records as they were on the instance, in the .snu folder of the project (ignored by git). Later it compares the instance with that copy. So the first deploy or pull to an instance sets the starting point, and changes are found from then on.

The NOW SDK App view in the ScriptSync sidebar lists the records that changed on the instance since then. When the helper is disconnected, the last result is marked cached; reconnect and refresh for a current check. Refresh (↻) checks the instance again. When the browser has no session for the instance, the view says so: click it to open the instance, log in if asked, and run /token.

The sidebar includes detected choice-list changes. Click a record to compare its last synced version on the left with the current instance version on the right.

Checking Before a Deploy

Before a deploy, ScriptSync checks whether the app changed on the instance since your last deploy or pull, for example because a colleague edited a Script Include in Studio. If it did, you see which records changed and choose:

• Pull first: bring those changes into your project, then deploy.
• Deploy anyway: overwrite them.

The check runs while the app builds. It compares the app's records on the instance with how they were after your last deploy or pull from this project, and with what you just built. You are only warned about changes the deploy would actually overwrite, field by field: a change you already pulled into your source does not count, and neither does saving a record without changing it. Records that exist only on the instance are normally left alone by a deploy; they are mentioned, not blocking. Choice lists are an exception: the SDK’s default format replaces the whole list, so adding a choice on the platform can also cause a deploy warning. The comparison includes added, edited and removed choices, including translations and dependent choices. With the SDK’s newer merge format, it warns only when the package would overwrite a changed choice. Line endings and trailing spaces do not count as a change; any other difference in a value does, including indentation and spaces inside a string.

If the check cannot run, for example because the session expired, ScriptSync tells you and deploys only when you choose Deploy without check.

Changes a Pull Cannot Bring In

Some changes cannot be pulled, because the ServiceNow SDK regenerates those records or fields from your source. The warning names the reason. Try Accept for supported source edits; copy the change into your source by hand if Accept cannot place it:

• Built from your UI source: HTML of a UI page built from src/client.
• Compiled from your server source: server modules from src/server.
• Its script calls a module function in your source: for example a business rule with script: myFunction; its script on the instance is generated.
• Regenerated from your source on every build: UI assets, images, UI messages and attachments.
• Marked @fluent-disable-sync in your source: definitions you excluded from pulls on purpose.
• Fields the SDK does not support: a changed field the Fluent API has no property for is also named, for example abort_action.

Accept a Change Made on the Instance (Beta)

In the NOW SDK App view, each record that changed on the instance has three actions:

• Click it to see what changed: the record after your last deploy or pull next to the instance version, field by field.

• Accept (✓) brings supported changes into your project:

  • records the ServiceNow SDK converts back (scripts, tables, choice lists and other supported artifacts) are pulled;
  • content generated from a source file, such as the HTML of a UI page built from src/client or a server module from src/server, is applied to that source file: the changed lines land in the one file that holds that text;
  • a field the SDK has no property for is added to the record's $override in your Fluent definition.

  The files change as normal edits, so you can review them in Source Control and undo them. A file that is open with unsaved changes keeps them: the edit is added, and saving is up to you. After an edit applied directly to source, ScriptSync builds the app and checks that the build now produces the instance version; only then does the change leave the list. When a change cannot be placed automatically (for example, bundled JavaScript), Accept tells you which field and why, and the change stays listed.

• Keep local version (right-click) acknowledges the instance change and keeps your source version. The next deploy applies your source version to records included in the package.

Accepting into generated source is in beta: review the edit before you deploy. Your next deploy will preserve the accepted change.

From Your Fluent Source

You can also work from the definitions in your .now.ts files. Right-click inside a definition, such as Table({...}), a column in its schema, Role({...}), UiPage({...}) or BusinessRule({...}), and choose:

• Open on Instance: opens the record that definition creates.
• Compare with Instance and Accept Instance Change (beta): shown when the file holds a definition that changed on the instance.

A definition that changed on the instance also shows it right above it, with the changed fields and Accept or Keep local version. A new definition gets its record ID at the next build, so build once before opening it.

Pull Instance Changes into Your Project

When someone changes the app on the instance, for example in Studio or on a form, pull those changes back into your Fluent source: right-click now.config.json and choose Pull instance changes into NOW SDK app (or run it from the Command Palette).

SN Utils downloads the app with your browser session, and the ServiceNow SDK in your project converts it into Fluent. The pull uses the same instance as deploy.

When your project is in a git repository and the files the pull changes have no uncommitted edits, the changes are applied right away. Review them in Source Control like any other change, or click Undo in the notification to put the project back as it was; the instance changes are then listed again.

When the project is not in git, or a file the pull would change has uncommitted edits, you review the changes first: a list shows every file that differs, with a diff button per file. Press Enter to copy the selected files into your project, or Escape to keep it as it is. When you leave files out, the instance changes stay listed in the NOW SDK App view until you pull the rest, deploy or choose Keep local version.

Good to know:

• The first pull writes out SDK defaults. A pull uses the same conversion as now-sdk transform, which also writes out default values (such as active: true) and record IDs the SDK keeps track of. After the first pull the source is stable, and later pulls only bring real changes.
• Deletions are not pulled. A record removed on the instance stays in your project; the notification tells you when that is the case. Remove it yourself if that is intended.
• Only the app's own records. Like now-sdk transform, a pull covers records in the application's scope.
• To pull from another instance, run Change NOW SDK app instance first.

From the Command Line or an AI Agent

snu sdk deploy and the snu_sdk_deploy MCP tool run the same check:

• E_INSTANCE_CHANGED: the deploy would overwrite changes made on the instance. The error lists each record with its fields and, when a pull cannot bring it in, the reason. Pull first (snu sdk pull), or add --force to overwrite them.
• E_CONFIRM_REQUIRED: the check could not run. Retry, or add --force to deploy without it. The result's instanceChecked says whether a deploy was checked.

snu sdk pull applies a pull when git can show and undo it; see From the Command Line or an AI Agent. Accept and Keep local version are available in the NOW SDK App view and from mapped Fluent definitions in the editor. They are not CLI or MCP actions yet.

Related

• Deploy NOW SDK Apps
• AI Agent Support