企业官网建设流程全解析

ToolJet 集成 Engagespot 通知数据源：连接配置、查询操作与源码实现解析

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

Engagespot 是一款面向应用内通知的托管服务，支持多渠道消息推送与用户管理。ToolJet 官方市场（Marketplace）提供了 Engagespot 数据源插件，使你在无需编写后端代码的前提下，直接在 ToolJet 应用中发送通知、创建或更新用户、生成用户令牌，并嵌入应用内收件箱（In-App Inbox）。本文将基于 2.50.0-LTS 版本文档与仓库内插件源码，完整讲解该数据源的连接建立、查询操作、参数含义以及底层实现原理，帮助你将 Engagespot 的通知能力无缝接入 ToolJet 应用。

本文对应的插件源码位于 marketplace/plugins/engagespot，核心实现文件为 lib/index.ts。

前置条件：使用 Marketplace 插件

Engagespot 属于 Marketplace 插件，在创建数据源之前，需要先完成插件的安装与启用。你可以在仪表盘左下角的设置图标菜单中打开Marketplace页面，在Marketplace标签页中找到 Engagespot 卡片并点击Install完成安装；安装成功后状态会变为Installed。随后在仪表盘的Data sources标签页向下滚动到Plugins区域，即可看到已安装的插件列表并进行配置。

注意：如果你移除了某个插件，所有与之关联的查询都会从应用中一并删除，请谨慎操作。

关于插件的完整安装与使用流程，可参考 Marketplace 概述。

建立与 Engagespot 的连接（Connection）

连接 Engagespot 有两种入口方式：

1. 在查询面板（Query Panel）中点击+Add new Data source；
2. 从 ToolJet 仪表盘进入 Data Sources 页面。

在连接配置表单中，需要填写以下字段：

填写完成后：

• 点击Test Connection验证凭据是否有效；
• 点击Save保存数据源。

从 manifest.json 可以看到连接配置的完整定义：apiKey、apiSecret、signingKey均为字符串类型，其中apiSecret标记为"encrypted": true，说明该密钥在持久化时会经过加密处理；endpoint默认值为https://api.engagespot.com/v3，而endpoint_enabled是一个布尔型开关（toggle），它作为endpoint字段的控制器（controller: "endpoint_enabled"）——只有开启"自定义端点"开关后才会显示端点输入框，方便自建代理或私有化部署场景下切换 BaseURL。

在底层，testConnection与run都会调用getConnection来构造 Engagespot 客户端（见 lib/index.ts）：

async getConnection(sourceOptions: SourceOptions) { const options: IEngagespotClientOptions = { apiKey: sourceOptions.apiKey, apiSecret: sourceOptions.apiSecret, ...(sourceOptions.endpoint && { baseUrl: sourceOptions.endpoint }), ...(sourceOptions.signingKey && { signingKey: sourceOptions.signingKey }), }; return EngagespotClient(options); }

可以看到，endpoint（自定义 BaseURL）与signingKey均为可选注入项，只有填写了才会传给官方客户端@engagespot/node（插件依赖版本见 package.json，@engagespot/node版本为^1.5.1）。连接测试失败时会返回{ status: 'failed', message }，成功则返回{ status: 'ok' }，插件通过customTesting: false使用默认的测试流程。

在 ToolJet 中查询 Engagespot（Querying）

数据源保存成功后，即可通过查询管理器（Query Manager）执行操作：

1. 点击查询管理器的+Add按钮（关于查询管理器可参考 query-panel）；
2. 选择上一步添加的 Engagespot 数据源；
3. 从下拉列表中选择要执行的操作（Operation）；
4. 填写对应的参数后点击Run运行查询。

查询的返回结果还可以通过数据转换（Transformations）进一步处理，例如过滤字段、重命名、合并多个查询结果等，具体语法见 transformations。

从源码看，查询执行入口是 lib/index.ts 中的run方法：它根据queryOptions.operation命中switch分支，将操作分派到对应的私有方法，最终统一返回{ status: 'ok', data: result }；任何异常都会被包装为QueryError抛出，便于在前端查询面板中展示错误信息。三种操作在 types.ts 中定义为枚举：

export enum Operation { createOrUpdateUser = 'create_or_update_user', sendNotification = 'send_notification', generateUserToken = 'generate_user_token', }

查询操作详解（Query Operations）

Engagespot 数据源支持三种操作：Create or Update User、Send Notification和Generate User Token。每种操作的参数与字段布局定义在 operations.json 中，所有参数均使用codehinter类型的输入框，既可以直接填写静态值，也可以通过{{ }}语法绑定组件状态、查询结果或全局变量。

Create or Update User（创建或更新用户）

该操作用于在 Engagespot 中创建新用户，若用户标识已存在则更新其资料，实现"存在即更新"的幂等语义。

必填参数：

