ThingsBoard 集成生命周期事件通知模板化指南：参数、文本修饰与国际化详解-平芜编程栈

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

【免费下载链接】thingsboard

All-in-one IoT Platform - Device management, data collection, processing and visualization.

项目地址：https://gitcode.com/GitHub_Trending/th/thingsboard

本篇技术指南讲解 ThingsBoard 物联网平台中「集成生命周期事件」通知（Integration lifecycle event notification）的模板化与本地化能力。当 MQTT、HTTP、OPC-UA 等设备集成在启动、更新或停止时发生状态变化（尤其是启动失败）时，平台可向管理员发送通知，而通知的主题、消息内容与按钮文案均支持使用模板参数动态生成，并可按接收者语言设置自动翻译。读完本文，你将掌握全部可用模板参数、大小写/首字母大写修饰符、translate本地化语法，以及这些参数在服务端源码中的实际生成与解析原理，可直接用于配置实战。

一、集成生命周期事件通知是什么

ThingsBoard 的「集成」（Integration）模块负责与外部系统建立连接（例如 MQTT Broker、HTTP 端点、OPC-UA 服务器等）。当集成实例的状态发生变化时，平台可以触发通知规则，将状态变化事件发送给相关人员。

围绕该功能，仓库中存在一套完整的定义：

事件触发器：IntegrationLifecycleEventTrigger.java 定义了触发器本身，其类型为INTEGRATION_LIFECYCLE_EVENT，携带integrationId、integrationType、integrationName、event（生命周期事件）与error（异常信息）。
触发配置：IntegrationLifecycleEventNotificationRuleTriggerConfig.java 允许你限定关注的集成类型（integrationTypes）、指定具体集成（integrations）、选择通知事件（notifyOn），并可开启onlyOnError仅在出错时通知。
生命周期事件枚举：ComponentLifecycleEvent.java 定义了完整的组件状态，而集成生命周期通知仅使用其中三种：STARTED（已启动）、UPDATED（已更新）、STOPPED（已停止），对应前端模型 notification.models.ts 中ComponentLifecycleEvent枚举的三个取值。

在通知规则中，你可以配置一个或多个触发事件（notifyOn），例如仅在集成启动失败时通知（onlyOnError = true+notifyOn = [STARTED]）。一旦规则被触发，平台就会使用对应的通知模板渲染并发送通知。

二、通知模板的模板化与本地化

集成生命周期事件通知的主题（subject）、消息（message）和按钮（button）均支持模板化与本地化，其行为由本指南所对应的官方说明文档 integration_lifecycle_event.md 定义。

模板化的核心规则：

所有参数名必须用${...}包裹引用，例如${recipientFirstName}；
可用的模板参数取决于模板类型——对于集成生命周期事件通知，可用的参数集合固定为本文第三节列出的九项；
参数值可以通过后缀进一步修饰（大写、小写、首字母大写）；
可以通过translate后缀实现通知文案的国际化，语言取自接收者个人资料设置，默认使用英语。

这些模板被保存在通知模板（NotificationTemplate）中，每个投递渠道（Web、Email、Slack、SMS、Microsoft Teams、移动端 App 等）可分别定义自己的 subject 与 body，相关数据模型可见 NotificationTemplate.java 与 DeliveryMethodNotificationTemplate.java。

三、可用模板参数总览

下表为集成生命周期事件通知模板支持的全部参数，前六个来自集成事件本身，后四个来自通知接收者：

参数	含义
`integrationType`	集成类型，如`MQTT`、`HTTP`、`OPC-UA`等
`integrationName`	集成的名称
`integrationId`	集成的 ID，以 uuid 字符串形式表示
`eventType`	事件类型，取值为`started`、`updated`、`stopped`三者之一
`action`	对应动作，取值为`start`、`update`、`stop`三者之一
`error`	错误文本（若集成启动/更新/停止过程发生异常）
`recipientTitle`	接收者称谓：若配置了姓名则显示名与姓，否则显示邮箱
`recipientEmail`	接收者的邮箱
`recipientFirstName`	接收者的名（first name）
`recipientLastName`	接收者的姓（last name）

需要特别说明的是eventType与action的区别：前者是状态结果（started/updated/stopped），后者是触发动作（start/update/stop），二者在文案中可以组合使用，例如描述"集成启动失败"的告警场景。

参数的源码依据

前六个集成相关参数的来源可以从 IntegrationLifecycleEventNotificationInfo.java 的getTemplateData()方法中得到证实：

return mapOf( "integrationId", integrationId.toString(), "integrationType", integrationType, "integrationName", integrationName, "action", action, "eventType", eventType.name().toLowerCase(), "error", error );

可以看到eventType在服务端被转成小写字符串（STARTED→started），与文档中"取值为started、updated、stopped"的描述完全对应。而后四个接收者参数的来源，则可以在 NotificationProcessingContext.java 的createTemplateContextForRecipient方法中看到：

