SDK 4.14.0

@servicenow/sdk — Release Notes

Version: 4.14.0
Availability: npm — https://www.npmjs.com/package/@servicenow/sdk

---

🚀 Overview

Version 4.14.0 adds a new UiMacro Fluent API, support for ATF reusable tests, and a new now-sdk exec command for running scripts on your instance. It also includes changes to credential storage, bug fixes, and a dependency update addressing reported vulnerabilities.

---

New Fluent APIs

UiMacro API

Define UI macros (sys_ui_macro) in Fluent, with new API reference, a UI Macro guide, and a Jelly guide. Keep the Jelly in its own file with Now.include().

import { UiMacro } from '@servicenow/sdk/core'

UiMacro({
    $id: Now.ID['alert-banner'],
    name: 'alert_banner',
    description: 'Displays a styled alert banner. Parameters: type (info|success|warning|danger), message.',
    xml: Now.include('./alert-banner.jelly.xml'),
})

ATF reusable tests

Test() now accepts isReusable: true with typed inputs / outputs. Call a reusable test from another test with the new atf.executeTest step, and populate its outputs with atf.setReusableTestOutputs. More info about resusable tests can be found here.

import { Test, StringColumn } from '@servicenow/sdk/core'

export const greetUser = Test(
    {
        $id: Now.ID['greet_user'],
        name: 'Greet User',
        isReusable: true,
        inputs: {
            userName: StringColumn({}),
        },
        outputs: {
            greeting: StringColumn({}),
        },
    },
    (atf, inputs, outputs) => {
        atf.server.log({
            $id: Now.ID['log_greeting'],
            log: inputs.userName,
        })

        atf.setReusableTestOutputs(
            outputs,
            { $id: Now.ID['set_outputs'] },
            { greeting: 'Hello!' }
        )
    }
)

Test(
    {
        $id: Now.ID['caller_test'],
        name: 'Caller Test',
    },
    (atf) => {
        const result = atf.executeTest(
            greetUser,
            { $id: Now.ID['greet_user_step'] },
            { userName: 'Jane Doe' }
        )
        // result.greeting is typed from the reusable test's outputs
    }
)

Assessments
Improved support for setting domain (Assessment, RiskAssessment).

Tables & Columns

Denormalized array columns
Columns now accept arrayDenormalized, matching the platform's denormalized/off-row array storage.

tags: StringColumn({ array: true, arrayDenormalized: true })

referenceQualCondition and basePolicy
Reference and list columns support referenceQualCondition, and Table supports basePolicy.

ACL role protectionPolicy
Each role on an Acl can now set its own protectionPolicy.

CLI

now-sdk exec
Runs a server-side script on the authenticated instance, like the Scripts - Background page. Accepts an inline script, --file, or stdin, records the run for rollback by default, and supports --reason for traceability.

now-sdk exec --file ./scripts/backfill.js --reason "Backfill category"

Credential storage changes

Why it changed: now-sdk kept every saved instance profile in a single entry in the OS keychain. That entry grows with each profile and token, and keychains limit entry size. Windows Credential Manager caps a credential at 2,560 bytes, so users there with several instances or OAuth tokens hit the cap and now-sdk auth failed to save credentials. The new storage applies on all platforms.

How it works now:

• Credentials are encrypted with AES-256-GCM and stored in ~/.now-sdk/credentials.enc. The file has no size limit.
• Only a random 32-byte encryption key is kept in the OS keychain (macOS Keychain, Windows Credential Manager, or the Linux keyring), under the account now-sdk-credentials-key. It's a fixed size and never approaches any platform's limit.

Migration: automatic on the first command that reads credentials. Your existing profiles are encrypted into the new file and nothing needs to be re-entered. The old keychain entry is left in place, so older now-sdk versions in other projects on the same machine keep working. It's removed only by now-sdk auth --delete all.

Configuration:

• SN_SDK_CREDENTIALS_DIR — directory for credentials.enc. Defaults to ~/.now-sdk; an empty value is treated as unset.

# macOS / Linux
export SN_SDK_CREDENTIALS_DIR=/path/to/credentials

# Windows (PowerShell)
$env:SN_SDK_CREDENTIALS_DIR = "$env:USERPROFILE\.now-sdk-credentials"

If the stored credentials can't be read (for example the keychain is locked or was cleared, or credentials.enc was copied from another machine, since it can only be decrypted with that machine's keychain key): in an interactive terminal the CLI offers to reset and re-authenticate. In non-interactive sessions (CI) it fails with a message to run now-sdk auth --delete all and add the profiles again. If the file was written by a newer now-sdk, you're asked to upgrade rather than reset.

Note: the encryption key lives in the OS keychain, so credentials.enc is not portable between machines. For CI and other headless environments, authenticate with environment credentials instead of a stored profile; see the CI integration guide.

Bug Fixes

• Fixed single quotes in attribute values being written unescaped on transform.
• Scoped apps no longer treat tables carrying their own scope prefix as augmentations of an existing table.
• Unlabeled columns get the platform's sentence-case label on transform.
• sys_dictionary security roles are preserved through transform and build.
• OverrideColumn readOnlyOption now matches instance behavior.
• sys_name is preserved for sys_number records and set on override records.
• Role() and Property() keep an explicit suffix.
• Script Includes: a missing sandbox_callable now falls back to client_callable, as on the platform.
• Related lists are written as a single XML with their entries.
• Fixed duplicate sys_es_latest_script records on transform.
• sys_ui_message records are now handled as regular records instead of being dropped.
• sys_app vendor / vendorPrefix are preserved during Fluent conversion.
• Fixed an AIUX ACL path-handling bug on Windows.
• Fixed corrupted component_props on dashboard widgets that aren't chart-family widgets.
• RestApi: default_operation_uri is set only on the route matching the API's default version.
• Fixed an unresolved default_view identifier breaking List update names.
• Fixed the Array.from polyfill in now-ux-globals
• Updated third-party dependencies to address report

Playbook

• Required AI-agent fields are now allowed regardless of aiAgentFieldDisplayPreferences.
• Fixed unquoted gs.dateGenerate arguments in the RequestAdHocApproval list query.

Documentation

• ATF guides now recommend testing as a dedicated user with the app's role, and looking up a table's schema before setting its fields.
• Fixes to the UI page patterns, application menu, and UI page guides.

---