smart-documents

智能文档

概述

此技能提供了一种在 ServiceNow Document Intelligence 中管理智能文档的结构化方法。它可帮助你：

• 在 sn_doc_management 中创建和管理文档记录，并进行完整的生命周期跟踪
• 在 sn_doc_template 中配置文档模板，为常见文档类型提供可复用的结构
• 使用 sn_doc_version 实施版本控制，以跟踪文档修订并维护审计历史
• 通过 sn_doc_approval 和 sysapproval_approver 设置审批工作流，以便审核和签署文档
• 在 sn_doc_merge_field 中定义合并字段，以便根据 ServiceNow 数据自动生成内容
• 通过 sn_doc_distribution 管理文档分发，实现受控共享与交付

适用场景： 创建标准化文档（政策、SOP、合同、合规报告）时；文档发布前需要版本控制和审批时；或者需要使用 ServiceNow 记录中的动态数据生成文档时。

所需插件： com.sn_doc_intelligence

先决条件

• 角色： sn_doc_management_admin、sn_doc_management_user、document_management 或 admin
• 访问权限： 对 sn_doc_management、sn_doc_template、sn_doc_version、sn_doc_approval 和 sys_attachment 表具有读写权限
• 知识： 了解组织的文档治理政策、审批层级和分发要求
• 插件： 必须激活 Document Intelligence（com.sn_doc_intelligence）

操作步骤

第 1 步：创建或选择文档模板

模板定义每种文档类型的结构、合并字段和默认内容。

查询现有模板：

使用 MCP（Claude Code/Desktop）：

Tool: SN-Query-Table
Parameters:
  table_name: sn_doc_template
  query: active=true^document_typeLIKEpolicy^ORdocument_typeLIKEcontract^ORdocument_typeLIKEreport
  fields: sys_id,name,description,document_type,category,version,state,merge_field_count,approval_required
  limit: 25
  order_by: name

使用 REST API：

GET /api/now/table/sn_doc_template?sysparm_query=active=true^ORDERBYname&sysparm_fields=sys_id,name,description,document_type,category,version,state,merge_field_count,approval_required&sysparm_limit=25&sysparm_display_value=true

创建新模板：

使用 MCP：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_template
  fields:
    name: "IT Security Policy Template"
    description: "Standard template for IT security policies with approval workflow. Includes merge fields for department, effective date, and policy owner."
    document_type: policy
    category: information_security
    approval_required: true
    approval_group: [security_governance_group_sys_id]
    version: "1.0"
    state: draft
    active: true

使用 REST API：

POST /api/now/table/sn_doc_template
Content-Type: application/json

{
  "name": "IT Security Policy Template",
  "description": "Standard template for IT security policies with approval workflow",
  "document_type": "policy",
  "category": "information_security",
  "approval_required": "true",
  "approval_group": "[security_governance_group_sys_id]",
  "version": "1.0",
  "state": "draft",
  "active": "true"
}

第 2 步：定义合并字段

配置合并字段，以便将 ServiceNow 记录中的动态数据填入文档。

使用 MCP：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_merge_field
  fields:
    template: [template_sys_id]
    field_name: "department_name"
    display_label: "Department Name"
    source_table: cmn_department
    source_field: name
    placeholder: "{{department_name}}"
    field_type: reference
    required: true
    order: 100

各类文档的常见合并字段：

文档类型	合并字段	源表	源字段	占位符
政策	部门	cmn_department	name	{{department_name}}
政策	生效日期	（手动）	（日期）	{{effective_date}}
政策	政策负责人	sys_user	name	{{policy_owner}}
政策	审核日期	（计算得出）	（日期）	{{next_review_date}}
合同	供应商名称	core_company	name	{{vendor_name}}
合同	合同金额	ast_contract	total_cost	{{contract_value}}
合同	开始日期	ast_contract	starts	{{start_date}}
合同	结束日期	ast_contract	ends	{{end_date}}
报告	报告周期	（手动）	（字符串）	{{report_period}}
报告	作者	sys_user	name	{{author_name}}
报告	生成日期	（系统）	（日期时间）	{{generated_date}}

使用 REST API：

POST /api/now/table/sn_doc_merge_field
Content-Type: application/json

{
  "template": "[template_sys_id]",
  "field_name": "department_name",
  "display_label": "Department Name",
  "source_table": "cmn_department",
  "source_field": "name",
  "placeholder": "{{department_name}}",
  "field_type": "reference",
  "required": "true",
  "order": "100"
}