• User Identifier：唯一用户标识（identifier），对应查询选项中的identifier字段。

可选参数：

• User Profile JSON（profile）：用户资料属性，接受任何合法的 JSON 键值对对象格式。

底层实现非常直接（lib/index.ts）：

async createOrUpdateUser(client: any, queryOptions: QueryOptions): Promise<any> { return await client.createOrUpdateUser(queryOptions.identifier, queryOptions.profile); }

典型场景是将 ToolJet 应用中的登录用户 ID 同步为 Engagespot 用户，例如在用户登录后触发一个查询，User Identifier绑定{{globals.currentUser.id}}，User Profile JSON填入：

{ "name": "{{globals.currentUser.name}}", "email": "{{globals.currentUser.email}}" }

Send Notification（发送通知）

该操作向指定的用户或用户组发送通知，可用于审批提醒、告警、任务分配等场景。

必填参数：

• Recipient：接收者（reciepient），唯一用户标识。
• Notification Title：通知标题（notification_title）。

可选参数：（完整定义见 operations.json）

• Notification Message（message）：通知正文。
• Notification URL（url）：通知点击后跳转的 URL。
• Notification Icon（icon）：通知图标。
• Notification Data（data）：随通知携带的自定义数据（JSON）。
• Notification Category（category）：通知分类。
• Override（override）：覆盖账户中预设的投递偏好（delivery preferences），例如强制指定某个渠道。

底层调用（lib/index.ts）将上述参数组装为 Engagespot 的send请求：

async sendNotification(client: any, queryOptions: QueryOptions): Promise<any> { return await client.send({ notification: { title: queryOptions.notification_title, message: queryOptions.message, url: queryOptions.url, icon: queryOptions.icon, }, recipients: [queryOptions.reciepient], category: queryOptions.category, override: queryOptions.override, data: queryOptions.data, }); }

从代码结构看，recipients是一个数组，因此接收者字段虽在界面上以单个标识呈现，但底层始终以数组形式提交；notification对象统一承载标题、正文、跳转链接与图标，而category、override、data作为通知的扩展控制项独立传递。

Generate User Token（生成用户令牌）

该操作为指定用户生成用于客户端初始化（如 Web SDK、移动端 SDK）的认证令牌。

必填参数：

• User Identifier：唯一用户标识（identifier）。

前置条件：正如文档提示，要使用该操作，必须在建立数据源连接时提供Signing Key；否则无法为用户的令牌签名。

底层实现（lib/index.ts）：

async generateUserToken(client: any, queryOptions: QueryOptions): Promise<any> { return await client.generateUserToken(queryOptions.identifier); }

生成的令牌可用于在 ToolJet 应用中直接初始化 Engagespot 的收件箱 SDK，从而让当前用户在浏览器内读取自己的通知，而无需暴露服务端密钥。

在 ToolJet 应用中添加 In-App Inbox 元素

除了通过查询与 Engagespot 交互，你还可以在 ToolJet 应用中嵌入应用内收件箱（In-App Inbox）组件，让用户直接查看和管理自己的通知。该元素通常配合Generate User Token操作使用：先用数据源为当前用户生成令牌，再把令牌交给收件箱组件完成初始化，即可在页面内呈现实时通知列表。

源码级补充：连接测试与错误处理

插件的连接测试逻辑（lib/index.ts）会真实地尝试建立一次 Engagespot 客户端连接，而不是仅做字段非空校验：

async testConnection(sourceOptions: SourceOptions): Promise<ConnectionTestResult> { try { await this.getConnection(sourceOptions); return { status: 'ok' }; } catch (error) { return { status: 'failed', message: error.message }; } }

这种设计意味着如果 API Key / API Secret 无效或网络不可达，测试会直接失败并返回具体错误信息，帮助你在保存数据源前尽早发现问题。同时，getConnection中通过展开运算符按需注入baseUrl与signingKey，从源码层面印证了自定义端点与签名密钥均为可选配置的事实。

插件目录下的测试文件tests/index.js 目前仅包含占位用例（it.todo('needs tests')），可作为后续为三类操作补充自动化测试的起点；构建脚本使用ncc build lib/index.ts -o dist将 TypeScript 源码打包为单一 JS 产物（见 package.json）。

小结

Engagespot 数据源插件为 ToolJet 应用提供了开箱即用的通知能力闭环：通过Api Key / Api Secret建立连接（可选Signing Key与自定义端点），在查询面板中以三种受控操作完成用户同步（Create or Update User）、消息触达（Send Notification）与客户端认证（Generate User Token），再配合 In-App Inbox 元素完成收件箱的前端呈现。整套流程无需编写后端服务，所有交互均可在 ToolJet 的可视化界面中配置完成，并可通过查询间的数据流（如用用户 ID 作为通知接收者）组合出审批提醒、告警推送、运营触达等真实业务场景。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet