variable-management

服务目录变量管理

概述

此技能涵盖全面的目录变量管理：

• 所有变量类型及其适用场景
• 创建和配置变量
• 用于筛选选项的引用限定条件
• 级联/依赖变量
• 用于显示/隐藏/设为必填逻辑的 UI 策略
• 变量选项（question_choice 表）
• 可复用的变量集

适用场景： 构建目录表单、实现动态表单行为或排查变量问题时。

前置条件

• 角色： catalog_admin 或 admin
• 访问权限： item_option_new、question_choice、catalog_ui_policy 表
• 知识： 目录结构基础知识
• 相关技能： catalog/item-creation，用于完整的项目配置

流程

步骤 1：了解变量类型

重要： 变量类型是存储在 type 字段中的数值。

完整变量类型参考：

类型	值	适用场景	示例
单行文本	16	简短文本输入	名称、标题、代码
多行文本	6	长文本	描述、备注、理由
选项（单选按钮）	1	2–5 个选项，可同时显示	优先级、是/否/可能
选择框（下拉菜单）	5	6 个以上选项或较长标签	部门、位置
引用	8	链接到 ServiceNow 记录	用户、CI、组
是/否	7	布尔切换	复选框、切换开关
复选框	7	与“是/否”相同	接受、同意
日期	9	日期选择器	开始日期、截止日期
日期/时间	10	日期和时间选择器	会议时间、截止时间
电子邮件	32	电子邮件验证	联系邮箱
URL	26	URL 验证	网站、链接
数字量表	2	1–10 评分	满意度、优先级
查找选择框	21	已筛选的引用下拉菜单	已筛选的用户/CI
容器开始	19	以视觉方式对变量分组	分节标题
容器结束	20	结束容器分组	分节页脚
标签	11	仅显示文本	说明、警告
分隔符	12	视觉分隔	换行
宏	14	执行 UI 宏	自定义小组件
掩码	25	类似密码的输入	敏感数据
HTML	17	富文本/HTML 显示	格式化说明
宽文本	6	与多行文本相同	旧版
IP 地址	27	IP 地址验证	网络配置
时长	29	时间时长	SLA 时长
附件	15	文件上传	文档、图片
列表收集器	22	多选引用	多个用户/组
查找多选	23	多选筛选	多个已筛选的引用

步骤 2：创建基本变量

单行文本变量：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "employee_name"
    question_text: "Employee Full Name"
    type: 16
    order: 100
    mandatory: true
    active: true
    help_text: "Enter the employee's full legal name as it appears on their ID"
    example_text: "John A. Smith"
    default_value: ""

多行文本变量：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "business_justification"
    question_text: "Business Justification"
    type: 6
    order: 200
    mandatory: true
    active: true
    help_text: "Explain why this request is needed for business operations"

日期变量：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "required_by_date"
    question_text: "Required By Date"
    type: 9
    order: 300
    mandatory: true
    active: true

步骤 3：创建选项变量

重要： 目录变量选项使用 question_choice 表，而非 sys_choice！

类型 1 - 选项（单选按钮）： 适用于用户需要同时看到的 2–5 个选项。

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "urgency_level"
    question_text: "Request Urgency"
    type: 1  # Radio buttons
    order: 400
    mandatory: true
    active: true

类型 5 - 选择框（下拉菜单）： 适用于 6 个以上选项或标签较长的选项。

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "department"
    question_text: "Department"
    type: 5  # Dropdown
    order: 500
    mandatory: true
    active: true
    include_none: false  # Don't show "-- None --" option

向变量添加选项：

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]  # item_option_new sys_id
    text: "Engineering"
    value: "engineering"
    order: 100
    inactive: false

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]
    text: "Marketing"
    value: "marketing"
    order: 200
    inactive: false

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]
    text: "Finance"
    value: "finance"
    order: 300
    inactive: false

查询变量选项：

Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[variable_sys_id]
  fields: sys_id,text,value,order,inactive
  limit: 100

