ui-policies

目录 UI 策略

概述

此技能涵盖 Service Catalog 项目的 UI 策略创建与管理：

• 创建带条件的 UI 策略
• 显示／隐藏／设为必填／禁用操作
• 脚本化 UI 策略条件
• UI Policy Actions 及其 REST API 限制
• 通过后台脚本关联操作的变通方法
• 测试和调试 UI 策略

使用场景： 构建动态目录表单，需要显示／隐藏字段、根据其他选项将字段设为必填，或实现复杂的条件逻辑时。

适用对象： 构建具有动态表单行为的服务目录项目的目录管理员和开发者。

前置条件

• 角色： catalog_admin 或 admin
• 访问权限： catalog_ui_policy、catalog_ui_policy_action、item_option_new 表
• 知识要求： 了解目录项目的基本结构和变量
• 相关技能： 用于创建变量的 catalog/variable-management

了解目录 UI 策略

UI 策略组件

┌─────────────────────────────────────────────────────────┐
│                    Catalog UI Policy                     │
├─────────────────────────────────────────────────────────┤
│  Catalog Item: [reference to sc_cat_item]               │
│  Short Description: "Show approval fields for >$1000"   │
│  Conditions: amount>1000                                │
│  On Load: true    Reverse If False: true                │
│  Script True: [optional advanced logic]                 │
│  Script False: [optional reverse logic]                 │
├─────────────────────────────────────────────────────────┤
│                    UI Policy Actions                     │
├─────────────────────────────────────────────────────────┤
│  Action 1: manager_approval → visible=true, mandatory=true │
│  Action 2: justification → visible=true                    │
│  Action 3: cost_center → disabled=false                    │
└─────────────────────────────────────────────────────────┘

UI 策略评估

User Opens Form
      │
      ▼
┌─────────────────┐
│  On Load = true?│───No──► Conditions evaluated only on change
      │
     Yes
      │
      ▼
┌─────────────────┐
│ Evaluate        │
│ Conditions      │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
  True      False
    │         │
    ▼         ▼
┌────────┐ ┌────────────────┐
│ Apply  │ │Reverse If False│───Yes──► Apply opposite actions
│Actions │ │    = true?     │
└────────┘ └───────┬────────┘
                   │
                  No
                   │
                   ▼
              Do nothing

操作步骤

阶段 1：创建基本 UI 策略

步骤 1.1：创建 UI 策略记录

基于简单条件的策略：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show approval fields when amount exceeds $1000"
    active: true
    on_load: true
    reverse_if_false: true
    order: 100
    global: false
    run_scripts: false

结果： 返回所创建 UI 策略的 sys_id（例如，policy_sys_id）

步骤 1.2：了解 UI 策略字段

字段	类型	说明
catalog_item	引用	目标目录项目
short_description	字符串	策略名称／说明
active	布尔值	启用／禁用策略
on_load	布尔值	表单加载时评估
reverse_if_false	布尔值	条件为 false 时应用相反操作
order	整数	执行顺序（数值越小越先执行）
global	布尔值	应用于所有目录项目
run_scripts	布尔值	启用 Script True／Script False
conditions	条件	针对变量的编码查询

阶段 2：添加 UI 策略条件

步骤 2.1：简单字段条件

条件使用编码查询语法比较变量值：

创建带条件的策略：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show manager approval for external vendors"
    conditions: "vendor_type=external"
    active: true
    on_load: true
    reverse_if_false: true
    order: 100

条件语法示例：

条件	含义
priority=1	优先级等于 1
amount>1000	金额大于 1000
category=hardware^urgency=1	类别为 hardware 且紧急程度为 1
department=IT^ORdepartment=Security	部门为 IT 或 Security
requested_for.active=true	引用的用户处于活动状态
descriptionISNOTEMPTY	描述有值
quantityBETWEEN1@10	数量介于 1 到 10 之间

步骤 2.2：多个条件（AND／OR）

AND 条件：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Require justification for high-cost IT equipment"
    conditions: "department=IT^hardware_type=laptop^estimated_cost>2000"
    active: true
    on_load: true
    reverse_if_false: true
    order: 200

