jsn / ServiceNow, simplified.

THE JSN HANDBOOK

Update sets and transfers

Transfer update sets between instances and read compact update-set diffs.

Intended write context

Reads have no automatic context banner and make no automatic user, scope or update-set context requests. Inspect context explicitly:

jsn --profile dev auth status --context
jsn --profile dev auth status --context --local --json

--context selects one profile, defaulting to the active profile. The existing all-profile status output is unchanged without this option. --local makes zero requests and never reports live context as verified. Domain output distinguishes the requested header from effective domain verification.

Bots must supply independently intended scope and capture set before customization:

jsn --profile dev includes create -f name=TaskHelper --expect-scope x_example_app --expect-update-set "Task feature" --json

Use the scope, application name or sys_id and update-set name or sys_id from the task, not values copied from the current preferences. Names must resolve uniquely. Unknown, ambiguous, incomplete, completed, mismatched or unreadable context blocks before mutation. Fresh preferences and effective session picker selections must agree. Nothing automatically switches context. Select explicitly with scopes set or updatesets set and retry. --force cannot bypass intent or mismatch checks. Global + Default still requires separate approval for the exact operation. Human interactive use can confirm fresh context when expectations were omitted.

For a task directory, explicitly write .servicenow/config.json:

{
  "write_context": {
    "profile": "dev",
    "instance_url": "https://example.service-now.com",
    "scope": "x_example_app",
    "update_set": "Task feature"
  }
}

These are illustrative task-owned values, not discovered defaults. CLI expectation flags override individual saved fields. A present local binding must exactly match the selected profile and instance URL, even when flags override its values. Global config never supplies write expectations, and normal configuration saves never promote these task-local expectations into global settings.

Ordinary ticket/data edits do not require capture context. Generic records and table factories classify customization through sys_db_object ancestry to sys_metadata, not command spelling. Unreadable ancestry refuses classification. Resolved action/flow targets and generic metadata record targets must match the verified intended scope before mutation. Explicit metadata sys_scope payloads cannot redirect writes; bulk updates preflight every selected target. Transaction scope flags are capability-declared. scopes create --scope names the new scope, not the transaction scope. Raw mutation APIs and eval conservatively require customization context. Operational metadata exemptions cover identity/membership administration, approvals, ATF runs, attachments, MID runtime operations, catalog ordering, Store installation, domain selection, and flow test/lock release. Explicit scope selection and update-set creation/selection/import/preview/commit/reopen keep their own safety gates. Scope creation is customization and is not exempt.

Successful JSON write envelopes include context.mutation, reusable with --get. Interactive writes show one compact context line from that same guard result. Quiet output remains data-only. Context checks supplement, not replace, command confirmations, read-only profiles and write-back verification.

Domain limitation

--expect-domain expresses intent but currently refuses customization writes. Configured domain headers and profiles known to use domain separation also refuse. The SDK propagates X-Now-Domain; this does not prove effective server selection. No verified provider contract connects that header to every customization transport, so domain-scoped customization remains unsupported rather than silently trusted. Ordinary domain-header reads/data edits remain available. No live domain mutation semantics were verified by this change.

Transfer an update set

Export without changing the source set's state or your selected capture context:

jsn --profile source updatesets export "Digital Helpdesk 0.1.77"
# In a terminal: Digital-Helpdesk-0.1.77.xml in the current directory.
jsn --profile source updatesets export "Digital Helpdesk 0.1.77" --out-dir ./exports
jsn --profile source updatesets export "Digital Helpdesk 0.1.77" --stdout > transfer.xml

Piped output remains raw XML. --out FILE selects an exact filename; --out-dir selects a directory that already exists. Export refuses to overwrite a file. Explicit JSON output without a file option retains the XML in its data envelope.

Inspect before loading:

jsn updatesets import transfer.xml --dry-run --json
jsn --profile target updatesets import transfer.xml --yes --json

The dry run is entirely local: it lists members with target names and actions, primary table counts, and subsidiary payload operations such as translation or flow cleanup. An omitted payload action is labeled platform_default rather than guessed. Imports support one retrieved set per file, up to 50 MiB, and require an admin session with native XML upload access. Without --yes, a terminal prompts; noninteractive calls return a confirmation-required error with a rerun command. Normal target selection (--profile / --instance) and read-only guards apply.

Successful import verifies the loaded set and every member ID/name/action. It does not apply the changes: the set is left loaded and uncommitted so the target can be previewed and reviewed first. Existing retrieved sets or member IDs cause refusal before upload. A timeout or failed verification may mean partial loading; inspect Retrieved Update Sets before retrying. The command does not silently replace an existing set, rename one, convert it to a local set, or change its state, and it refuses --name, --local, and --state rather than quietly ignoring them.

