用途:撤销已写入 ServiceNow 实例的配置变更。当业务规则脚本、Portal 组件服务端脚本或 Script Include 被改错时,实例已在 sys_update_version 中保存了变更前状态,恢复流程是读取、复制、写回,而非凭记忆重建。
主要能力与用法:
- 先确认改动范围。可用 snow_update_set_manage action="preview" 按记录列出变更,或用 snow_inspect_mutations 读取 sys_audit。注意 sys_audit 存储的值会被截断(约 255 字符),只能用于诊断,不能作为恢复来源;Flow Designer 的改动不记录在 sys_audit。
- 查询版本记录。sys_update_version 按 update name 索引,多数记录为 <table>_<sys_id>,可用 snow_query_table 以 nameLIKE<record_sys_id> 查询,按 sys_created_on 降序查看候选行,关注 state(Current/Previous/History)、source、sys_created_by。History 表示该版本未在本实例加载过。时间戳精度为秒,同秒写入需结合其他字段判断。
- 读取完整 payload。必须设置 truncate_output: false,否则只得到前 200 字符的截断内容。payload 为更新 XML,恢复时只取被改坏的单个字段,去掉 CDATA 包裹并保留原文,XML 转义值需先解码;不要把整个 payload 转为字段映射写入。
- 写回。使用 snow_artifact_manage action="update"。若没有活动 update set,需先调用 snow_ensure_active_update_set;对生产实例默认阻止,需用户确认后加 "__confirmProd": true。该工具仅内联读取 script、template、server_script、client_script、css、option_schema、description、active,其余字段(如 condition、when、order)需放在 config 中。Portal 组件应恢复 script 而非 server_script。
- 验证。回写后可用 snow_query_table 对比首尾行,注意写入路径会规范化换行与控制字符,行尾差异属正常。恢复本身也会生成新的版本记录并进入当前 update set。
适用场景:单个配置记录的单字段恢复;已提交 update set 的整体回退需在 ServiceNow UI 中用 Back out 操作完成;已删除记录、已发送邮件、已执行的流程及被删列销毁的数据无法由此撤销。
限制:不要使用 snow_rollback_deployment,其 revert 解析无法处理 CDATA、可能写入未解码实体,且会盲目选取版本,可能静默破坏记录;create_backup 与 add_artifact 也不构成可靠备份。记录若不以 sys_id 作为 update name,需在 UI 的 Versions 相关列表中使用 Revert to this version,该操作无 REST 端点。回退到较早的 baseline 版本不受支持。