> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Salesforce > 配置 Salesforce 记录索引，并明确对象、子关联、同步时间窗口与搜索访问边界。 ## 索引内容 Salesforce 连接器会为每条已配置的父记录创建一个可搜索文档。文档以该记录的可查询字段开始，并可把直接子记录作为额外的带链接章节。 | 行为 | 索引效果 | | ----- | --------------------------------------------------------------------------------------------------- | | 默认范围 | 在**简单**模式中，请求对象列表为空时默认使用 `Account`。否则，每个单数形式的对象名称都会被视为父类型。 | | 简单模式 | OpenCore 会请求父类型的全部可查询字段，并发现受支持的直接子关系。Base64、blob、encrypted-string、黑名单及不可查询数据会被排除。 | | 高级模式 | 一个 JSON 对象定义父字段和直接 `associations`。OpenCore 仍会添加 `Id`、`LastModifiedDate`，以及该日期字段可查询时的 `CreatedDate`。 | | 子记录限制 | 附件会被跳过。标准管理后台索引在首次与后续索引都会使用增量轮询，并且每个直接子关系查询都使用 `LIMIT 10`。管理后台流程没有能绕过此限制的完整重建入口。 | 记录字段会转换为可搜索的键值文本。父记录的 `Name` 会作为语义标识符；没有名称时使用 `Id`。记录与子记录链接会指向已认证的 Salesforce 实例。 ## 前置条件 * 创建专用 Salesforce 集成用户，使其可以通过 API 登录，并读取范围内的全部父对象、字段与直接子关系。 * 允许 REST describe/query 与 Bulk API 2.0 query/export 访问。 * 获取集成用户的用户名、密码与 security token。 * 确定凭据指向生产环境还是 Salesforce sandbox。 * 使用**高级**模式时，确认父对象、字段、子对象类型与关系准确且区分大小写的 API 名称。 * 使用**自动同步权限**时，确保搜索用户的 OpenCore 邮箱与活动 Salesforce `Username` 或 `Email` 匹配，并允许查询 `User` 与 `UserRecordAccess`。 ## 凭据 | 环境 | OpenCore 凭据值 | 认证行为 | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | 生产环境 | `sf_username: `、`sf_password: `、`sf_security_token: `、`is_sandbox: false` | 使用 Salesforce 用户名、密码与 token 对默认生产登录域进行认证。 | | Sandbox | `sf_username: `、`sf_password: `、`sf_security_token: `、`is_sandbox: true` | 使用相同凭据字段，但为摄取选择 Salesforce 测试登录域。 | 当前管理后台凭据不接收 Salesforce OAuth client ID、client secret、refresh token 或实例 URL。不要用这些值替代用户名、密码与 security token 字段。 ## 在 OpenCore 中配置 1. 在管理后台打开**连接器**，选择 **Salesforce**，并创建生产环境或 sandbox 凭据。 2. 在**配置类型**中选择**简单**或**高级**。 3. 对于**简单**模式，输入零个或多个单数形式的 Salesforce 对象 API 名称。仅在确实要把 `Account` 作为父类型时留空。 4. 对于**高级**模式，输入一个以父对象类型为顶层键的 JSON 对象。用 `fields` 定义父字段，用 `associations` 把直接子对象类型映射到其字段。这是配置 JSON，不是任意 SOQL 查询。 5. 选择文档访问模式。仅在使用代表性用户和记录验证查询时行为后，才启用**自动同步权限**。 6. 设置刷新与清理选项，创建连接器并运行首次索引。 标准管理后台流程创建轮询连接器，runner 会先选择 `poll_source`，不会进入 load 路径。因此首次与后续索引都会使用增量轮询；即使有效轮询起点是 Unix epoch 0，也不会调用 Salesforce 独立的完整加载实现。未设置**索引开始日期**时，首次有效轮询起点是 epoch 0；设置后，该日期会在共享调度器应用当前 30 分钟重叠后限制首次窗口。应把有效轮询起点视为历史覆盖边界，而不是假定存在完整导出。 ## 权限 摄取凭据决定 OpenCore 可以读取哪些 Salesforce 记录与字段。未使用**自动同步权限**时，Salesforce 记录访问不会同步；搜索访问只由连接器的 OpenCore **私有**群组或**公开**模式控制。 选择**自动同步权限**且权限功能可用时，OpenCore 会在查询时裁剪内容，而不是存储静态记录 ACL。它先用搜索者邮箱匹配活动 Salesforce `Username`，再匹配 `Email`，然后针对每个结果来源链接表示的记录 ID 查询 `UserRecordAccess.HasReadAccess`。用户不可读的 Salesforce 记录对应内容章节会被移除；无法映射用户或权限检查失败时，该检查不会返回任何 Salesforce chunk。 当前行为还有额外范围约束。如果租户内任意 Salesforce 连接器启用了自动同步，则该租户的所有 Salesforce 结果 chunk 都会进入裁剪流程，包括另一个未选择自动同步的 Salesforce 连接器所产生的 chunk。权限 client 会按租户从一个关联连接器凭据建立并缓存，且不会传递摄取凭据的 sandbox-domain 设置。每个记录访问查询最多只检查前 200 个记录 ID；省略的 ID 会失败关闭。使用 sandbox、多个 Salesforce 组织或多个凭据的部署必须显式验证每种组合。 ## 验证 1. 验证连接器，并确认 Salesforce 全局 describe 请求成功。 2. 运行首次同步，搜索一个已配置父记录和一个预期直接子记录值。设置**索引开始日期**时，还要检查有效窗口内的一条记录，以及明显早于配置日期和 30 分钟重叠范围的一条记录；未设置时，检查一条预期的较早记录。 3. 确认未请求的父类型不存在。在**高级**模式中，还要确认已省略字段与关联不存在。 4. 在首次运行和之后一次刷新中都检查一个拥有十条以上直接子记录的父记录。两个版本中每个直接关系都不应出现超过十条子记录。 5. 使用已获 Salesforce 授权的浏览器会话打开父记录与子记录引用链接。 6. 使用**自动同步权限**时，测试已映射活动用户、无记录读取权限的用户、无法匹配活动 Salesforce 用户的邮箱、每个 Salesforce 组织/凭据，以及自身未启用自动同步的连接器。 ## 故障排除 | 症状 | 检查项 | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 登录失败 | 检查用户名、密码、security token 与**是否为 Sandbox 环境**设置。连接器不使用 OAuth 凭据。 | | 验证成功但索引失败 | 验证只检查已认证的全局 describe 与 JSON 结构。确认每个已配置对象、字段与子关联真实存在且可查询。 | | 空的简单配置索引了非预期数据 | 空的简单范围表示 `Account`。需要其他范围时，请输入明确的单数形式对象 API 名称。 | | 高级配置被拒绝 | 确保每个顶层值都是对象，`fields` 是字符串列表，且 `associations` 把子对象名称映射到字符串列表。 | | 子类型被拒绝 | 确认它是该父对象的直接、可查询、未列入黑名单的关系，并确认父子方向正确。 | | 附件或二进制文本缺失 | 这是预期行为。附件、base64、blob 与 encrypted-string 字段会被排除。 | | 父记录只包含部分子记录 | 标准管理后台流程始终使用增量子查询，因此首次运行与后续刷新中，每个直接关系都最多返回十条记录。如果每条子记录都必须可搜索，请在简单或高级模式中把该子对象类型配置为顶层父对象，让每条子记录形成独立文档，再验证代表性子记录。这不会让父文档包含十条以上子记录。 | | 轮询重新处理的数据超出预期 | OpenCore 使用 `LastModifiedDate`，再回退到 `CreatedDate`；两者都不可查询时不会按时间过滤该类型。时间边界由 OpenCore 添加。 | | 自动同步隐藏了所有 Salesforce 结果 | 确认 OpenCore 邮箱能映射到活动 Salesforce 用户名或邮箱，并且权限凭据可以查询 `UserRecordAccess`。权限错误会对 Salesforce chunk 失败关闭。 | | Sandbox 或多连接器下自动同步行为异常 | 查询时 client 不会携带摄取凭据的 sandbox-domain 设置。一个已启用的 Salesforce 自动同步源会触发租户内全部 Salesforce chunk 的裁剪，每个租户只缓存一个凭据支持的 client，且每次访问查询最多检查 200 个记录 ID。请测试每个环境、组织与凭据，或改用明确的 OpenCore 私有群组。 | ## 相关页面 * [连接器与索引](/opencore/knowledge/connectors) * [索引设置](/opencore/knowledge/index-settings)