Preview, inspect the problems a human must decide, then commit:

jsn --profile target updatesets preview "Digital Helpdesk 0.1.77" --yes
jsn --profile target updatesets problems "Digital Helpdesk 0.1.77"
jsn --profile target updatesets commit "Digital Helpdesk 0.1.77" --yes

preview and commit run the platform's own steps through the CICD Update Set API (sn_cicd), which needs the CICD plugin and the sn_cicd.sys_ci_automation role. If that API is unavailable, jsn reports it and starts nothing; use System Update Sets > Retrieved Update Sets instead. Both commands follow the platform progress tracker (--timeout seconds, default 600) and then read the retrieved set back: preview must show previewed, commit must show committed. A successful call whose state does not match is reported as an error, not assumed.

problems is read-only. It lists unresolved preview problems with their description, missing item/table, and available actions; --include-resolved also shows rows a human already accepted or skipped. jsn never accepts, skips, or ignores a problem, and commit refuses while any problem is unresolved. It also refuses when the problem read reaches its 500-row bound, because a resolved sample does not prove that unread problems are resolved. Review and commit such sets in ServiceNow. Resolve problems in ServiceNow, rerun preview, then commit. A commit resolves the local update set it created through the retrieved record's update_set reference, falling back to a name lookup only when that reference is absent; an ambiguous or missing local copy is reported, never guessed.

Neither command changes the selected update set or scope.

Reopen a complete or ignored local update set explicitly:

jsn --profile source updatesets reopen "Digital Helpdesk 0.1.77"

This verifies in progress after the write and leaves selection unchanged. It does not accept committed sets. Export and import never reopen or complete sets.

Cross-instance update-set diff

jsn updatesets diff --source pdi --target vendor
jsn updatesets diff --source pdi --target vendor --from 2w --json
jsn updatesets diff --source pdi --target vendor --from 2026-10-01
jsn updatesets diff --source pdi --target vendor --get data.sets

--source and --target are independent configured profiles; the active profile is not changed. --from is a UTC date window, not a profile: default 2w, relative positive days/weeks (14d), or an exact calendar date. Selection is currently complete local source sets with sys_updated_on >= cutoff. It does not reconstruct completion transitions. Targets are searched across all dates.

Identity follows the existing export/import model: sys_remote_update_set.remote_sys_id identifies the original local sys_update_set.sys_id. Never match on name. Multiple retrieved candidates for one origin are Unknown, even when names agree. A committed retrieved candidate is Matching only when count-verified sys_update_xml captures joined by source update_set and target remote_update_set have the same unique artifact name, action, and exact payload. Envelope capture IDs, set references, timestamps and updater metadata are not compared. Payload XML is not normalized: representation differences conservatively report Different. This is captured-content evidence, not current-record comparison, preview, dependency analysis or deployment readiness.

Machine statuses remain Matching, Missing (only with complete inventories), Retrieved not committed, Different and Unknown. Default human output labels these Committed, matching, Missing in target, Loaded, not committed, Content differs and Unable to verify. Each named batch shows its base first, with children indented beneath parents; standalone sets have their own heading. Names are preserved exactly. Older and incomplete members show Context only (source state) and do not contribute to the status-count footer. Different sets list only changed artifact names and reasons; Unknown sets show one reason and a next step. The short shared note describes the selection window and captured-content boundary once.

--verbose retains full per-set evidence, IDs, source states, capture counts and coverage errors. JSON and --get retain the same statuses, identities and evidence regardless of verbosity. Base is derived from the oldest observable parent ancestor, not a guessed base field. Cycles and unreadable ancestry remain visible without unbounded traversal. “No selected sets” appears only after a complete source selection; unreadable selection explicitly leaves absence unestablished. The command requires no default profile and suppresses the unrelated active-profile context header.

Operational bounds: each table query uses at most 20 pages of 200 rows, a provider Stats count before and after, stable sys_id ordering, unique identities, strict response arrays and required fields. Short pages continue until the count is met. ACL errors, omitted fields, changing counts and budgets retain error/partial coverage rather than implying absence. These reads are not an atomic snapshot: same-count concurrent changes remain possible. Source hierarchy and the all-dates target inventory can exceed the budget; inspect coverage before using the report. No instance-record writes or eval occur; ordinary SDK authentication refresh/bootstrap remains permitted.

The fixture test uses the real CLI with two distinct profile identities and a local HTTP server; no live ServiceNow verification or live fixture creation is claimed.