• 物联网
• 后端
• 数据可视化
• 消息队列

规则引擎中的「send notification（发送通知）」节点负责将告警、遥测、实体事件等消息以通知的形式推送给指定目标（用户、客户、邮件/短信/Teams/Slack 通道）。本指南围绕 rule_node.md 讲解其核心能力：通知主题（subject）、正文（message）与按钮（button）的模板化与本地化。读完本文，你将掌握该节点可用模板参数清单、${...}取值语法、upperCase/lowerCase/capitalize/translate后缀用法，以及翻译 key 与收件人语言设置（locale）的联动机制，并能结合实际 JSON 消息编写可直接落地的通知模板。

一、为什么通知模板需要模板化与本地化

通知模板定义了消息的静态内容，但真实场景中通知内容必须随触发上下文动态变化：不同设备上报的温湿度、不同告警的严重级别、收件人姓名的个性化称呼等。ThingsBoard 通过统一的模板化机制，让规则引擎节点的主题、正文和按钮支持占位符插值；同时借助translate后缀与收件人语言设置，实现同一模板自动切换为收件人所用语言的本地化效果。

从源码结构看，这一机制服务于两大类通知来源：

• 规则引擎发起（Rule Engine originated）：即本指南讲解的send notification节点，消息数据与元数据直接来自流入节点的TbMsg，模板参数最丰富；
• 通知规则发起（Notification rule）：由 DefaultNotificationRuleProcessor.java 处理各类触发器（告警、设备活动、资源短缺等）自动生成通知。

两者共用同一套TemplateUtils处理引擎与「模板可替换值（TemplatableValue）」抽象，只是可用的模板参数集合不同。

二、可用模板参数完整清单

通知模板（主题、正文、按钮）支持模板化和本地化，可用的模板参数取决于模板类型（template type）。针对规则引擎通知节点，可用参数如下：

参数名必须用${...}包裹，例如${recipientFirstName}。

2.1 消息 metadata 与 data 参数在源码中的填充逻辑

规则引擎节点的模板参数来源于 RuleEngineOriginatedNotificationInfo.java 的getTemplateData()方法，其组装顺序为：

1. 将消息元数据msgMetadata全部键值对放入模板上下文；
2. 将消息数据msgData全部键值对放入模板上下文（数据来自JacksonUtil.toFlatMap扁平化，嵌套 JSON 对象会转换为形如building_1.temperature的点分路径键）；
3. 追加originatorType（取实体类型的规范名称getNormalName()，如Device）、originatorId、msgType、customerId（无客户时为空字符串）。

实际的数据采集发生在 TbNotificationNode.java：onMsg方法读取消息的 originator、metadata 与 data，并查询该 originator 归属的CustomerId后构建通知信息。因此模板中能引用哪些 metadata/data 键，取决于流入节点的消息内容——例如遥讯消息常带有deviceName、deviceType等元数据键，告警消息的数据中则包含alarmSeverity、alarmStatus等字段。

三、值修饰后缀：upperCase / lowerCase / capitalize

除直接插值外，还可以用一个后缀修改参数值的大小写或首字母大写格式：

这三个内置修饰函数在 TemplateUtils.java 中注册：

private static final Map<String, UnaryOperator<String>> FUNCTIONS = Map.of( "upperCase", String::toUpperCase, "lowerCase", String::toLowerCase, "capitalize", StringUtils::capitalize );

处理时先按正则\$\{(.+?)(:[a-zA-Z]+)?\}匹配出参数键与可选函数名，再对取到的值依次应用对应函数，最终以Matcher.quoteReplacement安全写回，避免替换文本中的特殊字符破坏结果。

四、模板的本地化：translate 后缀与收件人语言

要本地化通知内容，使用translate后缀：${some.translation.key:translate}。它表示以「翻译键」而非普通参数来解析占位符——系统会用该键去查找翻译文件（如自定义翻译 JSON）中对应语言的值。

例如，假设你定义了自定义翻译键custom.notifications.greetings，其值为Hello, ${recipientFirstName}!，那么模板：

${custom.notifications.greetings:translate}

将被转换为：

Hello, John!

4.1 翻译值内部还支持二次插值

翻译后的文本仍可包含${...}占位符。在 TemplateUtils.processTemplate 的实现中，translate被注册为自定义函数，执行逻辑是先取出翻译值，再对该值再次执行一轮模板处理（value = processTemplate(value, context, null)），因此Hello, ${recipientFirstName}!中的姓名占位符同样会被收件人数据替换。

4.2 语言（locale）如何确定

所需语言取自收件人的资料设置（profile settings），默认使用英语。对应逻辑位于 NotificationProcessingContext.java：

String locale = recipient instanceof User user ? user.getLocale() : Locale.US.toString();

