OpenCoreDocuments & KnowledgeConnectors

Salesforce

View as Markdown

What it indexes

The Salesforce connector creates one searchable document for each configured parent record. The document starts with that record’s queryable fields and can include direct child records as additional linked sections.

BehaviorIndexing effect
Default scopeIn Simple mode, an empty requested-object list defaults to Account. Otherwise, each singular object name is treated as a parent type.
Simple modeOpenCore requests all queryable fields for the parent types and discovers supported direct child relationships. Base64, blob, encrypted-string, blacklisted, and non-queryable data is excluded.
Advanced modeA JSON object defines parent fields and direct associations. OpenCore still adds Id, LastModifiedDate, and CreatedDate when that date field is queryable.
Child limitsAttachments are skipped. Standard Admin indexing uses delta polling on the first and later indexing attempts, and every direct child relationship query uses LIMIT 10. The Admin flow does not provide a full reconstruction that bypasses this limit.

Record fields are converted to searchable key-value text. The parent Name, or its Id when no name exists, becomes the semantic identifier. Record and child links point to the authenticated Salesforce instance.

Prerequisites

  • Create a dedicated Salesforce integration user that can log in through the API and read every parent object, field, and direct child relationship in scope.
  • Allow REST describe/query access and Bulk API 2.0 query/export access.
  • Obtain the integration user’s username, password, and security token.
  • Decide whether the credential targets production or a Salesforce sandbox.
  • For Advanced mode, confirm the exact case-sensitive API names of parent objects, fields, child object types, and relationships.
  • If using Auto Sync Permissions, make sure search users’ OpenCore email addresses match an active Salesforce Username or Email, and allow queries to User and UserRecordAccess.

Credentials

EnvironmentOpenCore credential valuesAuthentication behavior
Productionsf_username: <SALESFORCE_USERNAME>, sf_password: <SALESFORCE_PASSWORD>, sf_security_token: <SALESFORCE_SECURITY_TOKEN>, is_sandbox: falseUses Salesforce username-password-token authentication against the default production login domain.
Sandboxsf_username: <SALESFORCE_USERNAME>, sf_password: <SALESFORCE_PASSWORD>, sf_security_token: <SALESFORCE_SECURITY_TOKEN>, is_sandbox: trueUses the same credential fields but selects the Salesforce test login domain for ingestion.

The current Admin credential does not accept a Salesforce OAuth client ID, client secret, refresh token, or instance URL. Do not substitute those values for the username-password-security-token fields.

Configure in OpenCore

  1. In the Admin panel, open Connectors, select Salesforce, and create the production or sandbox credential.
  2. Choose Simple or Advanced under Configuration Type.
  3. For Simple, enter zero or more singular Salesforce object API names. Leave the list empty only when Account is the intended parent type.
  4. For Advanced, enter a JSON object whose top-level keys are parent object types. Use fields for parent fields and associations to map direct child object types to their fields. This is configuration JSON, not an arbitrary SOQL query.
  5. Choose the document-access mode. Enable Auto Sync Permissions only after validating its query-time behavior with representative users and records.
  6. Set refresh and cleanup options, create the connector, and run the first indexing attempt.

The standard Admin flow creates a polling connector, and the runner selects poll_source before any load path. As a result, the first and later indexing attempts use delta polling; even an effective poll start at Unix epoch 0 does not invoke Salesforce’s separate full-load implementation. Without Indexing Start, the first effective poll start is epoch 0. With Indexing Start, that date restricts the first window after the shared scheduler applies its current 30-minute overlap. Treat the effective poll start, rather than a full-export assumption, as the historical coverage boundary.

Permissions

The ingestion credential determines which Salesforce records and fields OpenCore can retrieve. Without Auto Sync Permissions, Salesforce record access is not synchronized; search access is controlled only by the connector’s OpenCore Private groups or Public mode.

When Auto Sync Permissions is selected and the permission feature is available, OpenCore performs query-time censoring instead of storing a static record ACL. It resolves the searcher’s email first against an active Salesforce Username, then against Email, and queries UserRecordAccess.HasReadAccess for record IDs represented by each result’s source links. Content sections whose Salesforce record is not readable are removed; an unmapped user or a permission-check failure returns no Salesforce chunks from that check.

This behavior has additional current scope constraints. If any Salesforce connector for a tenant enables Auto Sync, all Salesforce result chunks for that tenant are sent through censoring, including chunks from another Salesforce connector that did not select Auto Sync. The permission client is cached per tenant from one associated connector credential and does not propagate the ingestion credential’s sandbox-domain setting. Each record-access query evaluates at most the first 200 record IDs; omitted IDs fail closed. Deployments with sandboxes, multiple Salesforce orgs, or multiple credentials must verify every combination explicitly.

Verify

  1. Validate the connector and confirm the global Salesforce describe request succeeds.
  2. Run the first sync and search for a configured parent record and one expected direct child value. If Indexing Start is set, also check one record inside the effective window and one well before the configured date and its 30-minute overlap; without it, check an older expected record.
  3. Confirm an unrequested parent type is absent. In Advanced mode, also confirm an omitted field and association are absent.
  4. Check a parent with more than ten direct children on both the first run and a later refresh. Expect no more than ten child rows from each direct relationship in either document version.
  5. Open parent and child citations using a Salesforce-authorized browser session.
  6. If using Auto Sync Permissions, test a mapped active user, a user without record read access, an email with no active Salesforce match, every Salesforce org/credential, and a connector that did not itself enable Auto Sync.

Troubleshooting

SymptomWhat to check
Login failsVerify the username, password, security token, and Is Sandbox Environment setting. The connector does not use OAuth credentials.
Validation succeeds but indexing failsValidation checks authenticated global describe and the JSON shape. Confirm each configured object, field, and child association actually exists and is queryable.
Empty Simple configuration indexes unexpected dataEmpty Simple scope means Account. Enter explicit singular object API names when a different scope is required.
Advanced configuration is rejectedEnsure every top-level value is an object, fields is a string list, and associations maps child object names to string lists.
A child type is rejectedConfirm it is a direct, queryable, non-blacklisted relationship of that parent and that the parent-child direction is correct.
Attachment or binary text is missingThis is expected. Attachments, base64, blob, and encrypted-string fields are excluded.
A parent record has only some childrenThe standard Admin flow always uses delta child queries, which return at most ten records per direct relationship on both the first run and later refreshes. If every child must be searchable, configure that child object type as a top-level parent object in Simple or Advanced mode so each child becomes its own document, then verify representative child records. This does not place more than ten children inside the parent document.
Polling reprocesses more data than expectedOpenCore uses LastModifiedDate, falls back to CreatedDate, and leaves a type unfiltered when neither is queryable. Time bounds are added by OpenCore.
Auto Sync hides every Salesforce resultConfirm the OpenCore email maps to an active Salesforce username or email and the permission credential can query UserRecordAccess. Permission errors fail closed for Salesforce chunks.
Auto Sync behaves unexpectedly with sandbox or multiple connectorsThe query-time client does not carry the ingestion credential’s sandbox-domain setting. One enabled Salesforce Auto Sync source triggers censoring for all Salesforce chunks in the tenant, one credential-backed client is cached per tenant, and access checks evaluate at most 200 record IDs per query. Test each environment, org, and credential or use explicit OpenCore Private groups.