步骤 4：创建引用变量

基本引用变量：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "requested_for"
    question_text: "Request For (User)"
    type: 8  # Reference
    reference: sys_user  # Target table
    order: 100
    mandatory: true
    active: true

带限定条件（筛选器）的引用：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "manager_approval"
    question_text: "Manager for Approval"
    type: 8
    reference: sys_user
    reference_qual: "active=true^rolesLIKEmanager"
    order: 200
    mandatory: true
    active: true

引用限定条件示例：

适用场景	引用限定条件
仅限活跃用户	active=true
特定组中的用户	sys_idIN<group_members_subquery>
活跃 CI	install_status=1
特定 CI 类	sys_class_name=cmdb_ci_server
指定位置的服务器	location=[location_sys_id]^sys_class_name=cmdb_ci_server

动态引用限定条件（JavaScript）：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "team_member"
    question_text: "Team Member"
    type: 8
    reference: sys_user
    reference_qual: "javascript:new MyCatalogUtils().getTeamMembers(current.variables.department)"
    order: 300
    mandatory: true
    active: true

第 5 步：创建级联/依赖变量

级联变量会根据另一个变量的选择而变化。

示例：部门 -> 团队级联

步骤 1 - 创建父变量（部门）：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "department"
    question_text: "Department"
    type: 5
    order: 100
    mandatory: true
    active: true
# Result: sys_id = "dept_var_id"

步骤 2 - 创建子变量（团队）：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "team"
    question_text: "Team"
    type: 5
    order: 200
    mandatory: true
    active: true
    dependent_on_variable: "dept_var_id"  # Parent variable sys_id
# Result: sys_id = "team_var_id"

步骤 3 - 添加依赖选项：

# Engineering teams
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Frontend Engineering"
    value: "frontend"
    order: 100
    inactive: false
    depends_on: "engineering"  # Value of parent choice

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Backend Engineering"
    value: "backend"
    order: 200
    inactive: false
    depends_on: "engineering"

# Marketing teams
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Digital Marketing"
    value: "digital"
    order: 100
    inactive: false
    depends_on: "marketing"

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Brand Marketing"
    value: "brand"
    order: 200
    inactive: false
    depends_on: "marketing"

第 6 步：创建 UI 策略

UI 策略根据条件控制变量的可见性、必填状态和只读状态。

重要： 由于 ServiceNow 的限制，无法通过 REST API 完整关联 UI 策略操作。catalog_variable 字段不会通过标准 API 调用更新。

创建 UI 策略：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show manager approval when cost > 1000"
    active: true
    on_load: true
    reverse_if_false: true
    script_false: ""
    script_true: ""
    order: 100

UI 策略条件： 条件会针对目录项变量进行评估。

创建带条件的 UI 策略：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show additional details for external vendors"
    conditions: "vendor_type=external"  # Variable name = value
    active: true
    on_load: true
    reverse_if_false: true
    order: 200

UI 策略操作字段：

操作	说明
visible	显示/隐藏变量
mandatory	将变量设为必填
disabled	将变量设为只读

创建 UI 策略操作：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [ui_policy_sys_id]
    catalog_variable: "IO:[variable_sys_id]"  # Must use IO: prefix
    visible: true
    mandatory: true
    disabled: false

已知问题 - UI 策略操作关联： 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('Updated UI policy action: ' + gr.sys_id);
  description: "Link UI policy action to catalog variable"

第 7 步：配置变量集

变量集将可在多个目录项中重复使用的变量分组。

创建变量集：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new_set
  data:
    title: "Standard Requester Information"
    description: "Common requester fields used across all hardware requests"
    active: true
    type: "one_to_one"  # Each item gets unique variable instances
    order: 100

变量集类型：

类型	说明
one_to_one	为每个项克隆变量（值彼此独立）
one_to_many	多个项共享变量（使用同一条记录）

