创建文档模板
本单元学习 OmniStudio 文档生成的三种令牌类型、文档模板设计器，以及 OmniDataTransform 与自定义类的数据映射。
学习目标
完成本单元后，你将能够：
- 描述 OmniStudio 文档生成中使用的三种令牌类型及其语法。
- 在文档模板设计器中创建文档模板。
- 解释 OmniDataTransform 和自定义类的数据映射流程。
先决条件
开始前，建议完成以下模块：
- 必需：OmniStudio Document Generation Foundations。
- 推荐：OmniStudio Data Tools and Internal Data（涵盖 Data Mapper 和 OmniScript，是文档生成数据流的基础）。
Cloud Kicks 的文档生成
认识团队：
- Candace Evans——销售代表，想简化报价到文档的流程，需要能适应不同客户的模板。
- Linda Rosenberg——Salesforce 管理员，会实施 OmniStudio 文档生成，为 Candace 和她的团队搭建逻辑。
目标：一个「全能的」文档生成系统，让销售流程更快、更高效。
关于文档模板
文档模板是任何文档生成系统的基础，可以简单也可以复杂。模板中有三种内容：
- 标准内容——公司名称、联系方式（每次都一样）。
- 条件元素——满足条件时才出现的部分（如只对特定州显示的免责声明）。
- 动态元素——客户特定的数据，如产品名称、数量、定价。
模板就绪后：① 上传到文档模板设计器；② 指定元数据（名称、类型）；③ 选择用于映射和提取的 Data Mapper；④ 上线前测试。
从模板到生产
模板设计好后，按四步把它推向生产：
- 上传——把 .docx 或 .pptx 文件拖进文档模板设计器。
- 指定元数据——命名并选择类型：Microsoft Word 或 PowerPoint。
- 选择 Data Mapper——配置用于数据映射和提取的 Extract 和 Transform Data Mapper。
- 测试——用示例 OmniScript 生成测试文档，验证输出。
一切正常后再上线。测试这一步绝不能跳过——在这里发现问题，能避免把坏模板推给用户。
嵌入的令牌——概览
令牌（Token）是模板里的占位符，在动态文档生成时映射输入数据。.docx 和 .pptx 模板有三种令牌类型：
- 变量令牌（Variable Token）——单值占位符，如账户名称、报价编号、报价日期。
- 重复内容令牌（Repeating Content Token）——表格行、列表项，如报价里的产品行项目。
- 条件评估令牌（Condition Evaluation Token）——显示或隐藏部分，如只对阿拉斯加和夏威夷显示配送免责声明。
令牌用 true/false 语句实现条件逻辑。
变量令牌
变量令牌代表模板中单一、可替换的值。Linda 的报价模板用变量令牌表示公司名称、报价编号、报价日期。
工作原理：把令牌放在模板中希望显示值的位置，令牌通过 Data Mapper 映射到 Salesforce 数据，文档生成时令牌被真实数据替换。模板里的格式（如加粗）会延续到最终输出——令牌加粗，值就显示为加粗。
重复内容令牌
重复内容令牌处理数量随文档变化的列表和表格。Linda 的报价模板用它表示产品行项目（各种款式的超舒适运动鞋）。
工作原理：在模板里用表格格式定义令牌，令牌会为返回的每一行数据重复。输出是一张自动填充的表格，每个产品一行。
这能轻松扩展——2 个产品或 200 个产品，同一个模板，生成后无需手动编辑。
条件评估令牌
条件评估令牌根据文档生成时评估的 true/false 条件显示或隐藏内容。
Cloud Kicks 的用例：阿拉斯加和夏威夷的客户配送时间更长，只有这些客户需要看到配送免责声明，其他客户则自动隐藏。Linda 在模板里创建一个条件子句，用条件评估令牌包住免责声明部分，生成时系统检查配送地址是否在阿拉斯加或夏威夷——是则显示，否则隐藏。
重要：条件评估令牌只支持 true/false 语句。
文档模板设计器——设置
创建好 .docx 或 .pptx 模板后，把它上传到 Salesforce 的文档模板设计器。步骤 1-5（基本配置）：
- 从 App Launcher 打开文档模板设计器。
- 点击 New 打开 Start New Template 窗口。
- 输入名称（如 Sales Quote Template）。
- 选择模板类型：Microsoft Word 或 PowerPoint。
- 选择令牌映射方法：OmniDataTransform（用 Data Mapper）或 Custom Class（用 Apex 自定义提取）。
令牌映射的选择决定了整个数据流——根据数据复杂度谨慎选择。
文档模板设计器——数据映射与测试
步骤 6-9（Data Mapper 和文件上传）：
- 输入 Mapping Data Mapper Bundle 名称（如
DRTranformQuote）——从模板提取令牌并匹配到 Salesforce 字段，可用 Quick Match 自动映射省时间。 - 可选输入 Data Extract Data Mapper Bundle 名称（如
DRExtractQuote）——只有用 OmniScript 收集数据时才需要。 - 把 .docx/.pptx 文件拖进 Attach File 区域。
- 点击 Save Template Details。
保存后用示例 OmniScript 测试，反复调整直到文档完美。测试不是可选项——它是质量门。
文档生成中的数据映射
数据是如何进入文档的？两种令牌映射方法处理数据流：
- OmniDataTransform——Data Mapper Extract 从 Salesforce 以 JSON 格式提取数据，Data Mapper Transform 重新格式化 JSON 供文档生成器使用。适合基于 OmniScript 采集的标准用例。
- Custom Class——Apex 自定义类直接生成 JSON 输入，跳过 Data Mapper Extract。适合超大数据集（200+ 行项目）的文档。
两种方法最终都汇聚到文档生成 OmniScript，产出最终的 .docx、.pptx 或 .pdf。
OmniDataTransform 数据映射
两步 Data Mapper 管道：
- Data Mapper Extract——从 Salesforce 数据库以 JSON 格式拉取数据（账户名称、报价编号、产品行项目）。
- Data Mapper Transform——重新格式化提取的 JSON 供文档生成器使用，把字段映射到模板令牌。
- OmniScript——最终用户完成 OmniScript，生成 .docx/.pptx/.pdf。
这是标准做法——可靠、文档完善，适合大多数业务文档场景。
自定义类数据映射
对于大数据集文档，用 Apex 自定义类直接生成 JSON 输入。适用场景：200+ 行项目的文档、性能关键的生成、需要精细控制数据提取。
工作原理：① 写一个 Apex 自定义类查询并格式化数据；② 在设计器里把类连到模板；③ 类直接产出 JSON 输入（无需 Data Mapper Extract）；④ JSON 喂给文档生成 OmniScript；⑤ 生成最终文档。
设置步骤更多，但大规模下性能更好。
资源——单元 1
继续学习这些资源：OmniStudio Data Mappers、OmniScripts、文档模板文档、Word/PowerPoint 模板文档、在生成模板中使用自定义类、创建文档模板实践指南（PDF）。这些资源巩固所学，帮你应用到自己的项目。
探索客户端文档生成
本单元探索向模板传递数据的三种方式，以及示例客户端 OmniScript——把模板嵌入真实业务流程。
学习目标——单元 2
完成本单元后，你将能够：
- 解释向文档模板传递数据的三种方式。
- 描述客户端 OmniScript 示例的元素，以及如何为自己的用例定制。
构建文档生成流程
模板本身不做任何事，需要成为流程的一部分。所有文档生成都遵循同一机制：JSON 输入数据流入模板，模板渲染出最终文档。JSON 可来自三种来源：OmniScript、自定义 Apex 类、或附加在模板上的 Data Mapper。
关键的架构决策是选择客户端还是服务端生成，取决于是否需要用户交互。
客户端 vs 服务端生成
客户端生成——需要用户交互时使用：销售填写表单生成文档，适合有引导输入的小文档。例如 Candace 录入客户信息后点 Generate。
服务端生成——自动化是关键时使用：基于触发器或 API 驱动，无需用户输入，适合大文档或批量处理。例如商机关闭时自动生成报告。
无论哪种方式，核心模式相同：数据进、文档出。理解这一点是掌握 OmniStudio 文档生成的关键。
向文档模板传递数据
客户端文档生成有三种方式把数据传入模板：
- 定制示例 OmniScript——从提供的示例开始，适配自己的用例，最快（大部分结构已建好）。
- 从零创建新 OmniScript——完全控制数据采集和用户体验，适合独特或复杂的流程。
- 用自定义 Apex 类的 JSON 输入——适合超大数据集（200+ 行项目），把类直接连到模板。
每种方式各有其用武之地。
选项 1——自定义示例 OmniScript
OmniStudio 文档生成自带一个开箱即用的示例 OmniScript：收集对象 ID 和文档格式选项、提供生成文档的预览和下载。
Linda 的做法：创建一个新版本（原始版本保持不动），为她的报价模板定制，保留原始样本供未来项目使用。
前提：模板必须同时有 Data Mapper Extract 和 Transform——示例本身不提取 Salesforce 数据。
选项 2——用 OmniScript 收集用户数据
从零构建一个自定义 OmniScript 收集用户数据并直接传入模板。例如汽车保险保单 OmniScript：询问客户姓名、生日、地址、车辆信息，OmniScript 里已含 Data Mapper 或集成过程，把采集的数据传入模板。
与选项 1 的关键区别：模板只需 Data Mapper Transform，不需要 Extract——因为 OmniScript 已处理了数据检索。
适合数据采集和文档生成紧密耦合在单一工作流里的流程。
选项 3——自定义类 JSON 输入
对于大数据集文档，用自定义 Apex 类直接生成 JSON 输入。适用：200+ 行项目的文档、性能关键（绕过 Data Mapper 开销）、复杂数据逻辑更适合用 Apex 表达。
工作原理：自定义 Apex 类提取数据并格式化为 JSON，在设计器里把类连到模板，无需 OmniScript 或 Data Mapper Extract，模板只需 Data Mapper Transform。
权衡：前期开发工作量更大，但数据密集文档性能显著更好。
文档生成 OmniScript 示例
示例客户端 OmniScript 名为 docGenerationSample/fndSingleDocxLwc，在 Salesforce 的 OmniScript 选项卡里可找到。结构为 7 个顺序步骤：对象选择 → 模板选择 → 格式选择（.docx/.pptx/.pdf）→ 数据采集 → 文档生成 → 预览 → 下载。
Linda 创建新版本，保留原始样本供未来使用——这是推荐的最佳实践。
资源——单元 2
继续学习：OmniStudio Data Mappers、OmniScripts、Apex 触发器、Apex 基础与数据库、客户端文档生成概述文档、实践指南（PDF）。客户端生成适合交互式流程，下一单元探索服务端。
探索服务端文档生成
本单元学习服务端文档生成——自动化、API 驱动、大文档与批量处理，以及用于快速实施的示例资产。
学习目标——单元 3
完成本单元后，你将能够：
- 描述服务端文档生成的好处和能力。
- 识别何时用服务端而非客户端生成。
- 定制开箱即用的示例以加速实施。
生成文档的不同方法
传统上文档生成在浏览器里运行——需要用户交互，文档为中小型。但 Linda 注意到 Cloud Kicks 的低效：一些合同很大、浏览器里太慢；一些文档不需要团队输入、可以自动化；手动生成是大量工作流的瓶颈。
解决方案：服务端文档生成——运行在 Salesforce 计算资源（Hyperforce）而非浏览器，支持通过 API 自动化（无需用户），高效处理大文档和批量生成。
服务端文档生成能力
服务端生成的两个关键能力：
- 用 API 自动化——无需用户输入即可生成文档，配置 OmniScript 调用 API 实现全自动。
- 从多来源启动——从 Apex 代码、集成过程或 OmniScript 触发，灵活适配任何架构。
服务端规模与示例资产
另外两个能力：
- 处理大文档和多文档——用 Salesforce Hyperforce 计算处理渲染密集的文档（数千个令牌），可同时生成多个文档。例如 20 份多站点报价一次生成，而非逐个。
- 用示例资产加速实施——提供示例集成过程、服务端 OmniScript 和 Lightning Web Component，都是可定制的可用代码，不必从空白页开始。
何时使用服务端文档生成
三种常见场景：
- 渲染密集的文档——令牌多、表格复杂、行数多，如企业客户的大订单合同。
- 一次处理多个文档——多站点报价，每个位置各需一份文档。
- 基于触发器的生成——记录变更时自动生成，如商机变为 Closed-Won 时自动生成报告。
触发式与批量场景
第三个场景是触发器式自动化：商机状态变为 Closed-Won 时自动生成报告并附加到记录——销售代表不用点任何东西，文档自动出现。
这三个场景是你的决策框架：渲染密集（服务端承担计算）、一次多文档（并行生成）、事件驱动自动化（即发即忘）。看到这些模式，服务端就是答案。
服务端文档生成流程
服务端生成底层的流程：
- 启动——从集成过程、OmniScript 或 Apex 代码。
- BPO 请求——一个 Base Platform Object 请求进入队列，可同时生成多个 BPO 请求。
- 队列——请求等待出队机制调用远程 API 服务。
- 远程 API 服务——运行在 Hyperforce 环境，从队列拉取请求、生成文档。
- 存储——生成的文档以 Content Document 存到 Salesforce。
队列架构让生成在不阻塞用户或浏览器的情况下高效规模化。
更快地实施服务端文档生成
Salesforce 提供资产加速服务端实施——从可用样本开始，而非空白页。包内含三个示例资产：
- 示例服务端 OmniScript（
docGenerationSample/fndSingleDocxServersideLwc）。 - 示例集成过程——三个变体：生成文档、带令牌数据生成、转 PDF。
- Lightning Web Component——预构建的文档生成界面。
Linda 的做法：创建新版本再定制，绝不编辑原始样本。
示例服务端 OmniScript
示例服务端 OmniScript（docGenerationSample/fndSingleDocxServersideLwc）有 6 个顺序步骤：对象选择 → 模板选择 → 格式选择 → 服务端处理（在 Hyperforce 生成）→ 状态检查 → 下载。
与客户端的区别：步骤 4-5 在服务端异步运行，释放浏览器做其他事。Linda 为她的多站点报价模板创建新版本。
示例 OmniStudio 集成过程
三个示例集成过程处理不同场景：
DocumentServiceGateway_DocGeneration——服务端文档生成，按参数产出 .docx/.pptx/.pdf。DocumentServiceGateway_DocGenerationWithTokenData——带令牌数据生成，注入显式令牌值。DocumentServiceGateway_DocGenerationPDF——把已生成的 .docx/.pptx 转成 .pdf。
每个可独立调用，也可在 OmniScript 内调用——按需组合。
服务端文档生成 OmniScript 示例
服务端 OmniScript 示例提供流畅的用户体验，隐藏了幕后复杂性。最终用户（如 Candace）无需了解 BPO 请求、队列机制或 Hyperforce 计算——她只需选择记录、选模板、选格式、点生成，OmniScript 处理其余一切：提交请求到队列、轮询完成状态、就绪时提供下载链接。
集成过程——生成
两个用于文档生成的集成过程：
DocumentServiceGateway_DocGeneration——通用主力，服务端文档生成，产出 .docx/.pptx/.pdf。DocumentServiceGateway_DocGenerationWithTokenData——同样生成，另加显式令牌值注入，适合想程序化控制令牌值、不依赖 Data Mapper 时。
两者都可从 Apex 独立调用或在 OmniScript 内调用。
集成过程——PDF 与启用
DocumentServiceGateway_DocGenerationPDF：把已生成的 .docx/.pptx 转成 .pdf，输入是已有文档、输出是 PDF 版本。用例：生成 .docx 供编辑，再转 .pdf 发给客户。
⚠️ 重要——服务端生成默认不启用：必须通过知识文章「Request Access to Server-Side Document Generation」申请访问。在项目早期规划这个开通步骤——别等到全建好了才发现开不了引擎。
资源——单元 3
继续学习：集成过程、服务端文档生成概述文档、实践指南（PDF）。记住——服务端生成需要先申请访问才能在 org 里启用，请在项目早期规划这个开通步骤。
文章来源：Trailhead - Deep Dive into OmniStudio Document Generation