即：收件人是平台用户时，取其资料中的 locale 设置（在用户资料中对应lang字段，例如en_US，参见 User.java 的属性说明）；否则回退为Locale.US（英语）。只有模板值中确实包含收件人相关变量或translate键时，系统才会针对该收件人执行逐人模板处理，从而避免不必要的重复计算。

翻译解析通过translate(key, locale)完成：先按 locale 加载整份翻译 JSON（translationProvider），再用JacksonUtil.getByKeyPath按点分路径取出键对应文本；找不到键时返回空字符串。同键同语言的解析结果会被缓存，兼顾性能。

五、完整示例：基于消息数据的模板编写

假设流入规则引擎节点（send notification）的消息数据如下：

{ "building_1": { "temperature": 24 } }

模板：

Building 1: temperature is ${building_1.temperature}

将被转换为：

Building 1: temperature is 24

这正体现了「data 键名直接引用 + 嵌套路径点分访问」的用法：${building_1.temperature}会被msgData扁平化后生成的键building_1.temperature命中。

5.1 组合运用示例

将参数、修饰符与翻译机制组合使用，可写出更具实战价值的模板：

告警：${msgType} 来自设备 ${deviceName} 当前状态：${alarmStatus:capitalize}，严重级别 ${alarmSeverity:upperCase} 致 ${recipientTitle}（${recipientFirstName:lowerCase}）： ${custom.notifications.alarmBody:translate}

其中deviceName、alarmStatus、alarmSeverity取决于消息 metadata/data；recipientTitle、recipientFirstName由收件人资料填充；最后的翻译键负责加载本地化正文。

六、模板在 send notification 节点中的执行链路

要理解模板何时生效，需要看完整链路：

1. 节点触发：send notification节点（TbNotificationNode.java）收到TbMsg后，节点配置必须指定通知模板templateId与通知目标targets（见 TbNotificationNodeConfiguration.java，其中targets为@NotEmpty的 UUID 列表，templateId为@NotNull）。节点将消息上下文封装进RuleEngineOriginatedNotificationInfo并异步提交给通知中心（NotificationCenter）。
2. 模板预编译：NotificationProcessingContext.init()会对每个启用状态的投递渠道模板先执行一次「不可变参数」处理（此时尚无收件人），合并request.getInfo().getTemplateData()中的消息级参数。
3. 逐收件人渲染：当通知发送给具体收件人时，getProcessedTemplate()以收件人的 locale 与资料字段（recipientTitle、recipientEmail、recipientFirstName、recipientLastName）构建附加上下文；若模板包含这些变量或翻译键，则重新执行TemplateUtils.processTemplate完成最终渲染。可被模板化的字段（主题、正文、按钮）由各投递渠道模板的TemplatableValue集合定义（见 TemplatableValue.java）。
4. 结果回写节点：处理完成后，节点把统计结果写入消息元数据notificationRequestResult，并按成功/失败走Success或Failure分支（TbNotificationNode.java），供后续规则链分支使用。

七、注意事项与常见问题

• 未定义的参数会被保留：若模板引用的键在上下文中不存在，且没有可用函数，TemplateUtils不会报错，而是原样保留占位符（源码中返回"\\" + matchResult.group()，即保留${...}原文），便于排查模板编写错误。
• 空值安全：上下文键存在但值为null时，会被nullToEmpty转为空字符串，不会引发 NPE；例如无归属客户时customerId即为空字符串。
• 大小写敏感：参数键与后缀均区分大小写，请与消息键名、文档列出的参数名保持一致。
• locale 未设置时回退英文：收件人为非平台用户或未配置语言时，翻译默认按en_US处理；如需为特定用户启用本地化，请在其用户资料中设置语言。
• 模板类型决定可用参数：本文参数清单针对规则引擎通知节点；其他通知类型（如告警触发、实体变更等，见 ui-ngx/src/assets/help/en_US/notification 目录下的对应帮助文档）的参数集合不同，引用前务必核对对应模板类型的说明。
• {:copy-code}仅是 UI 标记：文档示例中出现的{:copy-code}用于在管理界面渲染「复制代码」按钮，并非模板语法，正式配置时无需（也不应）包含。

八、小结

通过模板参数${originatorType}、${building_1.temperature}等实现消息动态内容插值，通过upperCase/lowerCase/capitalize修饰输出格式，通过translate后缀配合收件人语言设置完成通知本地化——这三层能力共同构成了 ThingsBoard 规则引擎通知节点的模板体系。掌握它们，即可在 send notification 节点中编写出既个性化又国际化、可随消息上下文自动变化的通知模板。若需进一步验证行为，可结合 TemplateUtils.java 与 NotificationProcessingContext.java 的源码阅读其精确语义。

• 物联网
• 后端
• 数据可视化
• 消息队列