schema-discovery

架构发现

概述

架构发现是高效 ServiceNow 开发的基础。本技能将教你如何探索表结构、了解字段类型、发现表之间的关系，并记录发现结果以供开发使用。

• 解决什么问题？ 消除使用陌生表时的猜测，避免字段类型错误，并揭示 ServiceNow 实体之间隐藏的关系
• 谁应该使用本技能？ 在创建查询、脚本或集成之前，需要了解 ServiceNow 数据结构的开发人员、管理员和集成工程师
• 预期成果是什么？ 全面了解表架构、字段配置、引用关系以及字段的正确用法

前提条件

• 所需的 ServiceNow 角色：admin 或 personalize_dictionary（用于完整的架构访问权限）
• 对 sys_dictionary、sys_db_object 和 sys_documentation 表具有读取权限
• 基本了解 ServiceNow 表层次结构和字段类型
• 相关技能：无需其他技能（本技能为基础技能）

流程

步骤 1：发现可用表

首先，探索 ServiceNow 实例中有哪些可用表。表会根据其功能归类。

如果使用 MCP 工具：

Tool: SN-List-Available-Tables
Parameters:
  category: core_itsm

可用类别：

• core_itsm - 事件、问题、变更、请求
• cmdb - 配置管理数据库表
• service_catalog - 服务目录项目、变量、请求
• security - 用户、组、角色、ACL
• system - 系统属性、计划作业、更新集
• custom - 自定义应用表（x_* 前缀）

如果使用 REST API：

GET /api/now/table/sys_db_object?sysparm_query=super_class.name=task^ORsuper_class.name=cmdb_ci&sysparm_fields=name,label,super_class&sysparm_limit=50

决策点：

• 如果要查找 ITSM 表 → 使用类别 core_itsm
• 如果要探索 CMDB → 使用类别 cmdb
• 如果要处理自定义应用 → 使用类别 custom，或按范围前缀查询

步骤 2：获取表架构

确定表后，检索其完整架构，包括所有字段、类型和配置。

如果使用 MCP 工具：

Tool: SN-Get-Table-Schema
Parameters:
  table_name: incident

如果使用 REST API：

GET /api/now/table/sys_dictionary?sysparm_query=name=incident^internal_type!=collection&sysparm_fields=element,column_label,internal_type,max_length,mandatory,reference

预期响应字段：

字段	说明
element	内部字段名称
column_label	显示标签
internal_type	字段类型（string、reference、integer 等）
max_length	最大字符长度
mandatory	字段是否必填
reference	引用字段的目标表
default_value	默认值（如有）
choice	字段是否使用选项列表

步骤 3：通过关系深入发现架构

对于复杂集成，发现完整的关系映射，包括父表、子表和引用链。

如果使用 MCP 工具：

Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_relationships: true
  depth: 2

如果使用 REST API：

# Get table hierarchy (parent/child)
GET /api/now/table/sys_db_object?sysparm_query=name=incident&sysparm_fields=name,super_class,label

# Get all reference fields
GET /api/now/table/sys_dictionary?sysparm_query=name=incident^internal_type=reference&sysparm_fields=element,reference

# Get tables that reference this table
GET /api/now/table/sys_dictionary?sysparm_query=reference=incident&sysparm_fields=name,element

要发现的关系类型：

关系	说明	示例
继承	父表层次结构	incident 扩展 task
引用	外键关系	incident.assigned_to -> sys_user
Glide 列表	多值引用	incident.watch_list -> sys_user（列表）
文档 ID	动态表引用	sys_attachment.table_sys_id

步骤 4：了解字段类型

不同字段类型的行为、存储特性和查询语法各不相同。

常见的 ServiceNow 字段类型：

类型代码	类型名称	说明	查询示例
string	字符串	文本，长度不超过 max_length	short_description=test
integer	整数	整数	priority=1
boolean	真/假	布尔值	active=true
reference	引用	指向另一张表的外键	assigned_to.name=admin
glide_date	日期	仅日期	due_date>2024-01-01
glide_date_time	日期/时间	日期和时间	sys_created_on>=javascript:gs.daysAgo(7)
choice	选项	预定义选项	state=1
journal	日志	仅追加的文本	无法直接查询
journal_input	日志输入	工作备注/评论	work_notesLIKEupdate
script	脚本	JavaScript 代码	不适用
conditions	条件	编码查询	不适用