第 3 步：根据模板创建文档

根据模板生成新的文档实例，并使用实际数据填充合并字段。

使用 MCP：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_management
  fields:
    short_description: "IT Security Policy - Remote Access - Engineering Department"
    template: [template_sys_id]
    document_type: policy
    category: information_security
    department: [department_sys_id]
    owner: [policy_owner_sys_id]
    effective_date: "2026-04-01"
    review_date: "2027-04-01"
    state: draft
    version: "1.0"
    confidentiality: internal

使用 REST API：

POST /api/now/table/sn_doc_management
Content-Type: application/json

{
  "short_description": "IT Security Policy - Remote Access - Engineering Department",
  "template": "[template_sys_id]",
  "document_type": "policy",
  "category": "information_security",
  "department": "[department_sys_id]",
  "owner": "[policy_owner_sys_id]",
  "effective_date": "2026-04-01",
  "review_date": "2027-04-01",
  "state": "draft",
  "version": "1.0",
  "confidentiality": "internal"
}

第 4 步：管理文档版本

跟踪修订并维护版本历史。

编辑时创建新版本：

使用 MCP：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_version
  fields:
    document: [document_sys_id]
    version_number: "1.1"
    change_description: "Updated remote access VPN requirements per security audit findings. Added MFA requirement for all remote connections."
    author: [editor_sys_id]
    state: draft
    previous_version: [previous_version_sys_id]
    attachment: [updated_attachment_sys_id]

查询版本历史：

Tool: SN-Query-Table
Parameters:
  table_name: sn_doc_version
  query: document=[document_sys_id]
  fields: sys_id,version_number,change_description,author,state,sys_created_on,attachment,previous_version
  limit: 20
  order_by: -sys_created_on

使用 REST API：

# Create new version
POST /api/now/table/sn_doc_version
Content-Type: application/json

{
  "document": "[document_sys_id]",
  "version_number": "1.1",
  "change_description": "Updated remote access VPN requirements",
  "author": "[editor_sys_id]",
  "state": "draft",
  "previous_version": "[previous_version_sys_id]"
}

# Get version history
GET /api/now/table/sn_doc_version?sysparm_query=document=[document_sys_id]^ORDERBYDESCsys_created_on&sysparm_fields=sys_id,version_number,change_description,author,state,sys_created_on&sysparm_limit=20&sysparm_display_value=true

第 5 步：提交审批

将文档提交至已配置的审批工作流。

使用 MCP：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_approval
  fields:
    document: [document_sys_id]
    document_version: [version_sys_id]
    approval_type: sequential
    state: requested
    short_description: "Approval required: IT Security Policy v1.1 - Remote Access"
    comments: "Updated policy requires approval from Security Governance and CISO before publication."

然后创建单独的审批人记录：

Tool: SN-Create-Record
Parameters:
  table_name: sysapproval_approver
  fields:
    sysapproval: [approval_sys_id]
    approver: [approver_sys_id]
    state: requested
    order: 100
    comments: "Please review the updated remote access policy. Key changes: MFA requirement added for all VPN connections."

使用 REST API：

POST /api/now/table/sn_doc_approval
Content-Type: application/json

{
  "document": "[document_sys_id]",
  "document_version": "[version_sys_id]",
  "approval_type": "sequential",
  "state": "requested",
  "short_description": "Approval required: IT Security Policy v1.1"
}

监控审批状态：

Tool: SN-Query-Table
Parameters:
  table_name: sysapproval_approver
  query: sysapproval=[approval_sys_id]
  fields: sys_id,approver,state,comments,sys_updated_on,order
  limit: 10
  order_by: order

第 6 步：发布并更新文档状态

审批通过后，发布文档并更新其状态。

使用 MCP：

Tool: SN-Update-Record
Parameters:
  table_name: sn_doc_management
  sys_id: [document_sys_id]
  data:
    state: published
    version: "1.1"
    published_date: "2026-03-19"
    work_notes: "Document approved by Security Governance (2026-03-17) and CISO (2026-03-19). Published as version 1.1."

更新版本记录：

Tool: SN-Update-Record
Parameters:
  table_name: sn_doc_version
  sys_id: [version_sys_id]
  data:
    state: published

使用 REST API：

PATCH /api/now/table/sn_doc_management/[document_sys_id]
Content-Type: application/json