OR 条件：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show security review for sensitive departments"
    conditions: "department=Finance^ORdepartment=Legal^ORdepartment=HR"
    active: true
    on_load: true
    reverse_if_false: true
    order: 300

阶段 3：创建 UI Policy Actions

重要： 由于 ServiceNow 的限制，无法通过 REST API 将 UI Policy Actions 与变量完全关联。catalog_variable 字段需要特殊处理。

步骤 3.1：了解限制

通过 REST API 创建 catalog_ui_policy_action 时：

• 记录会成功创建
• catalog_variable 字段将无法正确关联
• 必须手动修复或通过后台脚本更新后，该操作才能生效

原因：

• catalog_variable 字段需要特殊格式：IO:[variable_sys_id]
• REST API 无法正确解析此引用类型
• 这是 ServiceNow 平台的已知限制

步骤 3.2：创建操作记录（第 1 步，共 2 步）

首先，创建 UI 策略操作记录：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: true
    disabled: false

结果： 返回操作的 sys_id（例如，action_sys_id）

注意： 操作已创建，但尚未关联任何变量。

步骤 3.3：将操作关联到变量（第 2 步，共 2 步）

必需： 使用后台脚本正确关联操作：

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    // Link UI Policy Action to Catalog Variable
    var actionSysId = '[action_sys_id]';
    var variableSysId = '[variable_sys_id]';

    var gr = new GlideRecord('catalog_ui_policy_action');
    if (gr.get(actionSysId)) {
      // The catalog_variable field requires IO: prefix
      gr.setValue('catalog_variable', 'IO:' + variableSysId);
      gr.update();
      gs.info('Linked UI policy action ' + actionSysId + ' to variable ' + variableSysId);
    } else {
      gs.error('UI policy action not found: ' + actionSysId);
    }
  description: Link UI policy action to catalog variable

步骤 3.4：批量关联多个操作

对于多个操作，可将其放在一个脚本中批量处理：

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    // Batch link UI Policy Actions
    var links = [
      { action: '[action1_sys_id]', variable: '[var1_sys_id]' },
      { action: '[action2_sys_id]', variable: '[var2_sys_id]' },
      { action: '[action3_sys_id]', variable: '[var3_sys_id]' }
    ];

    var success = 0;
    var failed = 0;

    links.forEach(function(link) {
      var gr = new GlideRecord('catalog_ui_policy_action');
      if (gr.get(link.action)) {
        gr.setValue('catalog_variable', 'IO:' + link.variable);
        gr.update();
        gs.info('Linked: ' + link.action + ' -> ' + link.variable);
        success++;
      } else {
        gs.error('Action not found: ' + link.action);
        failed++;
      }
    });

    gs.info('Batch link complete: ' + success + ' success, ' + failed + ' failed');
  description: Batch link UI policy actions to variables

阶段 4：UI 策略操作类型

步骤 4.1：显示／隐藏变量

条件为 true 时显示变量：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: false
    disabled: false

然后使用后台脚本链接到变量（步骤 3.3）。

隐藏变量（使用 reverse_if_false）：

• 在操作中设置 visible: true
• 在策略上设置 reverse_if_false: true
• 条件为 FALSE 时，变量将被隐藏

步骤 4.2：必填操作

条件为 true 时将变量设为必填：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: true
    disabled: false

常见模式：显示并设为必填：

• visible: true - 显示字段
• mandatory: true - 要求填写值
• 使用 reverse_if_false: true - 条件为 false 时，字段将被隐藏且不再必填

步骤 4.3：禁用／只读操作

条件为 true 时将变量设为只读：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: false
    disabled: true

适用场景： 锁定计算字段或仅供显示的值。

阶段 5：脚本化 UI 策略

步骤 5.1：启用脚本执行

对于无法用简单编码查询表达的复杂条件：

