SAP CPI Message Mapping 文档：一键生成 Excel 映射表
如何把 SAP CPI 的 Message Mapping 写成映射表：哪些列最重要、如何描述函数和上下文，以及如何把映射表导出到 Excel。
映射规范通常是一个接口的第一份文档，也是第一份过时的文档。SAP Cloud Integration（SAP CPI）中的 Message Mapping 会在构建和测试期间不断变化，而描述它的电子表格却停留在原地。
本文介绍映射表需要哪些列、如何描述函数、上下文和 Value Mapping 以便读者能够理解，以及如何直接从映射导出这份表格。
为什么映射规范会偏离实际
映射规范是在映射存在之前，由熟悉业务字段的人编写的。随后开发人员发现，某个字段需要更改上下文，某个日期需要换一种格式，某个代码需要 Value Mapping。这些决定都存在于映射编辑器的图形视图中，很少有被写回表格的。
映射表需要的列
| 列 | 内容 |
|---|---|
| 目标字段 | 目标消息中该字段的完整路径 |
| 出现次数 | 它可以出现的次数，例如 0..1 或 1..unbounded |
| 源字段 | 值来源的源路径 |
| 规则 | 用平实语言描述的逻辑 |
| 函数 | 使用的标准函数，例如 concat、if 或 formatByExample |
| 常量 | 写入映射的固定值 |
| UDF | 用户自定义函数及其作用 |
| Value Mapping | 通过 Value Mapping 转换的代码 |
| 备注 | 上下文变更，以及测试人员应该知道的任何事项 |
描述函数、上下文和 Value Mapping
- 把规则写成一句话：「用空格连接 FirstName 和 LastName」比一串函数名更容易核对。
- 上下文发生变化时要写明。每个项目填一次的字段与每个文档填一次的字段行为不同，大多数映射错误就藏在这里。
- 对于 Value Mapping，写明 agency 和 identifier，让测试人员知道该查哪张表。
- 对于用户自定义函数，说明它返回什么、在什么时候返回，而不是它是怎么写的。
从映射导出表格
- 在设计器中打开 iFlow，点击「Kitegra 工具」按钮并选择「为此 iFlow 生成文档」。
- 在「iFlow 文档」页面上打开「映射表」。它列出 iFlow 中的 Message Mapping，每个目标字段一行，包含上述各列。
- 将其下载为 Excel 工作簿，每个映射一个工作表。
- 如果不使用设计器，请改为选择「上传映射（.mmap 或 ZIP）」。上传的文件不计入您套餐的 iFlow 数。
映射表根据映射文件生成，因此反映的是映射当前的实际行为。请与根据同一个 iFlow 生成的技术设计文档对照阅读。
交接之前检查映射表
- 用一条测试消息核对几行：源值、规则、目标值。
- 以 TRACE 运行 iFlow，查看映射步骤前后的消息体，方法见逐步跟踪消息。
- 在读者需要的不只是规则时填写「备注」列：例如某个字段为什么是常量、哪个系统负责某个代码列表。
Kitegra 如何帮您
映射表属于 Kitegra 的 iFlow Docs 领域。它在您的浏览器中生成；映射从不发送给 Kitegra。
Helper、Message Monitor、iFlow Inspector 和 iFlow Docs 各自统计您使用它们的 iFlow 数：没有 Kitegra 账户时每个模块 5 个，Free 套餐 50 个，Starter 100 个，Pro 300 个；Business 不限。Toolbox 和工作区附加功能免费。比较各套餐。
在下一个 iFlow 中试试
了解 Kitegra 为 SAP Integration Suite 设计器增加了哪些功能，或在 Kitegra 的其他 Chrome 扩展旁查看它。
常见问题
如何为 SAP CPI 的 Message Mapping 编写文档？
写成映射表，每个目标字段一行：目标路径、出现次数、源字段、用文字描述的规则、函数、常量、UDF、Value Mapping 和备注。
可以把 Message Mapping 导出到 Excel 吗？
可以。在「iFlow 文档」页面上，「映射表」可以下载为 Excel 工作簿，每个映射一个工作表。
不用设计器可以为映射编写文档吗？
可以。上传一个 .mmap 文件或包含映射的 ZIP；上传的文件不计入您套餐的 iFlow 数。
映射表会解释用户自定义函数吗？
它会列出每个字段使用的 UDF。至于 UDF 在业务上做什么，值得在「备注」列中写上一行。
我的映射会发送给 Kitegra 吗？
不会。映射表在您的浏览器中生成，映射从不发送。