jsn / ServiceNow, simplified.

THE JSN HANDBOOK

Records and record engines

Watch records, understand the record-engine contract and batch SDK reads without changing unrelated behavior.

Watching a ServiceNow record

jsn records watch streams changes to one record through ServiceNow's Asynchronous Message Bus (AMB) record watcher, instead of polling the table with repeated reads.

jsn records watch --table incident --sys-id 0123456789abcdef0123456789abcdef --timeout 300 --json
jsn records watch --table incident --identifier INC0010001 --identifier-field number --max-events 1 --json

Use it when a person asks an agent to track an incident, change, task or other record: "tell me when this changes", "watch this", "let me know when it is assigned". You do not need to know the transport name — record watching is the right tool for "keep an eye on this record".

What it emits

One compact JSON object per line (newline-delimited JSON) when the output is JSON — which --json requests and a pipe selects automatically:

{"type":"connecting","table":"incident","sys_id":"70d5…","channel":"/rw/default/incident/…"}
{"type":"subscribed","channel":"/rw/default/incident/…","session_status":"session.logged.in"}
{"type":"record_change","channel":"/rw/default/incident/…","table":"incident","sys_id":"70d5…","operation":"updated","received_at":"2026-11-04T18:00:45.348Z","action":"update","display_value":"INC0010004","event_id":"b836…","record":{"short_description":{"display_value":"probe second update","value":"probe second update"},"sys_updated_by":{"display_value":"admin","value":"admin"},"sys_mod_count":{"display_value":"2","value":"2"},"sys_updated_on":{"display_value":"2026-11-04 10:00:45","value":"2026-11-04 18:00:45"}}}
{"type":"watch_summary","table":"incident","sys_id":"70d5…","channel":"/rw/default/incident/…","reason":"max_events","events":1,"gaps":0,"reconnects":0,"complete":true,"started_at":"…","ended_at":"…","duration_ms":9000,"last_event_at":"2026-11-04T18:00:45.348Z"}

In a terminal (or with --format styled) each event becomes one line naming the changed fields, for example 2026-11-04T18:00:45.348Z incident INC0010004 updated — short_description: probe second update.

type values:

type meaning
connecting / subscribed / unsubscribed connection status
record_change a change notification for the watched record
gap the connection dropped; observation was interrupted
reconnected re-subscribed after a gap (may_have_missed_events: true)
watch_summary final line: reason, counts, duration, complete

operation is created, updated, deleted, changed or unknown. The action field keeps the platform's raw word (update, insert, …).

record is the platform's record-watcher payload: a map of field name to {value, display_value} for the fields that changed, plus sys_* audit fields (sys_updated_on, sys_mod_count, sys_updated_by, …). A live instance does not send a changes array, and it does not put table or sys_id in the notification; jsn fills those from the subscription, which is why a single-record watch is always scoped by sys_id=<id>. changes is normalized if an instance ever sends it, but the current platform shape is record.

The notification carries current values only. There is no previous value in it, so output never invents a before → after transition.

state.record (with --state always) is the Table API's display_value=all shape — again a map of field name to {value, display_value} — not a flat record. With the default --state auto, a record-watcher notification already carries record, so no follow-up read happens. The notification and the state read are always distinct: record is what the event said, state.record is a later read with source: "fetched". A failed read sets state: null and state_error; it never rewrites the event.

Bounds and cancellation

  • --timeout <seconds> stops after a bounded window (default 0, until interrupted). The exit status is 0; the summary's reason is timeout.
  • --max-events <n> stops after n change events (reason: "max_events").
  • Ctrl+C (SIGINT/SIGTERM) unsubscribes, disconnects and prints the summary with reason: "cancelled".

Agents should schedule observation as repeated bounded runs (for example a 60–300 second window per check) rather than holding a connection forever. Scheduling and telling the user belong to the calling agent, not to jsn.

Reconnects and gaps

Record watchers are best effort delivery, not a durable stream. If the connection drops, jsn re-subscribes with backoff and reports one gap event, then a reconnected event; watch_summary reports complete: false. Events sent while disconnected are not replayed, so do not treat the stream as a complete history. Use a table query for the current state after a gap. --no-reconnect turns a drop into a hard failure instead of a gap.

Authentication and access

AMB authorizes like a browser session: it needs the session cookies and X-UserToken of a logged-in UI session, not a bearer or Basic header alone. jsn supplies that from a browser-session (gck) profile, or by warming a UI session for a basic/OAuth profile.

  • Recommended: jsn auth login --browser, then --profile <name>.
  • A bearer-token-only identity, an SSO instance that refuses the session login flow, or an instance with no /amb endpoint fails with an actionable error and recovery hint rather than retrying.
  • The subscription respects the authenticated user's ACLs: an inaccessible or missing record fails with not_found before any subscription is opened.
  • Watching is read-only and works on read-only profiles. It declares no mutation capability and requires no update set.
  • If the session expires mid-watch, the run ends with auth_error and reauthentication guidance instead of retrying a dead cookie. Events during that window were not observed; start a new watch after reauthenticating.

