update-set-workflow

ServiceNow 更新集工作流

更新集对于跟踪 ServiceNow 开发中的更改是强制要求。如果没有更新集，更改就不会被跟踪，也无法部署到其他实例。

此外，工具层也会强制执行此要求：当会话中没有活动更新集时，会阻止配置写入。遇到此阻止时，请询问用户是否要将工作记录到命名更新集中，然后调用一次 snow_ensure_active_update_set({ name }) 并重试。只有在用户明确拒绝跟踪时，才使用 __skipUpdateSet: true 再次调用一次——此选择会在本次会话的剩余时间内生效。

开始任何开发之前

务必先创建或确保有一个活动更新集，再进行更改：

// Step 1: Check current Update Set
var current = await snow_update_set_query({ action: "current" })

// Step 2: If no Update Set or using Default, create one
if (!current || current.name === "Default") {
  await snow_update_set_manage({
    action: "create",
    name: "Feature: [Descriptive Name]",
    description: "What and why this change is being made",
  })
}

// Step 3: Now safe to make changes
// All changes will be tracked!

// Step 4: When done, complete the Update Set
await snow_update_set_manage({
  action: "complete",
  update_set_id: current.sys_id,
})

更新集命名约定

类型	格式	示例
功能	Feature: [Name]	Feature: Incident Auto-Assignment
Bug 修复	Fix: [Issue]	Fix: Approval Email Not Sending
增强	Enhancement: [Name]	Enhancement: Dashboard Performance
紧急修复	Hotfix: [Issue]	Hotfix: Critical Login Bug

更新集生命周期

1. 进行中 - 活动状态，接收更改
2. 已完成 - 可供导出/推广
3. 忽略 - 更改不会被推广（用于实验）

跟踪的内容

更新集会自动捕获以下更改：

• 表和列
• 业务规则
• 脚本包含项
• 客户端脚本
• UI 策略和操作
• 工作流和 Flow Designer 流
• Service Portal 小组件和页面
• ACL 和安全规则
• 系统属性
• 计划作业
• 以及更多……

不会跟踪的内容

• 数据记录（数据请使用 Import Sets）
• 记录上的附件
• 用户会话信息
• 某些系统表（sys_user 等）

更新集 MCP 工具

// Create new Update Set
snow_update_set_manage({
  action: "create",
  name: "Feature: My Feature",
  description: "Description of changes",
})

// Switch to existing Update Set
snow_update_set_manage({
  action: "switch",
  update_set_id: "sys_id_here",
})

// Get current Update Set
snow_update_set_query({ action: "current" })

// Complete Update Set
snow_update_set_manage({
  action: "complete",
  update_set_id: "sys_id_here",
})

// Export Update Set as XML
snow_update_set_manage({
  action: "export",
  update_set_id: "sys_id_here",
})

最佳实践

1. 每个更新集只包含一个功能 - 不要混入无关更改
2. 使用描述性名称 - 清楚说明更新集包含的内容
3. 完成后及时结束 - 不要让更新集无限期保持打开状态
4. 完成前进行测试 - 确认所有更改都能正常工作
5. 切勿使用 Default - 始终创建命名更新集

OAuth 上下文与更新集跟踪

Serac 使用 OAuth 服务帐户进行身份验证。 所有 API 调用都以 OAuth 服务帐户的身份运行，而不是以你的 UI 用户身份运行。更新集必须对进行更改的用户设为“当前”——对于 API 更改，这意味着对服务帐户设为当前。

两种上下文

┌─────────────────────────────────────────────────────────────┐
│ YOUR UI SESSION (when you log in to ServiceNow UI)         │
│ User: john.doe                                              │
│ Current Update Set: [Whatever you selected in the UI]      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ SERAC OAUTH SESSION (API calls)                             │
│ User: oauth.service.account                                 │
│ Current Update Set: [Set via Update Set tools]             │
│ ← All Serac changes are tracked here                        │
└─────────────────────────────────────────────────────────────┘

auto_switch — 跟踪的必需设置

• auto_switch=true（默认） — 更新集会设为服务帐户的当前更新集，所有更改都会被跟踪 ✅
• auto_switch=false — 更改不会被跟踪。仅用于查询/分析，绝不可用于开发。

要点

• ✅ 会创建更新集 — 它们存在于 ServiceNow 中
• ✅ auto_switch=true 时会跟踪更改 — 所有 Serac 工件都会自动放入更新集
• ❌ 不会显示在你的 UI 会话中，除非你提供 servicenow_username 参数（这也会将其设为该 UI 用户的当前更新集）
• ✅ 仍可部署 — 更新集可以照常导出/导入
• ⚠️ 开发任务不要禁用 auto_switch

何时使用 servicenow_username

此参数为可选参数。如果希望更新集也显示为 UI 会话中的当前更新集，可以传入你的 ServiceNow 用户名——当你在使用 Serac 的同时也在 ServiceNow UI 中操作，并希望两处选中同一个更新集时，这会很方便。它不会影响跟踪；跟踪由 auto_switch 控制。