configuration-validation

配置验证

概述

配置验证对于维护质量和防止 ServiceNow 部署出错至关重要。本技能将介绍在部署前系统地验证目录项、工作流、业务规则和其他配置的方法。

• 解决什么问题？ 在配置错误、缺少依赖项和引用失效影响用户或导致生产问题之前将其发现
• 谁应使用此技能？ 负责 ServiceNow 配置质量保证的管理员、开发人员和发布经理
• 预期成果是什么？ 确保配置经过验证且正常运行，全面检测错误，并增强对部署的信心

前提条件

• 所需的 ServiceNow 角色：admin 或特定管理员角色（catalog_admin、workflow_admin）
• 对配置表（sys_script、wf_workflow、sc_cat_item）的读取权限
• 了解 ServiceNow 配置类型
• 相关技能：admin/schema-discovery（有助于了解结构）

流程

步骤 1：确定配置类型

确定需要验证的配置类型。每种类型的验证要求各不相同。

配置类型和表：

配置类型	表	关键验证项
目录项	sc_cat_item	变量、工作流、定价
目录变量	item_option_new	类型、引用、选项
工作流	wf_workflow	活动、转换、条件
业务规则	sys_script	脚本语法、条件、时间
UI 策略	sys_ui_policy	条件、操作、触发器
客户端脚本	sys_script_client	脚本语法、类型、表
脚本包含	sys_script_include	客户端可调用性、作用域
ACL	sys_security_acl	条件、脚本、角色

步骤 2：目录项验证

验证目录项是否完整、配置正确且依赖项正常运行。

如果使用 MCP 工具：

Tool: SN-Validate-Configuration
Parameters:
  type: catalog_item
  sys_id: <catalog_item_sys_id>
  checks:
    - variables
    - workflows
    - pricing
    - approvals
    - fulfillment

如果使用 REST API：

# Get catalog item details
GET /api/now/table/sc_cat_item/<sys_id>?sysparm_display_value=all

# Get associated variables
GET /api/now/table/item_option_new?sysparm_query=cat_item=<sys_id>&sysparm_fields=name,type,mandatory,reference,order

# Get associated workflows
GET /api/now/table/wf_workflow?sysparm_query=table=sc_req_item^published=true&sysparm_fields=name,sys_id

目录项验证清单：

检查项	说明	严重性
活动状态	项目处于活动状态且可见	严重
类别	已分配有效类别	高
变量	包含所有必需变量	严重
变量顺序	变量具有唯一的顺序值	中
变量引用	引用字段指向有效表	严重
工作流	存在已发布的履行工作流	高
审批规则	审批组／用户存在	高
定价	价格和周期性价格有效	中
简短说明	字符数未超出限制	低
图标	包含有效图标或图像	低

步骤 3：变量验证

验证目录变量的配置是否正确且功能正常。

如果使用 MCP 工具：

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=<catalog_item_sys_id>
  fields: name,question_text,type,mandatory,reference,order,variable_set

变量类型验证规则：

类型	必填字段	常见错误
1（是／否）	question_text	无
5（选择框）	question_text、choices	缺少选项
6（单行）	question_text、max_length	长度过长
8（引用）	question_text、reference	表引用无效
9（日期）	question_text	日期格式问题
14（宏）	macro	未找到宏
18（查找）	reference、lookup_table	表不匹配
21（列表收集器）	reference、list_table	列表配置无效

验证变量选项：

Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=<variable_sys_id>
  fields: text,value,order

决策点：

• 如果类型为 5（选择框）且没有选项 → 错误：缺少选项
• 如果类型为 8（引用）且引用表不存在 → 错误：引用无效
• 如果 mandatory=true 但 default_value 为空 → 警告：必填字段没有默认值

步骤 4：工作流验证

验证工作流是否完整、转换是否正确，以及是否存在死路。

如果使用 MCP 工具：

Tool: SN-Validate-Configuration
Parameters:
  type: workflow
  sys_id: <workflow_sys_id>
  checks:
    - activities
    - transitions
    - conditions
    - end_states