将变量添加到变量集：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    variable_set: [variable_set_sys_id]  # Instead of cat_item
    name: "cost_center"
    question_text: "Cost Center"
    type: 16
    order: 100
    mandatory: true
    active: true

将变量集与目录项关联：

Tool: SN-Create-Record
Parameters:
  table_name: io_set_item
  data:
    sc_cat_item: [catalog_item_sys_id]
    variable_set: [variable_set_sys_id]
    order: 100

第 8 步：高级变量配置

隐藏变量（用于工作流数据）：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "internal_tracking_id"
    question_text: "Tracking ID"
    type: 16
    order: 9999
    mandatory: false
    active: true
    hidden: true  # Not visible to users
    read_only: true

只读变量（仅用于显示）：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "calculated_cost"
    question_text: "Estimated Cost"
    type: 16
    order: 800
    mandatory: false
    active: true
    read_only: true
    default_value: "$0.00"

带属性的变量：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "quantity"
    question_text: "Quantity"
    type: 16
    order: 600
    mandatory: true
    active: true
    attributes: "min=1,max=100,step=1"  # HTML5 validation

列表收集器（多选引用）：

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "additional_users"
    question_text: "Additional Users for Access"
    type: 22  # List Collector
    reference: sys_user
    reference_qual: "active=true"
    order: 700
    mandatory: false
    active: true

第 9 步：查询和验证变量

获取目录项的所有变量：

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=[catalog_item_sys_id]
  fields: sys_id,name,question_text,type,order,mandatory,active,reference
  limit: 100

获取变量的选项：

Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[variable_sys_id]
  fields: sys_id,text,value,order,depends_on,inactive
  limit: 100

获取目录项的 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
  limit: 50

获取目录项的变量集：

Tool: SN-Query-Table
Parameters:
  table_name: io_set_item
  query: sc_cat_item=[catalog_item_sys_id]
  fields: sys_id,variable_set.title,order
  limit: 50

完整示例：硬件请求表单

# 1. Create container for requester info
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "requester_section"
    question_text: "Requester Information"
    type: 19  # Container Start
    order: 100
    active: true

# 2. Requested For
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "requested_for"
    question_text: "Requested For"
    type: 8
    reference: sys_user
    reference_qual: "active=true"
    order: 110
    mandatory: true
    active: true

# 3. Department (dropdown)
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "department"
    question_text: "Department"
    type: 5
    order: 120
    mandatory: true
    active: true
# Result: sys_id = "dept_id"

# Add department choices
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "dept_id"
    text: "Engineering"
    value: "eng"
    order: 100

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "dept_id"
    text: "Sales"
    value: "sales"
    order: 200

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "dept_id"
    text: "Finance"
    value: "fin"
    order: 300

# 4. End requester section
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "requester_section_end"
    question_text: ""
    type: 20  # Container End
    order: 190
    active: true

# 5. Hardware type (radio - 3 options)
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "hardware_type"
    question_text: "Hardware Type"
    type: 1  # Radio buttons
    order: 200
    mandatory: true
    active: true
# Result: sys_id = "hw_type_id"

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "hw_type_id"
    text: "Laptop"
    value: "laptop"
    order: 100

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "hw_type_id"
    text: "Desktop"
    value: "desktop"
    order: 200

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "hw_type_id"
    text: "Monitor"
    value: "monitor"
    order: 300

# 6. Business justification
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "justification"
    question_text: "Business Justification"
    type: 6  # Multi-line
    order: 300
    mandatory: true
    active: true

# 7. Required by date
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "needed_by"
    question_text: "Required By"
    type: 9  # Date
    order: 400
    mandatory: true
    active: true

变量类型选择指南

Text Input:
├── Short answer (< 100 chars)?
│   └── Type 16: Single Line Text
├── Long answer (> 100 chars)?
│   └── Type 6: Multi-Line Text
└── Sensitive/password?
    └── Type 25: Masked

