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/ToolJetEngagespot 是一款面向应用内通知的托管服务支持多渠道消息推送与用户管理。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 有两种入口方式在查询面板Query Panel中点击Add new Data source从 ToolJet 仪表盘进入 Data Sources 页面。在连接配置表单中需要填写以下字段字段必填说明Api key是Engagespot 应用实例的唯一标识对应请求头X-ENGAGESPOT-API-KEYApi secret是Engagespot 的 API 密钥对应请求头X-ENGAGESPOT-API-SECRET存储时会被加密Signing key否签名密钥用于直接从 ToolJet 为你的用户签发认证令牌Generate User Token 操作依赖此配置Custom endpoint否自定义端点开关开启后可修改默认的 Engagespot API 地址填写完成后点击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.tsasync 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.jsonengagespot/node版本为^1.5.1。连接测试失败时会返回{ status: failed, message }成功则返回{ status: ok }插件通过customTesting: false使用默认的测试流程。在 ToolJet 中查询 EngagespotQuerying数据源保存成功后即可通过查询管理器Query Manager执行操作点击查询管理器的Add按钮关于查询管理器可参考 query-panel选择上一步添加的 Engagespot 数据源从下拉列表中选择要执行的操作Operation填写对应的参数后点击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 OperationsEngagespot 数据源支持三种操作Create or Update User、Send Notification和Generate User Token。每种操作的参数与字段布局定义在 operations.json 中所有参数均使用codehinter类型的输入框既可以直接填写静态值也可以通过{{ }}语法绑定组件状态、查询结果或全局变量。Create or Update User创建或更新用户该操作用于在 Engagespot 中创建新用户若用户标识已存在则更新其资料实现存在即更新的幂等语义。必填参数User Identifier唯一用户标识identifier对应查询选项中的identifier字段。可选参数User Profile JSONprofile用户资料属性接受任何合法的 JSON 键值对对象格式。底层实现非常直接lib/index.tsasync createOrUpdateUser(client: any, queryOptions: QueryOptions): Promiseany { 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.jsonNotification Messagemessage通知正文。Notification URLurl通知点击后跳转的 URL。Notification Iconicon通知图标。Notification Datadata随通知携带的自定义数据JSON。Notification Categorycategory通知分类。Overrideoverride覆盖账户中预设的投递偏好delivery preferences例如强制指定某个渠道。底层调用lib/index.ts将上述参数组装为 Engagespot 的send请求async sendNotification(client: any, queryOptions: QueryOptions): Promiseany { 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.tsasync generateUserToken(client: any, queryOptions: QueryOptions): Promiseany { 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): PromiseConnectionTestResult { 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考