步骤 5：获取字段文档

对于不熟悉的字段，请获取详细文档，其中包含用法示例和最佳实践。

如果使用 MCP 工具：

Tool: SN-Explain-Field
Parameters:
  table_name: incident
  field_name: impact

如果使用 REST API：

# Get field definition
GET /api/now/table/sys_dictionary?sysparm_query=name=incident^element=impact&sysparm_fields=element,column_label,internal_type,comments,hint

# Get field documentation
GET /api/now/table/sys_documentation?sysparm_query=name=incident^element=impact&sysparm_fields=text,short_description

文档包含：

• 字段用途和业务含义
• 有效值（针对选项字段）
• 相关字段和依赖关系
• 常见用例
• API 行为说明

步骤 6：探索选项值

对于选项字段（下拉菜单），请查找所有有效值及其含义。

如果使用 MCP 工具：

Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=incident^element=state
  fields: value,label,sequence

如果使用 REST API：

GET /api/now/table/sys_choice?sysparm_query=name=incident^element=state&sysparm_fields=value,label,sequence&sysparm_orderby=sequence

常见选项表：

表	用途
sys_choice	标准字段选项
question_choice	目录变量选项
sys_choice_set	可重复使用的选项集

步骤 7：记录发现

为开发工作创建架构参考文档。

架构文档模板：

## Table: incident

### Hierarchy
- Parent: task
- Children: None

### Key Fields
| Field | Type | Required | Reference | Notes |
|-------|------|----------|-----------|-------|
| number | string | auto | - | Auto-generated |
| short_description | string | yes | - | Max 160 chars |
| assigned_to | reference | no | sys_user | Can be empty |
| state | integer | yes | - | Choice: 1-8 |

### State Values
| Value | Label |
|-------|-------|
| 1 | New |
| 2 | In Progress |
| 3 | On Hold |
| 6 | Resolved |
| 7 | Closed |
| 8 | Canceled |

### Key Relationships
- assignment_group -> sys_user_group
- caller_id -> sys_user
- cmdb_ci -> cmdb_ci
- problem_id -> problem

工具用法

MCP 工具（Claude Code/Desktop）

工具	用途	使用时机
SN-List-Available-Tables	按类别列出表	开始探索时
SN-Get-Table-Schema	获取字段定义	了解表结构时
SN-Discover-Table-Schema	深入发现关系	复杂集成时
SN-Explain-Field	获取字段文档	遇到不熟悉的字段时
SN-Query-Table	查询 sys_choice、sys_dictionary	自定义架构查询时

REST API（ChatGPT/其他）

端点	方法	用途
/api/now/table/sys_db_object	GET	列出表
/api/now/table/sys_dictionary	GET	获取字段定义
/api/now/table/sys_choice	GET	获取选项值
/api/now/table/sys_documentation	GET	获取字段文档
/api/now/table/sys_glide_object	GET	获取字段类型定义

原生工具（Claude Code）

工具	用途
Bash	执行 curl 命令以调用 REST API
Read	读取缓存的架构文件

最佳实践

• 缓存架构信息： 架构很少变化——在本地缓存结果，以减少 API 调用
• 从父表开始： 先了解 task，再了解 incident；先了解 cmdb_ci，再了解 cmdb_ci_computer
• 同时检查 sys_dictionary 和 sys_db_object： Dictionary 包含字段，db_object 包含表元数据
• 记录引用链： incident -> assignment_group -> sys_user_group 有助于点遍历
• 先在开发环境中验证： 由于自定义配置，不同实例的架构可能有所不同
• 使用编码查询构建器： 在编写查询代码之前，先在 ServiceNow UI 中测试查询

故障排除

常见问题 1：架构中缺少字段

症状： 预期的字段未出现在架构结果中 原因： 字段可能位于父表中，而非子表中 解决方案： 查询父表，或使用带有 depth 参数的 SN-Discover-Table-Schema

Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_parent_fields: true

常见问题 2：对 sys_dictionary 的访问被拒绝

症状： 查询 sys_dictionary 时出现 403 错误 原因： 缺少 personalize_dictionary 或 admin 角色 解决方案： 申请相应角色，或使用针对特定表的端点

# Alternative: Use table API with schema
GET /api/now/table/incident?sysparm_limit=1&sysparm_display_value=all
# Response headers include field metadata

