ToolJet 集成 Salesforce 数据源：OAuth2 连接、SOQL 查询与 CRUD 操作实战指南

ToolJet 集成 Salesforce 数据源：OAuth2 连接、SOQL 查询与 CRUD 操作实战指南

【免费下载链接】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

ToolJet 通过官方 Marketplace 插件与 Salesforce 无缝对接，让你能在低代码应用中直接操作 Salesforce 已连接的 App（Connected App）数据。本文以 docs/docs/marketplace/plugins/salesforce.md 为骨架，结合 marketplace/plugins/salesforce/lib/index.ts 的源码实现，完整讲解从创建 Connected App、OAuth2 授权连接，到执行 SOQL 查询与增删改查（CRUD）的端到端流程。读完本文，你将能够独立完成 Salesforce 数据源配置，并在查询面板中运行 SOQL 与 CRUD 操作。

前置条件：安装 Marketplace 插件

在开始本文的 Salesforce 集成之前，请确保已经完成了 Using Marketplace plugins 的流程，即在 ToolJet 中安装并启用 Salesforce 插件。该插件在仓库中的完整实现位于 marketplace/plugins/salesforce，其 manifest.json 声明了数据源的元信息（版本1.0.1、类型api、Kind 为salesforce），而 operations.json 则定义了查询面板中可用的操作表单。

建立连接：OAuth2 授权流程

1. 准备 Connected App 凭据

要连接 Salesforce，你需要在 Salesforce 侧创建一个 Connected App，并取得以下两项凭据：

• Client ID—— Salesforce Connected App 的 Consumer Key（消费者密钥）；
• Client Secret—— Salesforce Connected App 的 Consumer Secret（消费者机密）。

在 Salesforce 的 Connected App 设置页面中启用 OAuth 设置并记录下这两个值，作为后续填入 ToolJet 表单的依据。

2. 在 ToolJet 中新建数据源

建立连接有两种入口：

• 在查询面板（Query Panel）中点击+Add new Data source；
• 或从 ToolJet 仪表盘导航到 Data Sources 页面。

进入新建数据源界面后：

1. 从API version下拉框中选择 API 版本。从 manifest.json 的properties.api_version定义可以看出，该下拉框由前端根据插件清单动态渲染；
2. 在对应字段中填入Client ID与Client Secret；
3. 复制 ToolJet 表单中展示的Redirect URL，将其粘贴到 Salesforce Connected App 设置中的 OAuthCallback URL字段；
4. 点击Connect to salesforce按钮完成 Salesforce 账号的 OAuth 授权；
5. 授权成功后点击Save data source保存数据源。

3. 源码视角：授权与回调是如何工作的

从 lib/index.ts 的authUrl方法可以看到，插件基于jsforce的OAuth2构建授权 URL，并在其中附加了scope（默认值为full refresh_token offline_access，来自 manifest 的defaults.scopes）以及&prompt=login，确保每次授权都要求用户显式登录。

回调地址的拼装逻辑在getOAuthCredentials（index.ts）中：插件读取环境变量TOOLJET_HOST与SUB_PATH，拼出形如<host>/<subpath>oauth2/authorize的redirect_uri。这解释了为什么你必须把 ToolJet 提供的 Redirect URL 原样填回 Salesforce——两端必须严格一致，OAuth 回调才能成功。

完成授权后，accessDetailsFrom（index.ts）会调用conn.authorize(authCode)换取access_token、refresh_token与instance_url并持久化。后续执行查询时，getConnection（index.ts）使用这些令牌构建jsforce.Connection实例。

4. 关于 OAuth 类型与多用户授权的说明

在 manifest 的oauth.oauth_configs中可以看到，该插件仅允许oauth2授权类型与authorization_code授权模式，并要求client_id、client_secret两个字段。oauth_type支持两种取值（manifest.json）：

• custom_app：使用你在表单中填写的自有 Connected App 凭据（CE/EE/Cloud 均可用）；
• tooljet_app：仅 Cloud 版本支持，此时插件自动读取服务端环境变量SALESFORCE_CLIENT_ID与SALESFORCE_CLIENT_SECRET（见 index.ts）。

