UiPolicy

Creates a UI Policy that defines dynamic form behaviors to change field properties and control related list visibility based on conditions. UI Policies can make fields mandatory, read-only, visible, hidden, or cleared, and show or hide related lists when certain conditions are met.

Signature

UiPolicy(config)

Parameters

config

UiPolicy<keyof Tables>

an object containing api properties:

Properties:

• $id (required): string | number | ExplicitKey<string>

• shortDescription (required): string A brief description of what the UI Policy does (required and must not be empty)

• actions (optional): UiPolicyAction<keyof Tables>[] List of actions to perform when the UI Policy condition is met

  • field (required): TableSchemaDotWalk<T> -- The field to which the action applies
  • visible (optional): boolean | 'ignore' -- Whether the field should be visible
  • readOnly (optional): boolean | 'ignore' -- Whether the field should be read-only (disabled). true means read-only/disabled, false means editable
  • mandatory (optional): boolean | 'ignore' -- Whether the field should be mandatory
  • cleared (optional): boolean -- Whether the field should be cleared when the condition is met
  • value (optional): string -- Value to set for the field
  • fieldMessage (optional): string -- Message to display for the field
  • fieldMessageType (optional): 'error' | 'info' | 'warning' | 'none' -- Type of field message
  • valueAction (optional): string -- Action to perform on the field value
  • table (optional): keyof Tables -- The table reference for the action (sys_db_object)

• active (optional): boolean Whether the UI Policy is active

• conditions (optional): string A condition script or query that determines when the UI Policy applies

• description (optional): string Detailed description of the UI Policy

• global (optional): boolean Whether the UI Policy applies to all form views. If false, use the view property to target a specific form view

• inherit (optional): boolean Whether the UI Policy is inherited by tables that extend this table

• isolateScript (optional): boolean Whether to run the script in an isolated scope

• modelId (optional): string Model ID for the UI Policy

• modelTable (optional): keyof Tables Model table for the UI Policy

• onLoad (optional): boolean Whether the UI Policy runs when the form loads

• order (optional): number Order/priority of the UI Policy execution

• protectionPolicy (optional): 'read' | 'protected' Controls edit/view access for other developers after the application is installed.

  • 'read': Others can see the script logic but not change it
  • 'protected': Others cannot change this record
  • Omit to allow other developers to customize this record

• relatedListActions (optional): UiPolicyRelatedListAction[] List of related list visibility controls

  • list (optional): string | Record<'sys_relationship'> -- The related list identifier. Use 'child_table.reference_field' format for reference-based relationships (e.g., 'x_myapp_task.parent'), or a GUID string for system sys_relationship records. The plugin automatically adds/removes the REL: prefix during transformation — do not include it
  • visible (optional): boolean | 'ignore' -- Whether the related list should be visible. true = visible, false = hidden, 'ignore' = no change

• reverseIfFalse (optional): boolean Whether to reverse the actions when the condition is false (renamed from 'reverse' for clarity)

• runScripts (optional): boolean Whether to run the scripts defined in scriptTrue/scriptFalse

• scriptFalse (optional): string JavaScript code that runs when the condition evaluates to false

• scriptTrue (optional): string JavaScript code that runs when the condition evaluates to true

• setValues (optional): string Values to set when the UI Policy is applied

• table (optional): keyof Tables The table to which the UI Policy applies (optional)

• uiType (optional): 'desktop' | 'mobile-or-service-portal' | 'all' User interface to which the UI Policy applies

• view (optional): string | Record<'sys_ui_view'> View context where the UI Policy applies (sys_ui_view reference or name). If global is true, the UI Policy applies to all form views. If global is false/undefined, specify a view to make the policy view-specific.

See

• https://docs.servicenow.com/csh?topicname=ui-policy-api-now-ts.html&version=latest

Examples

Basic UI Policy

Create a minimal UI policy for a table

/**
 * @title Basic UI Policy
 * @description Create a minimal UI policy for a table
 */
import { UiPolicy } from '@servicenow/sdk/core'

UiPolicy({
    $id: Now.ID['basic_policy'],
    table: 'incident',
    shortDescription: 'Basic UI Policy Test',
})

UI Policy with Field Actions

Create a UI policy that controls field visibility, mandatory state, and read-only behavior

/**
 * @title UI Policy with Field Actions
 * @description Create a UI policy that controls field visibility, mandatory state, and read-only behavior
 */
import { UiPolicy } from '@servicenow/sdk/core'

UiPolicy({
    $id: Now.ID['policy_with_actions'],
    table: 'incident',
    shortDescription: 'Policy with Actions',
    actions: [
        {
            field: 'priority',
            visible: false,
            mandatory: 'ignore',
            readOnly: 'ignore',
        },
        {
            field: 'urgency',
            visible: 'ignore',
            mandatory: true,
            readOnly: false,
        },
    ],
})

UI Policy with Scripts

Create a UI policy with condition-based scripts and advanced options

/**
 * @title UI Policy with Scripts
 * @description Create a UI policy with condition-based scripts and advanced options
 */
import { UiPolicy } from '@servicenow/sdk/core'

UiPolicy({
    $id: Now.ID['policy_with_scripts'],
    table: 'incident',
    shortDescription: 'Policy with Scripts',
    runScripts: true,
    uiType: 'desktop',
    scriptTrue: 'function onCondition() { g_form.addErrorMessage("Error"); }',
    scriptFalse: 'function onCondition() { g_form.clearMessages(); }',
    conditions: 'state=1',
    global: true,
    reverseIfFalse: true,
    isolateScript: true,
})

UI Policy with Related List Actions

Create a UI policy that controls related list visibility based on conditions

/**
 * @title UI Policy with Related List Actions
 * @description Create a UI policy that controls related list visibility based on conditions
 */
import { UiPolicy } from '@servicenow/sdk/core'

UiPolicy({
    $id: Now.ID['policy_with_related_lists'],
    table: 'x_myapp_project',
    shortDescription: 'Show task and member lists when project is active',
    conditions: 'status=active',
    onLoad: true,
    relatedListActions: [
        {
            list: 'x_myapp_task.project',
            visible: true,
        },
        {
            list: 'x_myapp_team_member.project',
            visible: true,
        },
    ],
})