Salesforce Connector

Index top level resources such as Accounts, Contacts, Cases, Opportunities, Leads by installing an External Client App.

The Salesforce connector enables the indexing of Salesforce objects, such as Accounts and Opportunities, using the Salesforce REST API by creating an External Client App in your Salesforce instance.

Note: Salesforce’s External Client Apps (ECA) are the successor to the legacy Connected Apps and follow a least-privilege model with explicit permission grants.

Setup External Client App

Note: The setup assumes that you are using the lightning experience of Salesforce.

Identify the integration user

Before creating the External Client App, identify or create the Salesforce user that Atolio will run as. Later steps grant this user access to the app and permission to read data.

As a best practice, we recommend a dedicated user rather than a real person’s account (turnover, MFA, password resets on a human account will break the integration). Any Salesforce user license works — a Salesforce Integration license is the cheapest option and is designed for this use case.

To create one: Setup → Users → Users → New User. Note the username; you will reference this user in the steps below as the integration user.

Create the External Client App

  1. As an administrator, navigate to Setup.
  2. In the Quick Find box, search for “External Client App Manager” and open it.
  3. Click “New External Client App”.
  • Choose an External Client App Name and API Name, e.g. Atolio.
  • Choose an email for Contact Email.
  • (Optional) For Logo Image URL and/or Icon URL, you can use the Atolio logo here.
  1. Under “API (Enable OAuth Settings)”, select Enable OAuth.
  • For Callback URL, enter a valid URL (e.g. https://atolio.example.com) — Atolio does not use this login flow for authentication.
  • For Selected OAuth Scopes, add only the “Manage user data via APIs (api)” scope. Do not add the “Full access (full)” scope — Salesforce now rejects token requests for External Client Apps configured with overly broad scopes.
  • Under “Flow Enablement”, check Enable Client Credentials Flow and acknowledge the security prompt.
  1. Click “Create” to save the External Client App.

Next, configure the app’s policies:

  1. From the External Client App Manager, open your new app and go to the “Policies” tab, then click “Edit”.
  2. Under “OAuth Policies”:
  • Set Permitted Users to “Admin approved users are pre-authorized”.
  • Check “Enable Client Credentials Flow”, and under the newly revealed Run As section, set Run As to the integration user identified above.
  1. Save the policy changes.

Finally, grant the integration user access to the External Client App. Unlike Connected Apps, ECAs require explicit assignment via a permission set (profile-based access is not supported):

  1. From Setup, navigate to “Users” -> “Permission Sets” and click “New”.
  2. Give the permission set a name (e.g. Atolio External Client App Access) and save.
  3. Open the new permission set and go to “External Client App Access Settings” (or “Assigned External Client Apps”, depending on your org).
  4. Enable your Atolio External Client App.
  5. Assign this permission set to the integration user identified above.

Integration User Permissions

Access to the External Client App only lets the integration user authenticate — it does not grant permission to read any data. Grant the following on the integration user’s profile or via a separate permission set.

Objects the connector reads

The Salesforce connector supports indexing a range of standard objects, including:

  • Account
  • Contact
  • Case
  • Lead
  • Opportunity
  • Report
  • Profile

Additonally, metadata objects (PermissionSet, User, UserRole, Group, EntityDefinition, etc.) are indexed in support of delivering secure permissions. These objects must be readable under any permissions scheme.

Permissions

The connector’s default behavior is to index every record in the org and compute per-record ACLs from Salesforce’s sharing model. The integration user must therefore be able to read every record which is desired to be indexed.

For the common case of indexing an entire organization, grant the integration user a permission set with:

  • Object permissions on Account, Contact, Case, Lead, Opportunity, and Report: Read plus View All Records. Object-level Read alone restricts the user to records they own or that are shared with them; View All Records is what lets the connector see every record regardless of the sharing model.
  • The API Enabled system permission (granted by default under the Salesforce Integration user license).

The metadata Atolio reads to compute ACLs (PermissionSet, PermissionSetAssignment, ObjectPermissions, Profile, UserRole, EntityDefinition, Folder, Group, GroupMember) is served through the standard Data API and is queryable by any user with API access.

Scoping to a subset of records

If instead you want Atolio to index only a subset of records (e.g. one region’s accounts, one business unit’s opportunities), omit View All Records on the corresponding objects and let Salesforce’s sharing model do the scoping. Configure the integration user’s visibility through the standard Salesforce mechanisms: placing them at an appropriate role in the hierarchy, defining ownership-based or criteria-based sharing rules, or manually sharing records with them. The connector will then index only what that integration user can see. Object-level Read is still required.

If the integration user is scoped down, the connector will still run to completion and will silently omit records the integration user is not entitled to see via ownership, the role hierarchy, or sharing rules.

To restrict which fields get indexed:

  • Restrict the integration user’s field-level security on their profile, and/or
  • Use the field_filters option in the source configuration (see below).
The field_filters configuration option

field_filters lets you tell the connector which fields of a given Salesforce object should be indexed as metadata on the corresponding Atolio record. It is applied per-object, using the Salesforce API name of each object as the key.

Each entry accepts two optional lists:

  • included: an allow-list of field API names. If omitted or empty, every field returned by the Salesforce describe call is included.
  • excluded: a deny-list of field API names. If omitted or empty, nothing is excluded.

Exclusion takes precedence over inclusion — if a field appears in both lists, it is excluded.

Example:

field_filters:
  Account:
    included:
      - Name
      - Industry
      - AnnualRevenue
      - Website
    excluded:
      - Description
  Opportunity:
    excluded:
      - ForecastCategoryName
      - NextStep

In this example:

  • For Account, only the four included fields are indexed (and Description would be excluded even if it were listed in included).
  • For Opportunity, every field is indexed except ForecastCategoryName and NextStep.
  • Any object not listed in field_filters (e.g. Contact, Case, Lead, Report) has all of its fields indexed by default.

Use field API names (as they appear in Salesforce’s schema, including the __c suffix for custom fields), not display labels.

Provide Configuration

To obtain the necessary client credentials:

  1. From the External Client App Manager, open your Atolio app and go to the “Settings” tab.
  2. Under “OAuth Settings”, click “Consumer Key and Secret” → “Manage Consumer Details”.
  3. Copy the “Consumer Key” and “Consumer Secret” to be shared with your Deployment Engineer.

Provide the following values to your Deployment Engineer for them to configure in Atolio:

  • base_url is the URL of your Salesforce tenant, e.g. https://yourcompany.my.salesforce.com.
  • client_id is the “Consumer Key” of the External Client App you created.
  • client_secret is the “Consumer Secret” of the External Client App you created.

Streaming Configuration

To periodically sync updates in Salesforce to the Atolio index, we need to set the cron-spec. The recommended value is (*/10 * * * *). This would fetch updates from Salesforce every 10 minutes. We also need to set complete_backfill_frequency. This, alongside the cron-spec, controls how often the connector performs a complete backfill of the data (to capture ACL changes). For example, setting a value of 24 would mean that every 24th call to backfill would be a complete fill. This combined with a cron-spec of every 10 minutes, a complete backfill would happen every 4 hours. The recommended value is 48 so a complete backfill happens every 8 hours. This value can be tweaked to reduce the number of API calls. Generally, we want to use a higher value for larger datasets so the connector performs a complete backfill less frequently.