此外，插件还支持多用户授权模式：当multiple_auth_enabled为真时，每个用户通过自己的令牌访问 Salesforce。run方法（index.ts）会根据auth_type与grant_type判断是否需要走initializeOAuth与逐用户取令牌的流程；当访问令牌过期时，refreshToken（index.ts）会利用 refresh_token 静默刷新，若刷新失败则提示用户重新授权。

查询 Salesforce：两种操作类型

配置好数据源后，在编辑器底部的 query manager 中点击+Add按钮新建查询，从Data Source下拉框中选择刚才保存的 Salesforce 数据源。

随后在Operation下拉框中选择操作类型。ToolJet 为 Salesforce 交互提供两种操作（与 operations.json 中的operation列表一一对应）：

• SOQL Query—— 使用 SOQL（Salesforce Object Query Language）在你的组织数据中检索特定信息；
• CRUD Action—— 对 Salesforce 对象执行 Create / Retrieve / Update / Delete 操作。

SOQL 查询

执行 SOQL 查询的步骤如下：

1. 在 Operation 下拉框中选择SOQL Query；
2. 在Query字段中输入 SOQL 查询语句；
3. 点击Run执行查询。

从源码实现看，SOQL 分支对应 index.ts 的case 'soql'：插件直接调用conn.query(query)（底层为 jsforce 的 SOQL 查询）。代码中还包含空查询校验——若soql_query为空或仅为空白字符，会抛出QueryError('Invalid Query', 'The SOQL query cannot be empty...')，所以务必填写有效的查询语句。

:::info 查询结果可以使用转换（Transformations）进一步加工，详见 transformations 文档。 :::

CRUD 操作

要执行 CRUD 操作，在 Operation 下拉框中选择CRUD Action，再在Action Type中选择具体动作。插件支持以下四种动作，对应的底层实现集中在 index.ts 的case 'crud'中。

Create（创建）

• Resource Name—— 要创建的 Salesforce 对象名称，默认选中Account；
• Resource Body—— 要插入到 Salesforce 对象中的数据。

Resource Body 支持使用 ToolJet 的模板语法引用组件数据，例如：{{ {name: "ToolJet"} }}（该占位符定义于 operations.json 的create.resource_body）。源码中对应conn.sobject('Account').create(resource_body)。

Retrieve / Read（检索）

• Resource Name—— 对象名称，默认Account；
• Resource ID—— 要检索的 Salesforce 对象 ID（如0012F3E4R56487900N）。

源码中对应conn.sobject('Account').retrieve(resource_id)。

Update（更新）

• Resource Name—— 对象名称，默认Account；
• Resource Body—— 要更新的数据。注意：Resource Body 中必须包含待更新对象的 ID。

官方占位符示例为{{ {Id: "0012F3E4R56487900N", name: "ToolJet"} }}。源码实现会先将resource_id与resource_body合并为{ Id: resource_id, ...resource_body }，再调用conn.sobject('Account').update(...)。

Delete（删除）

• Resource Name—— 对象名称，默认Account；
• Resource ID—— 要删除的 Salesforce 对象 ID。

源码中对应conn.sobject('Account').destroy(resource_id)。

从源码可以看出，目前四种 CRUD 动作均硬编码操作Account对象（conn.sobject('Account')），UI 上的 Resource Name 字段在 operations.json 中也被标记为disabled: true。如果后续需要支持其他 Salesforce 对象，需要扩展插件实现。

错误处理与令牌过期

在 CRUD/SOQL 执行过程中，插件对错误做了统一封装（index.ts）：

• 当检测到 HTTP 401、INVALID_SESSION_ID，或 jsforce 抛出的 "No refresh token found" / "refresh token" 类错误时，会抛出OAuthUnauthorizedClientError，提示会话过期或无效；
• 其他异常则包装为QueryError('Query could not be completed', ...)。

这意味着如果 Salesforce 侧撤销了授权或访问令牌过期，查询会以明确的鉴权错误呈现，提示用户重新连接数据源。

小结

通过 ToolJet 的 Salesforce 插件，你可以在几分钟内完成 OAuth2 授权连接，并在低代码应用中直接执行 SOQL 查询与 Account 对象的 CRUD 操作。整个流程既有可视化的表单配置，又有 jsforce 底层驱动与完整的令牌刷新、错误处理机制作为支撑。若要深入了解数据源管理、查询面板与结果转换能力，可以继续阅读 Data Sources 总览、查询面板文档 与 Transformations 教程。

【免费下载链接】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