Supported versions and restrictions

  • Record watchers exist on current ServiceNow releases; AMB is a platform service that administrators may restrict. If /amb is disabled or proxied away, the command reports AMB endpoint not found (HTTP 404).
  • One record per invocation in this release. Filtered table subscriptions are not exposed yet — the channel query is sys_id=<id> — until table-level access behavior is validated on a live instance.

Verification status

Live-verified on example.service-now.com on 2026-11-04 with an admin OAuth profile, watching one incident:

  • /amb/handshake returned 200 with a clientId and glide.session.status: session.logged.in; the cookies and X-UserToken from the warmed OAuth session were accepted.
  • /meta/subscribe acknowledged the /rw/default/incident/<base64> channel with successful: true.
  • A save made in a separate UI session was delivered as a record_change within milliseconds, with the record map described above.
  • --state always fetched the record after the event; --state auto did not (the notification already had detail).
  • SIGINT during a watch unsubscribed, disconnected, and printed watch_summary with reason: "cancelled" and exit status 0.

Still unverified: ACL/role denial (the only available profile is an admin, and admins bypass record ACLs), create and delete notification payloads, reconnect/gap behavior against a real dropped connection, and filtered table-level subscriptions. Unit and mock coverage lives in cli/test/amb.test.js, cli/test/record-watch.test.js and cli/test/records-watch.test.js; the opt-in live harness is cli/test/amb-live.test.js.

Records engine compatibility contract

Audit for #313, prerequisite to #314–#321. Baseline: origin/main at a3b0e6f. This contract precedes implementation and does not declare those issues complete.

Current implementations

Entry point Implementation and transport Compatibility requirements
records list/get/create/update/delete src/commands/records.js; SDK list, create, update, delete, aggregateCount, attachment methods Arbitrary/custom tables; required table; columns/c/fields aliases; list query, limit=20, offset=0, counts with profile override; get attachments; JSON/file/stdin/repeated-field payloads; derived-field warnings and strict write-back verification
incidents/inc, changes/chg, requests/req, tasks/task src/commands/_ticket.js via four modules; requests adds catalog helpers Preserve tables incident/change_request/sc_req_item/sc_task, number identifiers, aliases, list sorting/pagination, create description/priority shortcuts, breadcrumbs and required short_description
tickets/ticket src/commands/tickets.js; separate CRUD on task Preserve distinct task table, list shape and show summary; migrate alongside ticket factory without changing aliases
Simple specialized commands src/commands/_simple.js delegates to _generic.js; other modules also use factory Preserve every name/alias/default column/readOnly flag, optional resolver, showFields, onShow, summaries, breadcrumbs, extraQuery and scopeValidation hooks
Specialized rich commands flows/actions/catalog/CMDB/users and others have custom implementations Do not replace specialized operations wholesale; shared resolver changes require existing regression suite
Form views src/commands/forms.js independently reads views, sections, elements No automatic form/related-list retrieval in current generic get or ticket show. Preserve generic presentation; form-aware presentation belongs to specialized views

Observable data and calls

Generic get currently uses display=true; specialized show uses display=all. List commands request all but usually project display strings with formatRecordForDisplay. records/ticket lists expose table/count/columns/records, pagination and instance context; factory lists omit pagination today. Selected records carry _context. Preserve defaults and existing envelope/get extraction; add explicit raw/display/both options rather than silently changing defaults. Do not stringify raw reference objects when both is requested.

Current shared resolver selects 32-hex ids by sys_id and other values by the human field, requests one row and returns it without ambiguity checking. Generic get independently queries sys_id. Generic update/delete send supplied ids straight to SDK. The new resolver must replace these unsafe differences.

Interactive generic lists, ticket lists and factory lists use distinct picker rules and cancellation/empty behavior. Preserve those rules in this migration; reuse in-process transport/parameter functions underneath the existing UI. Keep ordinary get to one table read where resolution can return the record. Mutation id resolution may add bounded reads before a write; never substitute subprocess invocations. List counts remain best effort and honor opt-outs.

Identifier contract for the new engine

  1. Explicit identifier field wins. --sys-id means sys_id even for legacy or nonhex values. --identifier with --identifier-field selects any safe field.
  2. Specialized commands preserve their configured human-field precedence for non-32-hex identifiers; exact sys_id is attempted if no human match. Full 32-hex values retain sys_id precedence. Explicit field selection resolves a collision in either direction.
  3. Every lookup requests at most two records. Exact zero matches may fall back to sys_id prefix then suffix; partial matching applies only to ids, never human fields. Zero and multiple results fail, including duplicate exact ids.
  4. Never select the first ambiguous result or proceed to write. Errors identify table, lookup mode, field, match count/lower bound and actionable next steps.
  5. Validate identifiers and field/table names before encoded queries. Preserve the safe-exact-match boundary and always unwrap raw ids before mutations.