{
  "state": "published",
  "version": "1.1",
  "published_date": "2026-03-19",
  "work_notes": "Approved and published as version 1.1."
}

第 7 步：配置文档分发

设置受控分发，确保文档发送给正确的受众。

使用 MCP：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_distribution
  fields:
    document: [document_sys_id]
    distribution_type: group
    recipient_group: [engineering_group_sys_id]
    delivery_method: email_notification
    notify_on_update: true
    acknowledgment_required: true
    acknowledgment_deadline: "2026-04-15"
    short_description: "Distribute IT Security Policy v1.1 to Engineering"

使用 REST API：

POST /api/now/table/sn_doc_distribution
Content-Type: application/json

{
  "document": "[document_sys_id]",
  "distribution_type": "group",
  "recipient_group": "[engineering_group_sys_id]",
  "delivery_method": "email_notification",
  "notify_on_update": "true",
  "acknowledgment_required": "true",
  "acknowledgment_deadline": "2026-04-15"
}

跟踪确认情况：

Tool: SN-Query-Table
Parameters:
  table_name: sn_doc_distribution
  query: document=[document_sys_id]
  fields: sys_id,recipient_group,recipient_user,delivery_method,acknowledged,acknowledged_date,acknowledgment_deadline
  limit: 50

第 8 步：监控文档生命周期

跟踪即将到达审核日期或需要更新的文档。

使用 MCP：

Tool: SN-Query-Table
Parameters:
  table_name: sn_doc_management
  query: state=published^review_date<=javascript:gs.daysAgoEnd(-30)^review_date>=javascript:gs.beginningOfToday()
  fields: sys_id,number,short_description,document_type,owner,review_date,version,department
  limit: 25
  order_by: review_date

使用 REST API：

GET /api/now/table/sn_doc_management?sysparm_query=state=published^review_dateBETWEENjavascript:gs.beginningOfToday()@javascript:gs.daysAgoEnd(-30)^ORDERBYreview_date&sysparm_fields=sys_id,number,short_description,document_type,owner,review_date,version,department&sysparm_limit=25&sysparm_display_value=true

生成生命周期报告：

Tool: SN-Add-Work-Notes
Parameters:
  table_name: sn_doc_management
  sys_id: [document_sys_id]
  work_notes: |
    === DOCUMENT LIFECYCLE STATUS ===
    Document: [number] - [short_description]
    Current Version: [version]
    State: Published
    Owner: [owner]

    VERSION HISTORY:
    - v1.0 (2026-01-15) - Initial publication
    - v1.1 (2026-03-19) - Updated MFA requirements

    APPROVAL HISTORY:
    - v1.0: Approved by Security Governance (2026-01-12), CISO (2026-01-14)
    - v1.1: Approved by Security Governance (2026-03-17), CISO (2026-03-19)

    DISTRIBUTION:
    - Engineering: 45/50 acknowledged (90%)
    - IT Operations: 28/30 acknowledged (93%)
    - Outstanding: 7 users past deadline

    NEXT REVIEW: 2027-04-01 (378 days)
    ACTION: Schedule review kickoff for 2027-02-01

工具用法

MCP 工具参考

工具	使用时机
SN-Natural-Language-Search	按描述或内容关键词查找文档
SN-Query-Table	查询文档、模板、版本、审批和分发记录
SN-Get-Record	检索特定文档或模板记录
SN-Create-Record	创建文档、版本、审批、分发记录和合并字段
SN-Update-Record	更新文档状态、发布文档或归档文档
SN-Add-Work-Notes	记录文档生命周期事件和审核备注

REST API 参考

端点	方法	用途
/api/now/table/sn_doc_management	GET/POST/PATCH	管理文档记录
/api/now/table/sn_doc_template	GET/POST	管理文档模板
/api/now/table/sn_doc_version	GET/POST/PATCH	跟踪文档版本
/api/now/table/sn_doc_approval	GET/POST	管理文档审批
/api/now/table/sn_doc_distribution	GET/POST	管理分发列表
/api/now/table/sn_doc_merge_field	GET/POST	配置合并字段
/api/now/table/sysapproval_approver	GET/POST	管理单个审批人
/api/now/table/sys_attachment	GET	访问文档文件附件

最佳实践