如果使用 REST API：

# Get workflow details
GET /api/now/table/wf_workflow/<sys_id>?sysparm_display_value=all

# Get workflow activities
GET /api/now/table/wf_activity?sysparm_query=workflow_version.workflow=<sys_id>&sysparm_fields=name,activity_definition,x,y

# Get workflow transitions
GET /api/now/table/wf_transition?sysparm_query=workflow_version.workflow=<sys_id>&sysparm_fields=from,to,condition

工作流验证清单：

检查项	描述	严重性
已发布	工作流已发布并处于活动状态	严重
开始活动	恰好包含一个开始活动	严重
结束活动	至少包含一个结束活动	严重
孤立活动	所有活动都有传入转换	高
死路活动	所有活动都有传出转换（结束活动除外）	高
条件完整性	所有分支条件均涵盖所有情况	高
活动脚本	脚本语法有效	严重
超时处理程序	长时间运行的活动设有超时	中
回滚活动	正确处理审批拒绝	中

检测孤立活动：

Tool: SN-Query-Table
Parameters:
  table_name: wf_activity
  query: workflow_version.workflow=<sys_id>^activity_definition.name!=Begin
  fields: sys_id,name

# Then check each activity has incoming transition
Tool: SN-Query-Table
Parameters:
  table_name: wf_transition
  query: to=<activity_sys_id>
  fields: sys_id

步骤 5：业务规则验证

验证业务规则的配置、语法及性能注意事项是否正确。

如果使用 MCP 工具：

Tool: SN-Validate-Configuration
Parameters:
  type: business_rule
  sys_id: <business_rule_sys_id>
  checks:
    - syntax
    - conditions
    - performance
    - scope

如果使用 REST API：

# Get business rule details
GET /api/now/table/sys_script/<sys_id>?sysparm_fields=name,when,collection,active,script,filter_condition,order

业务规则验证清单：

检查项	描述	严重性
活动状态	规则处于活动状态	信息
表	有效的表引用	严重
触发时机	时机合适（before/after/async）	高
条件	筛选条件有效	高
脚本语法	没有 JavaScript 错误	严重
Before 中的 GlideRecord	避免在 before 规则中使用 GlideRecord 更新	高
Current.update()	避免在 before 规则中使用（会导致递归）	严重
变更检查	使用 .changes() 提高效率	中
顺序	顺序值合适	中
范围	应用范围正确	高

常见业务规则反模式：

// ANTI-PATTERN 1: current.update() in before rule
// Causes infinite recursion
(function executeRule(current, previous) {
  current.priority = 1;
  current.update(); // BAD! Remove this line
})(current, previous);

// ANTI-PATTERN 2: Unnecessary GlideRecord in before rule
(function executeRule(current, previous) {
  var gr = new GlideRecord('incident');
  gr.get(current.sys_id);
  gr.priority = 1;
  gr.update(); // BAD! Just set current.priority = 1
})(current, previous);

// ANTI-PATTERN 3: No changes() check
(function executeRule(current, previous) {
  // Runs on every update even if priority didn't change
  notifyPriorityChange(current.priority);
})(current, previous);

// CORRECT: Check if field changed
(function executeRule(current, previous) {
  if (current.priority.changes()) {
    notifyPriorityChange(current.priority);
  }
})(current, previous);

步骤 6：UI 策略验证

验证 UI 策略的配置是否正确，以及操作是否完整。

如果使用 MCP 工具：

Tool: SN-Query-Table
Parameters:
  table_name: sys_ui_policy
  query: sys_id=<ui_policy_sys_id>
  fields: short_description,table,conditions,active,global,inherit

获取 UI 策略操作：

Tool: SN-Query-Table
Parameters:
  table_name: sys_ui_policy_action
  query: ui_policy=<ui_policy_sys_id>
  fields: field,mandatory,visible,disabled

UI 策略验证清单：