Selection (from list):
├── 2-5 options, visible at once?
│   └── Type 1: Choice (Radio)
├── 6+ options OR long labels?
│   └── Type 5: Select Box
├── Single ServiceNow record?
│   └── Type 8: Reference
├── Multiple ServiceNow records?
│   └── Type 22: List Collector
└── Filtered reference list?
    └── Type 21: Lookup Select Box

Boolean:
└── Yes/No or Checkbox?
    └── Type 7: Yes/No

Date/Time:
├── Date only?
│   └── Type 9: Date
└── Date and time?
    └── Type 10: Date/Time

Special:
├── Email address?
│   └── Type 32: Email
├── URL/link?
│   └── Type 26: URL
├── IP address?
│   └── Type 27: IP Address
├── File upload?
│   └── Type 15: Attachment
├── Rating (1-10)?
│   └── Type 2: Numeric Scale
└── Time duration?
    └── Type 29: Duration

Display Only:
├── Instructions/info?
│   └── Type 11: Label
├── Rich HTML content?
│   └── Type 17: HTML
└── Visual separator?
    └── Type 12: Break

Layout:
├── Start section?
│   └── Type 19: Container Start
└── End section?
    └── Type 20: Container End

工具使用摘要

操作	MCP 工具	表
创建变量	SN-Create-Record	item_option_new
创建选项	SN-Create-Record	question_choice
创建 UI 策略	SN-Create-Record	catalog_ui_policy
创建 UI 策略操作	SN-Create-Record	catalog_ui_policy_action
创建变量集	SN-Create-Record	item_option_new_set
关联变量集	SN-Create-Record	io_set_item
查询变量	SN-Query-Table	item_option_new
查询选项	SN-Query-Table	question_choice

最佳实践

• 选项达到 6 个或以上时使用类型 5： 与单选按钮相比，下拉列表更适合较长的选项列表
• 选项为 2–5 个时使用类型 1： 单选按钮可让用户一次看到所有选项
• 使用 question_choice，而非 sys_choice： 目录变量始终使用 question_choice
• 排序间隔设为 100： 便于之后插入变量（100、200、300……）
• 使用有意义的变量名称： 采用 lowercase_with_underscores 命名
• 帮助文本： 始终为复杂字段提供说明
• 使用容器分组： 使用类型 19/20 整理相关字段
• 引用限定条件： 仅将引用字段筛选为相关记录
• 测试 UI 策略： 验证显示/隐藏逻辑在两个方向上都能正常工作

故障排除

选项未显示

现象： 下拉列表或单选按钮中没有选项 原因： 选项创建在 sys_choice 中，而不是 question_choice 中 解决方法：

# Verify choices are in question_choice
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[variable_sys_id]
  fields: text,value,order,inactive

# If empty, create choices in correct table
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]
    text: "Option 1"
    value: "opt1"
    order: 100

级联变量未进行筛选

现象： 无论父变量选择什么，子变量都会显示所有选项 原因： depends_on 的值与父变量选项的值不匹配 解决方法：

# Check parent choices
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[parent_variable_sys_id]
  fields: text,value

# Verify child choices have matching depends_on values
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[child_variable_sys_id]
  fields: text,value,depends_on

UI 策略不起作用

**症状：**变量未根据条件隐藏或显示 原因：

1. UI 策略未激活
2. 条件语法不正确
3. UI 策略操作未关联 解决方案：

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

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

参考限定条件语法错误

**症状：**参考字段显示错误或没有结果 **原因：**reference_qual 中的编码查询语法无效 **解决方案：**先在列表筛选器中测试查询，然后使用完全相同的语法

相关技能

• catalog/item-creation - 创建完整的目录项
• catalog/approval-workflows - 配置审批
• catalog/request-fulfillment - 处理已提交的请求
• development/client-scripts - 动态表单行为

参考资料

• ServiceNow 变量类型
• 目录 UI 策略
• 变量集