return Map.of( "recipientTitle", recipient.getTitle(), "recipientEmail", Strings.nullToEmpty(recipient.getEmail()), "recipientFirstName", Strings.nullToEmpty(recipient.getFirstName()), "recipientLastName", Strings.nullToEmpty(recipient.getLastName()) );

四、用后缀修饰参数值

除了直接引用参数，你还可以为参数值附加修饰后缀，对输出文本进行格式化。支持的修饰符如下：

后缀	作用	示例
`upperCase`	全部转为大写	`${recipientFirstName:upperCase}`→`JOHN`
`lowerCase`	全部转为小写	`${recipientFirstName:lowerCase}`→`john`
`capitalize`	首字母大写	`${recipientFirstName:capitalize}`→`John`

修饰符的底层实现位于 TemplateUtils.java：

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

模板解析正则\$\{(.+?)(:[a-zA-Z]+)?\}会同时提取参数名与可选的:后缀部分；若参数不存在，模板原样保留，避免产生空字段。

五、使用`translate`实现通知本地化

通知模板还支持国际化：使用translate后缀即可将翻译键（translation key）渲染为对应语言的文案：

${some.translation.key:translate}

工作流程如下：

假设你在平台中自定义了一个翻译键custom.notifications.greetings，其值为Hello, ${recipientFirstName}!；
模板中写入${custom.notifications.greetings:translate}；
通知发送时，平台会先按接收者语言解析该翻译键，得到Hello, ${recipientFirstName}!，再对结果中的嵌套参数继续进行二次解析，最终渲染为Hello, John!。

这里有一个重要的机制细节：translate会先完成翻译，再递归处理翻译文本内部的${...}参数。这一行为可以在 TemplateUtils.java 的源码中得到确认：

function = customFunctions.get(functionName); if (function != null) { value = function.apply(key); value = processTemplate(value, context, null); // 对翻译结果递归解析参数 }

关于语言（locale）的取值，官方文档明确：所需的语言取自接收者的个人资料设置，默认使用英语。这一点在服务端实现中也有对应逻辑——NotificationProcessingContext.java 中，接收者为用户（User）时取user.getLocale()，否则回退到Locale.US；只有当模板确实包含接收者相关变量或translate键时，才会执行带 locale 的模板处理，以提升批量发送场景的性能。

六、实战示例：集成启动失败通知

官方文档给出了一个完整的示例场景。假设名为My integration的 MQTT 集成启动失败，使用以下模板：

${integrationType} integration '${integrationName}' - ${action} failure: ${error} {:copy-code}

将被渲染为：

MQTT integration 'My integration' - start failure: failed to connect to MQTT broker

逐段拆解其渲染过程：

${integrationType}→MQTT（集成类型）；
${integrationName}→My integration（集成名称）；
${action}→start（触发动作，因为本次事件是启动）；
${error}→failed to connect to MQTT broker（服务端捕获到的具体错误文本，来自IntegrationLifecycleEventTrigger中携带的Throwable）。

在此基础上，你可以组合出更丰富的文案，例如：

[ALERT] ${integrationType} integration '${integrationName}' ${eventType} unexpectedly (${action} failure): ${error} Recipient: ${recipientTitle} <${recipientEmail}>

结合上一节介绍的修饰符与本地化能力，还可以写出：

${integrationName:upperCase} ${eventType:capitalize} — ${custom.notifications.integration.failure:translate}

七、如何创建与触发此类通知（配置路径）

要在你的 ThingsBoard 环境中使用上述模板化能力，需要完成以下配置（均为查看与配置方式，仓库本身为只读代码库）：

创建通知模板：在平台「通知中心 → 通知模板」中新建模板，模板类型选择"集成生命周期事件"；在 Web/Email/Slack 等各投递渠道的 subject、message 与按钮文案中写入上文的${...}模板；
创建通知规则：新建通知规则，触发器类型选择"集成生命周期事件"；在触发配置中按需指定integrationTypes（关注哪些类型的集成）或integrations（关注哪些具体集成），勾选notifyOn事件（STARTED/UPDATED/STOPPED），并按需开启onlyOnError（仅错误时通知），相关字段定义见 IntegrationLifecycleEventNotificationRuleTriggerConfig.java 及前端模型 notification.models.ts；
指定接收者：在规则中配置接收者（用户/用户组等），平台会自动填充recipientTitle、recipientEmail、recipientFirstName、recipientLastName四个接收者参数，并按其个人资料语言设置完成translate本地化。

配置完成后，任何匹配规则的集成生命周期事件（例如 MQTT 集成启动失败）都会触发通知，且通知文案会按照上述模板规则动态生成、格式化并本地化。本指南对应的官方帮助文档 integration_lifecycle_event.md 与通知模板相关的其余帮助文件（位于 notification 帮助目录）可供你在配置时随时查阅。