检查项	描述	严重性
活动状态	策略处于活动状态	信息
表	有效的表引用	严重
条件	条件有效且可测试	高
存在操作	至少定义了一个操作	高
字段引用	操作所用字段存在于表中	严重
反向处理	策略处理 true 和 false 两种状态	中
顺序	不存在针对相同字段且顺序冲突的策略	中

步骤 7：脚本包含项验证

验证脚本包含项的配置和可访问性是否正确。

如果使用 MCP 工具：

Tool: SN-Query-Table
Parameters:
  table_name: sys_script_include
  query: sys_id=<script_include_sys_id>
  fields: name,api_name,client_callable,access,active,script

脚本包含项验证清单：

检查项	描述	严重性
活动状态	脚本包含项处于活动状态	信息
名称规范	遵循命名规范	中
API 名称	唯一且具描述性	中
客户端可调用	仅在需要时启用（存在安全风险）	高
语法	JavaScript 语法有效	严重
原型模式	使用正确的类模式	中
文档	包含 JSDoc 注释	低
依赖项	引用的脚本包含项均存在	高

步骤 8：ACL 验证

验证访问控制列表的安全配置是否正确。

如果使用 MCP 工具：

Tool: SN-Query-Table
Parameters:
  table_name: sys_security_acl
  query: name=incident
  fields: name,operation,type,active,condition,script,role

ACL 验证清单：

检查项	描述	严重性
活动状态	ACL 处于活动状态	信息
操作	操作类型有效	严重
角色	至少指定一个角色或条件	严重
条件	条件表达式有效	高
脚本	如果使用脚本，则脚本有效	高
覆盖范围	涵盖所有操作	中
继承	正确使用 * ACL	中

步骤 9：生成验证报告

将所有验证结果汇总为一份完整报告。

验证报告模板：

# Configuration Validation Report

## Summary
- Configuration: [Name]
- Type: [Catalog Item / Workflow / Business Rule]
- Date: [Date]
- Validator: [Name]

## Overall Status: [PASS / FAIL / WARNING]

## Detailed Findings

### Critical Issues (Must Fix)
1. [Issue description and remediation]
2. [Issue description and remediation]

### High Priority Issues (Should Fix)
1. [Issue description and remediation]

### Medium Priority Issues (Consider Fixing)
1. [Issue description and remediation]

### Low Priority Issues (Nice to Have)
1. [Issue description and remediation]

## Validation Details

### Component 1: [Name]
- Status: [PASS/FAIL]
- Checks Performed: [List]
- Issues Found: [List]

### Component 2: [Name]
- Status: [PASS/FAIL]
- Checks Performed: [List]
- Issues Found: [List]

## Recommendations
1. [Recommendation]
2. [Recommendation]

## Sign-off
- [ ] All critical issues resolved
- [ ] All high priority issues resolved or documented
- [ ] Configuration approved for deployment

工具用法

MCP Tools（Claude Code/Desktop）

工具	用途	使用时机
SN-Validate-Configuration	全面验证	主要验证工具
SN-Query-Table	查询配置表	详细检查
SN-Get-Table-Schema	了解表结构	验证字段引用

REST API（ChatGPT/Other）

端点	方法	用途
/api/now/table/sc_cat_item	GET	目录项验证
/api/now/table/item_option_new	GET	变量验证
/api/now/table/wf_workflow	GET	工作流验证
/api/now/table/sys_script	GET	业务规则验证
/api/now/table/sys_ui_policy	GET	UI 策略验证
/api/now/table/sys_script_include	GET	脚本包含项验证
/api/now/table/sys_security_acl	GET	ACL 验证

原生工具（Claude Code）

工具	用途
Bash	执行验证脚本
Read	读取验证模板

最佳实践

• 提升前先验证： 在实例之间迁移配置前，务必进行验证
• 使用自动化验证： 在 CI/CD 流水线中实施自动化验证
• 记录例外情况： 记录所有已接受的验证警告
• 使用数据进行测试： 使用真实的测试数据进行验证，而非空记录
• 交叉检查依赖项： 确保目标环境中存在所有引用的对象
• 版本控制： 将验证报告与更新集文档一同保存
• 符合 ITIL： 将验证纳入变更管理流程