Safety and extension boundaries

Middleware capability registry remains the source for read-only/instance and mutation safeguards. SDK authentication/recovery stays in-process. Keep delete confirmation, scope guards and write-back checks in their current order. New engine functions accept hooks for table-specific policy; they cannot bypass handlers or the registry. Coordinate any Global + Default work with #310.

Declarative profiles should own actual table/aliases/defaults, not a second help-only registry. Function hooks remain code. Discovery must derive from those same definitions. Related/essential data is additive JSON, never stdout console prose (UI policy actions currently print console prose and must migrate). Batch transport is optional, validates read-only same-instance subrequests, maps responses/errors by id and falls back only when batch is unsupported. Dynamic metadata and counts must report ACL/coverage uncertainty, inherit safely, cache within an invocation, and avoid eager supplementary record retrieval.

Verification and migration gates

Existing contracts: test/records.test.js, test/tickets.test.js, test/resolve-record.test.js, test/users.test.js, test/inspect.test.js, test/field-pairs.test.js, test/usability-output-contract.test.js, test/usability-safety-group-mutations.test.js, test/capabilities.test.js, test/mutations.test.js and test/records-rest-help.test.js. Existing resolver tests assert limit=1 and must deliberately change to 2 with ambiguity regression proof. Most are structure/stub tests, so add real CLI/local HTTP fixtures for generic, ticket and factory operations, custom/legacy ids, references, output modes, ambiguity/no matches, selected profiles, mutation blocking and exact HTTP counts. No live instance writes. Run lint/full suite and verify skill local docs fixture; inspect evidence and cleanup. Batch, inherited metadata, related counts and essential data each need independent behavior/fallback/error/call-count tests.

The user has explicitly approved keeping the existing generic get presentation. Form-aware presentation belongs to specialized views. New metadata APIs and explicit opt-in operations must preserve that boundary.

Optional SDK batch reads

SDKClient.batch(requests, options) is an explicit transport for independent, read-only calls to the selected instance. Ordinary SDK/record commands stay unbatched. This follows the compatibility audit's initial read-only batch scope; writes continue through normal SDK methods and their safety/history contracts.

const output = await sdk.batch([
  { id: 'incident', url: '/api/now/table/incident?sysparm_limit=1' },
  { id: 'task', method: 'GET', url: '/api/now/table/task?sysparm_limit=1' },
], { fallback: true, chunkSize: 50 });
for (const item of output.results) {
  if (item.ok) consume(item.data); // normal API envelope, e.g. { result: [...] }
  else report(item.id, item.status, item.error);
}

Requests accept an optional unique id (otherwise their one-based index), a same-instance /api/ URL, optional GET method, and optional header object. External origins, authentication-header overrides, nested batches, request bodies, and write methods fail validation before any requests are sent. Auth and domain selection come from the existing SDK. Credential last-seen metadata is not touched.

The implementation uses the official ServiceNow Batch API: POST /api/now/v1/batch with batch_request_id and rest_requests. Response serviced_requests carry base64 bodies; unserviced_requests contain IDs. Results are correlated by ID and returned in input order, even if the server reorders them. JSON item bodies become objects, other bodies stay text, and empty bodies are null.

The result includes transport (batch, individual, mixed, or none), counts (total, successful, failed), and results. Each item contains id, ok, HTTP status, data, error, and serviced. Explicit unserviced items have serviced: false; absent responses have serviced: null because execution is unknown. Both are errors, never empty success. Item HTTP failures and malformed body errors retain their item correlation. Malformed aggregate envelopes, unknown/duplicate response IDs, and wrong batch IDs fail the aggregate operation.

By default, only outer HTTP 404/405/501 triggers sequential individual GET fallback. Unsupported endpoint state is cached for this SDK instance. fallback: false requires native batch support. No fallback hides outer authentication, ACL, rate-limit, server, timeout, or malformed-response failures. Item failures, unserviced requests, and missing responses are never automatically retried. Existing SDK auth recovery applies only to a definitive outer 401, not failed items in an otherwise accepted batch. No writes can be replayed through this API.

chunkSize defaults to 50 and accepts 1–1000; chunks run sequentially. timeout defaults to the SDK timeout and applies to each native batch or fallback read, not the entire operation. Platform payload/processing limits can still leave items unserviced; batching does not promise parallel transactions or atomicity. Successful earlier chunks may have been read if a later aggregate request fails.