常见问题 3：引用字段显示 sys_id 而非值

症状： 引用字段返回的是 sys_id，而非显示值 原因： 未使用 sysparm_display_value 参数 解决方案： 在查询中添加 display_value 参数

Tool: SN-Query-Table
Parameters:
  table_name: incident
  display_value: all

常见问题 4：未找到选项值

症状： 对选项字段查询时，sys_choice 返回空结果 原因： 字段使用选项集，或定义方式不同 解决方案： 检查 sys_choice_set，或使用依赖值进行查询

Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=incident^element=subcategory^dependent_value=network

示例

示例 1：发现 CMDB 计算机架构

# Step 1: List CMDB tables
Tool: SN-List-Available-Tables
Parameters:
  category: cmdb

# Result: Lists cmdb_ci, cmdb_ci_computer, cmdb_ci_server, etc.

# Step 2: Get cmdb_ci_computer schema
Tool: SN-Get-Table-Schema
Parameters:
  table_name: cmdb_ci_computer

# Result:
Fields:
- cpu_core_count (integer)
- cpu_count (integer)
- cpu_speed (float)
- disk_space (float)
- ram (integer)
- os (string)
- os_version (string)
- serial_number (string)
- [inherited from cmdb_ci: name, ip_address, manufacturer, etc.]

# Step 3: Understand OS field
Tool: SN-Explain-Field
Parameters:
  table_name: cmdb_ci_computer
  field_name: os

# Result:
- Type: String
- Label: Operating System
- Description: Operating system name
- Common values: Windows, Linux, macOS
- Related field: os_version

示例 2：映射事件引用关系

# Discover all relationships from incident table
Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_relationships: true
  depth: 2

# Result:
Table: incident
Extends: task

Reference Fields:
- assigned_to -> sys_user
  - sys_user.manager -> sys_user (depth 2)
  - sys_user.department -> cmn_department (depth 2)
- assignment_group -> sys_user_group
  - sys_user_group.manager -> sys_user (depth 2)
  - sys_user_group.parent -> sys_user_group (depth 2)
- caller_id -> sys_user
- cmdb_ci -> cmdb_ci
  - cmdb_ci.location -> cmn_location (depth 2)
  - cmdb_ci.support_group -> sys_user_group (depth 2)
- problem_id -> problem
- rfc -> change_request

Reverse References (tables referencing incident):
- incident_sla.task -> incident
- incident_alert.incident -> incident
- sc_task.incident -> incident

示例 3：目录变量架构发现

# Step 1: Get catalog variable types
Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=item_option_new^element=type
  fields: value,label

# Result:
- 1: Yes/No
- 2: Multi Line Text
- 3: Multiple Choice
- 4: Numeric Scale
- 5: Select Box
- 6: Single Line Text
- 7: CheckBox
- 8: Reference
- 9: Date
- 10: Date/Time
- etc.

# Step 2: Understand variable definition structure
Tool: SN-Get-Table-Schema
Parameters:
  table_name: item_option_new

# Result:
- name (string): Variable name
- question_text (string): Label shown to user
- type (integer): Variable type from above
- reference (string): For type 8, target table
- cat_item (reference): Parent catalog item
- order (integer): Display sequence
- mandatory (boolean): Required field

示例 4：自定义应用表发现

# List custom tables in specific scope
Tool: SN-Query-Table
Parameters:
  table_name: sys_db_object
  query: nameSTARTSWITHx_myapp_
  fields: name,label,super_class

# Result:
- x_myapp_request (label: My App Request, extends: task)
- x_myapp_config (label: Configuration, extends: none)
- x_myapp_log (label: Activity Log, extends: none)

# Get schema for custom table
Tool: SN-Get-Table-Schema
Parameters:
  table_name: x_myapp_request

# Discover custom table relationships
Tool: SN-Discover-Table-Schema
Parameters:
  table_name: x_myapp_request
  include_relationships: true

相关技能

• admin/update-set-management - 在开发过程中管理更新集
• admin/batch-operations - 利用架构知识创建多条记录
• development/business-rules - 编写使用已发现字段的脚本
• development/scripted-rest-apis - 基于架构构建集成

参考资料

• ServiceNow 表管理
• 字典条目
• 字段类型参考
• 表层级与继承