Deploy NOW SDK Apps

ScriptSync works with apps built with the ServiceNow SDK (NOW SDK, Fluent). It deploys your app: it builds and packs the app with the SDK in your project, then SN Utils installs it on the instance with the session you are already logged in with. And it pulls changes made on the instance back into your Fluent source. Review the result in Source Control, or preview it first when affected files have uncommitted edits. There is no separate SDK login or OAuth setup for build, deploy and pull.

What You Need

• SN Utils 10.2.5.0 or later in the browser, with the ScriptSync helper tab open.
• sn-scriptsync 4.9.8 or later in VS Code (or Cursor), or @snutils/snu 0.3.6 or later for agents and the command line.
• A NOW SDK project: a folder with now.config.json, with its dependencies installed (npm install). ScriptSync uses the now-sdk from the project itself and supports ServiceNow SDK 4.1 up to 4.x; it was tested with SDK 4.13 on a Zurich instance.
• The instance known to ScriptSync: approved in the helper tab and with a current session (run /token on the instance if needed).
• Permission to install applications on the instance (typically the admin role).
• A scope that matches the instance's vendor prefix, such as x_1234567_myapp. A project created with now-sdk init against the instance already has it.

Supported apps

ScriptSync deploys and pulls scoped custom applications. For these app types, keep using now-sdk install and now-sdk transform; ScriptSync tells you when a project is one of them:

• Configuration projects (type: "configuration" in now.config.json), which install into an update set.
• Apps installed as Store apps (installAs: "store" or hostedPlugins), and apps already installed on the instance from the ServiceNow Store or an app repository.
• Global-scope apps.

Deploy from VS Code

1. Press Ctrl+Alt+U (Ctrl+Cmd+U on macOS) in any file of the project. Or choose Deploy NOW SDK app to instance from the right-click menu of a project file or now.config.json, or click the app in the status bar and choose Deploy to instance.
2. The first time, pick the instance. After that the app deploys to and pulls from that instance; run Change NOW SDK app instance (also on the now.config.json right-click menu) to switch.
3. ScriptSync builds and packs the app. Progress and the SDK output appear in the sn-scriptsync: NOW SDK output panel.
4. Confirm the install in the ScriptSync helper tab.

When the install finishes, VS Code shows the result with a link to the rollback point.

While a file of a NOW SDK project is open, the status bar shows the app and its instance. Click it for Deploy, Pull, Change instance, the documentation and a feedback link. While a deploy or pull runs, it shows that too. The helper tab's title blinks while it waits for your confirmation.

The NOW SDK App View

When your workspace holds a NOW SDK project, the ScriptSync sidebar shows a NOW SDK App view for the project you are working in. At a glance it tells you:

• Which instance the app deploys to and pulls from (click to change).
• Whether someone changed the app on the instance since your last deploy or pull, with the records listed and a Pull button right there.
• Which files you edited since the last deploy, with a Deploy button; click a file to open it.
• When you last deployed and pulled.
• What is in the app: tables, columns, UI pages, scripts, flows, ACLs and more. Click one to open its definition in your source; the globe next to it opens it on the instance.

Warnings only appear when something needs attention, such as a helper tab that is not connected or an SDK version ScriptSync does not support. The toolbar has Deploy, Pull and Refresh; Refresh also checks the instance for changes.

Changes Made on the Instance

Before a deploy, ScriptSync checks whether the app changed on the instance since your last deploy or pull, and asks before overwriting those changes. If the check cannot run, for example because the session expired, you choose whether to deploy without it. Review Instance Changes in NOW SDK Apps explains the check, how to accept a change made on the instance into your source, and how to pull.

From the Command Line or an AI Agent

Everything also works from a terminal with the SN Utils CLI (@snutils/snu 0.3.6 or later), and from AI agents through its MCP tools snu_sdk_deploy and snu_sdk_pull. It runs through ScriptSync in VS Code or through the standalone snu serve bridge.

snu sdk deploy my-fluent-app          # build, check the instance, install after you confirm
snu sdk pull my-fluent-app            # bring changes made on the instance into the source
snu sdk pull my-fluent-app --dry-run  # only list what would change

Leave out the folder when the workspace holds one NOW SDK project. Without --instance, both commands use the instance the app was last deployed to or pulled from, the same one the editor uses.

They behave like the editor commands, with flags instead of dialogs:

• snu sdk deploy stops with E_INSTANCE_CHANGED and lists the records when the app changed on the instance since the last deploy or pull. Pull first, or add --force to overwrite them. When the check itself cannot run, it stops with E_CONFIRM_REQUIRED; retry, or add --force to deploy without the check. You still confirm every install in the ScriptSync helper tab; agents cannot skip that.
• snu sdk pull applies the changes when your project is in git and the affected files have no uncommitted edits, so you review with git diff and undo with git checkout. Otherwise it stops with E_CONFIRM_REQUIRED and lists the files; commit first, or add --force.

A deploy or pull started by an agent is blocked while agents are paused in the helper tab. A deploy also needs the Create Artifacts permission for the instance.

The Confirmation

Every deploy shows a dialog in the ScriptSync helper tab with the target instance, whether it installs a new app or updates the installed version, and the app's scope, version, package size and number of flows to activate. Nothing is installed until you click Install.

Before that dialog, SN Utils checks the instance: a deploy over an app installed from the Store, or into a scope another app already uses, is refused with an explanation.

If the instance is tagged as production in SN Utils, you type the instance name before Install is enabled.

Only one deploy runs at a time. A second deploy that arrives while one is waiting or installing is refused until the first has finished.

What a Deploy Does

1. Runs now-sdk build and now-sdk pack in your project.
2. Uploads the package to the instance with your browser session and waits for the install to finish.
3. Activates the app's flows, subflows and actions, like now-sdk install does.
4. Reports the result, with links to the rollback point and the install's execution tracker.

Records included in the package overwrite their corresponding records on the instance. Accept or pull any changes you want to preserve before deploying. Records that exist only on the instance are normally left alone. Choice lists need special care: the SDK’s default format replaces the whole list, including choices added on the platform. ScriptSync includes those changes in its pre-deploy check.

Results

When the Result Is Unknown

If no result arrives, for example because the browser or VS Code closed during the install, the install may still have finished on the instance. Before you deploy again:

1. Open System Applications > All Available Applications > All on the instance and check the app's version and install date.
2. Open the execution tracker from the ScriptSync helper tab's activity log to see how the install ended.
3. To undo an install, open its rollback context (linked in the result and in the activity log).

Pull Instance Changes

To bring changes made on the instance into your Fluent source, right-click now.config.json and choose Pull instance changes into NOW SDK app. See Review Instance Changes in NOW SDK Apps for how a pull is applied, reviewed and undone.

What Still Needs the SDK Login

Build, deploy and pull need no SDK login. Other SDK commands still call the instance with the SDK's own credentials:

• now-sdk dependencies, to download type definitions.
• now-sdk transform options that pick records or update sets (--table, --updateSet).
• now-sdk init --from, now-sdk download and the CI/CD commands.

Set those up with now-sdk auth as described in the ServiceNow SDK documentation.

Related

• Review Instance Changes in NOW SDK Apps
• ScriptSync (VS Code)
• AI Agent Support