故障排除

常见问题 1：验证返回误报

症状： 验证标记的问题在实际使用中运行正常
原因： 验证逻辑未考虑所有有效配置
解决方案： 检查具体的验证规则并添加异常处理

# Check if the "error" is actually valid
Tool: SN-Query-Table
Parameters:
  table_name: <relevant_table>
  query: sys_id=<object_sys_id>
  display_value: all

常见问题 2：目标实例中缺少依赖项

症状： 配置在开发环境中正常运行，但在测试/生产环境中验证失败
原因： 依赖项未包含在更新集中
解决方案： 查询 sys_update_xml 以查找所有相关记录

Tool: SN-Query-Table
Parameters:
  table_name: sys_update_xml
  query: update_set=<update_set_sys_id>
  fields: type,target_name,name

常见问题 3：未检测到脚本语法错误

症状： 无效的 JavaScript 通过验证，但在运行时失败
原因： 基本语法检查无法捕获所有 JavaScript 错误
解决方案： 使用 ServiceNow 的语法检查器或后台脚本测试

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    try {
      eval('<script_content>');
      gs.info('Syntax check passed');
    } catch(e) {
      gs.error('Syntax error: ' + e.message);
    }

常见问题 4：工作流验证超时

症状： 工作流验证耗时过长或失败
原因： 工作流复杂，包含许多活动和转换
解决方案： 将验证拆分为较小的部分

# Validate activities separately
Tool: SN-Query-Table
Parameters:
  table_name: wf_activity
  query: workflow_version.workflow=<sys_id>
  limit: 50
  offset: 0

# Then transitions
Tool: SN-Query-Table
Parameters:
  table_name: wf_transition
  query: workflow_version.workflow=<sys_id>
  limit: 100

示例

示例 1：完整的目录项验证

# Step 1: Get catalog item details
Tool: SN-Query-Table
Parameters:
  table_name: sc_cat_item
  query: sys_id=abc123
  fields: name,short_description,active,category,workflow
  display_value: all

# Result:
name: "New Laptop Request"
active: true
category: "Hardware"
workflow: "Standard Laptop Fulfillment"

# Step 2: Validate variables
Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=abc123
  fields: name,question_text,type,mandatory,reference,order

# Result:
- laptop_type (Select Box, mandatory) - OK
- memory_size (Select Box) - OK
- justification (Multi-line, mandatory) - OK
- manager_approval (Reference to sys_user) - OK

# Step 3: Validate variable choices exist
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question.cat_item=abc123
  fields: question.name,text,value

# Result:
laptop_type choices: Standard, Developer, Executive - OK
memory_size choices: 8GB, 16GB, 32GB - OK

# Step 4: Validate workflow exists and is published
Tool: SN-Query-Table
Parameters:
  table_name: wf_workflow
  query: name=Standard Laptop Fulfillment
  fields: name,published,active

# Result:
published: true
active: true - OK

# Final Status: PASS - All validations passed

示例 2：业务规则性能验证

# Step 1: Get business rule
Tool: SN-Query-Table
Parameters:
  table_name: sys_script
  query: name=Auto Assign Critical Incidents
  fields: name,when,collection,active,script,filter_condition

# Result:
name: "Auto Assign Critical Incidents"
when: "before"
collection: "incident"
filter_condition: "priority=1"
script: (see below)