Tool: SN-Update-Record
Parameters:
  table_name: catalog_ui_policy
  sys_id: [policy_sys_id]
  data:
    run_scripts: true
    script_true: |
      // Runs when condition is TRUE
      // Access variables via g_form
      var amount = g_form.getValue('amount');
      var dept = g_form.getValue('department');

      if (parseFloat(amount) > 5000 && dept == 'IT') {
        // Additional client-side logic
        g_form.showFieldMsg('amount', 'Requires CIO approval', 'info');
      }
    script_false: |
      // Runs when condition is FALSE (optional)
      g_form.hideFieldMsg('amount');

步骤 5.2：脚本示例

复杂验证：

// script_true
var hardware = g_form.getValue('hardware_type');
var quantity = parseInt(g_form.getValue('quantity')) || 0;

// Show warning for bulk orders
if (hardware == 'laptop' && quantity > 10) {
  g_form.showFieldMsg('quantity', 'Bulk orders require procurement approval', 'warning');
}

// Dynamic mandatory based on multiple fields
if (hardware == 'other') {
  g_form.setMandatory('other_description', true);
}

日期验证：

// script_true
var startDate = g_form.getValue('start_date');
var endDate = g_form.getValue('end_date');

if (startDate && endDate) {
  var start = new Date(startDate);
  var end = new Date(endDate);

  if (end < start) {
    g_form.showFieldMsg('end_date', 'End date must be after start date', 'error');
    g_form.setMandatory('end_date', true);
  }
}

阶段 6：完整的 UI 策略示例

步骤 6.1：完整实现

场景： 软件申请表单，其中：

• 如果许可证类型为“Enterprise”，则显示成本中心和经理审批
• 如果数量 > 5，则要求填写业务理由

步骤 1：获取变量 sys_ids：

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=[catalog_item_sys_id]
  fields: sys_id,name,question_text
  limit: 50

步骤 2：创建策略 1 - Enterprise 许可证：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show approval fields for Enterprise license"
    conditions: "license_type=enterprise"
    active: true
    on_load: true
    reverse_if_false: true
    order: 100
# Result: policy1_sys_id

步骤 3：为策略 1 创建操作：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy1_sys_id]
    visible: true
    mandatory: true
    disabled: false
# Result: action1a_sys_id (for cost_center)

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy1_sys_id]
    visible: true
    mandatory: true
    disabled: false
# Result: action1b_sys_id (for manager_approval)

步骤 4：将操作链接到变量：

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    var links = [
      { action: '[action1a_sys_id]', variable: '[cost_center_var_sys_id]' },
      { action: '[action1b_sys_id]', variable: '[manager_approval_var_sys_id]' }
    ];

    links.forEach(function(link) {
      var gr = new GlideRecord('catalog_ui_policy_action');
      if (gr.get(link.action)) {
        gr.setValue('catalog_variable', 'IO:' + link.variable);
        gr.update();
        gs.info('Linked: ' + gr.sys_id);
      }
    });
  description: Link enterprise license policy actions

步骤 5：创建策略 2 - 批量订单：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Require justification for bulk orders (>5)"
    conditions: "quantity>5"
    active: true
    on_load: true
    reverse_if_false: true
    order: 200
# Result: policy2_sys_id

步骤 6：为策略 2 创建并链接操作：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy2_sys_id]
    visible: true
    mandatory: true
    disabled: false
# Result: action2_sys_id

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    var gr = new GlideRecord('catalog_ui_policy_action');
    if (gr.get('[action2_sys_id]')) {
      gr.setValue('catalog_variable', 'IO:[justification_var_sys_id]');
      gr.update();
      gs.info('Linked bulk order justification action');
    }
  description: Link bulk order policy action

阶段 7：测试和调试

步骤 7.1：验证 UI 策略配置

查询目录项目的所有策略：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy
  query: catalog_item=[catalog_item_sys_id]^active=true
  fields: sys_id,short_description,conditions,on_load,reverse_if_false,order,run_scripts
  limit: 50

查询策略的所有操作：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy_action
  query: ui_policy=[policy_sys_id]
  fields: sys_id,catalog_variable,visible,mandatory,disabled
  limit: 20

步骤 7.2：调试操作链接

检查 catalog_variable 是否已正确链接：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy_action
  query: ui_policy=[policy_sys_id]
  fields: sys_id,catalog_variable.name,visible,mandatory,disabled
  limit: 20