• 模板治理： 维护集中式的已批准模板库；仅允许文档管理管理员创建模板
• 版本规范： 切勿覆盖已发布的版本；始终创建新的版本记录，以保留审计轨迹
• 有意义的变更说明： 每个版本都必须清楚说明变更内容及原因，不能只写“已更新文档”
• 分发前审批： 切勿分发尚未完成审批工作流的文档
• 确认情况跟踪： 对于合规性关键文档（政策、流程），要求接收方确认并跟踪完成率
• 审核周期： 根据文档类型设定审核日期：政策每年审核一次，流程每半年审核一次，标准每季度审核一次
• 保密级别分类： 为每份文档标记保密级别（公开、内部、机密、受限），以控制访问权限
• 合并字段验证： 发布模板前，使用示例数据测试所有合并字段，确保正确呈现

故障排除

“模板合并字段未填充”

原因： 文档内容中的合并字段占位符与 sn_doc_merge_field 中配置的 placeholder 值不匹配 解决方案： 确认占位符使用完全匹配的语法（例如，{{department_name}}）。检查是否存在多余空格或编码问题。使用 template=[template_sys_id] 查询 sn_doc_merge_field，确认字段配置。

“审批工作流未触发”

原因： 模板的 approval_required 标志未设置，或未配置审批组 解决方案： 确认模板已设置 approval_required=true，且 approval_group 有效。检查审批组是否包含具有 approver_user 角色的活跃成员。

“文档版本冲突”

原因： 两名用户同时编辑同一文档，或创建新版本时未锁定先前版本 解决方案： 查询该文档的 sn_doc_version，找出相互冲突的草稿。使用文档的 state 字段实现签出/锁定机制（编辑时将其设为 checked_out）。

“未发送分发通知”

**原因：**缺少电子邮件通知配置，或收件人组中没有启用电子邮件的成员 **解决方案：**确认 sysevent_email_action 中存在通知模板，且事件名称与分发触发条件匹配。检查 sys_user 记录中的收件人是否有有效的电子邮件地址。

“找不到文档附件”

**原因：**附件可能关联到版本记录，而非文档记录 **解决方案：**使用 table_name=sn_doc_management^table_sys_id=[doc_sys_id] 和 table_name=sn_doc_version^table_sys_id=[version_sys_id] 查询 sys_attachment，以查找所有相关文件。

示例

示例 1：创建并发布安全策略

输入：“为财务部门创建新的数据分类策略”

流程：

1. 选择模板：“IT 安全策略模板”
2. 使用合并字段创建文档：Department=Finance、Owner=CISO、Effective=2026-04-01
3. 上传草稿内容作为附件
4. 创建版本 1.0
5. 提交审批：安全治理部门，然后是 CISO
6. 审批通过后，发布并分发给财务部门
7. 要求在 30 天内确认

示例 2：更新现有流程文档

输入：“更新事件响应流程，加入勒索软件应对手册”

流程：

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_version
  fields:
    document: [ir_procedure_sys_id]
    version_number: "3.2"
    change_description: "Added ransomware response playbook (Section 7). Updated escalation matrix to include Cyber Insurance carrier notification. Revised recovery time objectives per 2026 BCP update."
    author: [security_analyst_sys_id]
    state: draft
    previous_version: [v31_sys_id]

示例 3：自动生成合同文档

输入：“根据模板为供应商入驻生成一份 NDA 文档”

流程：

1. 选择模板：“双向 NDA 模板”
2. 从 core_company 和 sys_user 填充合并字段：
   • {{vendor_name}}：“TechPartners Inc”
   • {{vendor_address}}：“123 Innovation Blvd, Austin, TX”
   • {{effective_date}}：“2026-03-19”
   • {{term_length}}：“2 years”
   • {{company_signatory}}：“Jane Smith, VP Legal”
3. 生成文档，创建版本 1.0
4. 提交法务审批
5. 审批通过后，通过安全链接分发给供应商

Tool: SN-Create-Record
Parameters:
  table_name: sn_doc_management
  fields:
    short_description: "Mutual NDA - TechPartners Inc - Vendor Onboarding"
    template: [nda_template_sys_id]
    document_type: contract
    category: nda
    state: draft
    version: "1.0"
    confidentiality: confidential
    related_record_table: core_company
    related_record: [vendor_sys_id]

相关技能

• document/document-extraction - 从上传的文档中提取结构化数据
• legal/contract-analysis - 分析生成的合同文档，评估风险
• legal/contract-obligation-extraction - 从合同文档中提取义务
• catalog/approval-workflows - 为文档流程配置审批工作流
• admin/workflow-creation - 构建自定义文档生命周期工作流