# Step 2: Analyze script for anti-patterns
Script Content:
```javascript
(function executeRule(current, previous) {
  var gr = new GlideRecord('sys_user_group');
  gr.addQuery('name', 'Critical Incident Team');
  gr.query();
  if (gr.next()) {
    current.assignment_group = gr.sys_id;
  }

  // ISSUE FOUND: GlideRecord query in before rule
  // This runs on EVERY insert of P1 incident
})(current, previous);

步骤 3：生成建议

发现的问题：

1. WARNING：before 规则中的 GlideRecord 查询
   • 影响：创建事件时性能下降
   • 建议：在系统属性中缓存组 sys_id，或使用 gs.getProperty()

建议的修复：

(function executeRule(current, previous) {
  // Use cached value instead of query
  var criticalTeamId = gs.getProperty('x_app.critical_team_sys_id');
  if (criticalTeamId) {
    current.assignment_group = criticalTeamId;
  }
})(current, previous);

最终状态：WARNING - 检测到性能问题

### Example 3: Workflow Dead-End Detection

步骤 1：获取工作流活动

工具：SN-Query-Table 参数： table_name: wf_activity query: workflow_version.workflow=wf123 fields: sys_id,name,activity_definition.name

结果：

• act1: 开始
• act2: 创建任务
• act3: 审批
• act4: 如果已批准（分支）
• act5: 履行请求
• act6: 结束
• act7: 发送拒绝电子邮件

步骤 2：获取所有转换

工具：SN-Query-Table 参数： table_name: wf_transition query: workflow_version.workflow=wf123 fields: from.name,to.name,condition

结果：

• 开始 -> 创建任务
• 创建任务 -> 审批
• 审批 -> 如果已批准
• 如果已批准 -> 履行请求（条件：已批准）
• 如果已批准 -> 发送拒绝电子邮件（条件：已拒绝）
• 履行请求 -> 结束

步骤 3：分析问题

发现问题：活动存在死路

• “发送拒绝邮件”（act7）没有后续转换
• 这会导致工作流在拒绝后卡住

建议：

添加从“发送拒绝邮件”到“结束”的转换

最终状态：失败 - 工作流存在死路活动

### Example 4: ACL Coverage Validation

步骤 1：获取表的所有 ACL

工具：SN-Query-Table 参数： table_name: sys_security_acl query: name=x_app_custom_table fields: name,operation,type,active,admin_overrides,role.name

结果：

• x_app_custom_table (read) - 角色：x_app.user - 已启用
• x_app_custom_table (write) - 角色：x_app.admin - 已启用
• x_app_custom_table (create) - 角色：x_app.admin - 已启用
• x_app_custom_table (delete) - 角色：x_app.admin - 已启用
• x_app_custom_table.* (read) - 角色：x_app.user - 已启用

步骤 2：分析覆盖范围

已覆盖的操作：

• read：是
• write：是
• create：是
• delete：是

字段级 ACL：

• .（所有字段）：是

步骤 3：检查漏洞

发现问题：没有行级限制

• 所有拥有 x_app.user 角色的用户都可以读取所有记录
• 考虑添加记录级安全条件

建议：

如果记录应仅对特定用户可见，请添加条件： created_by=javascript:gs.getUserID()

最终状态：警告 - 请考虑行级安全

## Related Skills

- `admin/schema-discovery` - Understanding table structures for validation
- `admin/update-set-management` - Managing validated configurations
- `admin/batch-operations` - Fixing validation issues in bulk
- `admin/deployment-workflow` - Deploying validated configurations

## References

- [ServiceNow Instance Scan](https://docs.servicenow.com/bundle/utah-application-development/page/build/instance-scan/concept/instance-scan.html)
- [Catalog Item Best Practices](https://docs.servicenow.com/bundle/utah-servicenow-platform/page/product/service-catalog-management/concept/c_ServiceCatalogBestPractices.html)
- [Workflow Best Practices](https://docs.servicenow.com/bundle/utah-servicenow-platform/page/administer/workflow-administration/concept/c_WorkflowBestPractices.html)
- [Business Rule Best Practices](https://docs.servicenow.com/bundle/utah-application-development/page/script/server-scripting/concept/c_BusinessRuleBestPractices.html)
- [ACL Best Practices](https://docs.servicenow.com/bundle/utah-platform-security/page/administer/contextual-security/concept/access-control-best-practices.html)