如果 catalog_variable.name 为空，则链接失败——请重新运行后台脚本。

步骤 7.3：测试清单

测试前：

• 所有 UI 策略均已启用
• 所有策略操作均已链接变量（catalog_variable 不为空）
• 顺序号设置正确（无冲突）
• reverse_if_false 设置恰当

测试场景：

1. 加载时： 全新打开表单——验证初始可见性
2. 条件为真： 设置值使条件为真——验证操作是否生效
3. 条件为假： 更改值使条件为假——验证是否反转
4. 多个策略： 测试不同条件的组合
5. 脚本策略： 验证脚本执行时无错误

步骤 7.4：常用调试命令

查找未链接的操作：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy_action
  query: ui_policy.catalog_item=[catalog_item_sys_id]^catalog_variableISEMPTY
  fields: sys_id,ui_policy.short_description
  limit: 50

按名称获取变量 sys_ids：

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=[catalog_item_sys_id]^name=manager_approval
  fields: sys_id,name

工具使用摘要

操作	MCP 工具	备注
创建 UI 策略	SN-Create-Record	catalog_ui_policy 表
创建 UI 策略操作	SN-Create-Record	catalog_ui_policy_action 表
将操作链接到变量	SN-Execute-Background-Script	必需——REST API 限制
查询策略	SN-Query-Table	catalog_ui_policy
查询操作	SN-Query-Table	catalog_ui_policy_action
更新策略	SN-Update-Record	用于 script_true/script_false

最佳实践

• 使用描述性名称： 使用清晰简短的 short_description，便于调试
• 谨慎设置顺序： 顺序号较小的先执行——避免冲突
• 使用 reverse_if_false： 比创建两个相反的策略更简洁
• 测试两种状态： 务必测试条件为真和为假的情况
• 尽量减少脚本： 尽可能使用条件——脚本速度较慢
• 记录逻辑： 在 description 字段中注释复杂条件
• 批量链接操作： 使用单个后台脚本链接多个操作
• 验证链接： 始终查询以确认 catalog_variable 已填充

故障排除

UI 策略未执行

**症状：**变量的可见性／必填状态没有变化
原因：

1. 策略未启用
2. 条件语法错误
3. 操作未关联到变量 解决方案：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy
  query: catalog_item=[item_sys_id]
  fields: short_description,active,conditions

检查 active=true，并确认条件语法正确。

操作未关联（catalog_variable 为空）

**症状：**策略已执行，但字段没有变化
**原因：**REST API 限制——操作未正确关联
解决方案：

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    var gr = new GlideRecord('catalog_ui_policy_action');
    gr.get('[action_sys_id]');
    gr.setValue('catalog_variable', 'IO:[variable_sys_id]');
    gr.update();
    gs.info('Fixed action link');
  description: Fix unlinked UI policy action

reverse_if_false 不起作用

**症状：**条件为 false 时，变量仍保持可见／必填
原因：

1. 未启用 reverse_if_false
2. 未启用 on_load（仅在发生更改时评估） 解决方案：

Tool: SN-Update-Record
Parameters:
  table_name: catalog_ui_policy
  sys_id: [policy_sys_id]
  data:
    on_load: true
    reverse_if_false: true

脚本错误

**症状：**表单加载时控制台报错，脚本未执行
**原因：**script_true 或 script_false 中存在 JavaScript 语法错误
解决方案：

1. 检查浏览器控制台中的错误
2. 验证 JavaScript 语法
3. 先在浏览器控制台中测试脚本

多个策略相互冲突

**症状：**变量行为不可预测
**原因：**多个策略对同一变量执行相互冲突的操作
解决方案：

1. 查询所有影响该变量的策略
2. 调整顺序编号
3. 考虑将其合并为一个包含复杂条件的策略

相关技能

• catalog/variable-management - 创建和配置变量
• catalog/item-creation - 完整配置目录项目
• catalog/approval-workflows - 审批配置
• admin/script-execution - 后台脚本模式

参考资料

• ServiceNow 目录 UI 策略
• UI 策略操作
• 客户端脚本与 UI 策略