Skip to main content

Salesforce

This page contains the setup guide and reference information for the Salesforce source connector.

Prerequisites​

  • A Salesforce Account with Enterprise edition or Professional edition with API access purchased as an add-on

You may also need the following. This article explains how to get them.

  • For Calabi Connect: Salesforce OAuth credentials

Setup guide​

Set up Salesforce​

Create a dedicated Salesforce user (optional, but recommended)​

Follow the instructions below to create a Minimum Access standard profile and assign custom permission sets to grant the new user the read access needed for data you want to access with Calabi Connect.

While you can set up the Salesforce connector using any Salesforce user with read permission, we recommend creating a dedicated user with the Minimum Access standard profile for Calabi Connect. This allows you to granularly control the data Calabi Connect can read.

Using Permission Sets, you should grant this user read access to the data you want Calabi Connect to have access to. Learn more about Permission sets by referring to Salesforce's documentation. If you want to sync permissions data from Salesforce, you also need the permissions necessary to sync security-related data.

Log in to Salesforce with an admin account.

Step 1: Create a new user​
  1. On the top right of the screen, click the gear icon and then click Setup.
  2. In the left navigation bar, under Administration, click Users > Users. Create a new User, entering details for the user's first name, last name, alias, and email. Filling in the email field auto-populates the username field and nickname.
    1. Leave role unspecified
    2. Select Salesforce for the User License
    3. Select Standard User for Profile.
    4. Decide whether to generate a new password and notify the user.
    5. Select save
Step 2: Create a new permission set​
  1. Using the left navigation bar, select Users > Permission Sets
  2. Click New to create a new Permission Set.
  3. Give your permission set a descriptive label name (e.g., "Calabi Connect Read Only Access"). The API name auto-populates based on the label you give the permission set.
  4. For licence, leave this set to –None— and click save.
  5. Now that you see the permission set is created, define the permissions via Object Settings.
    1. Click "Object Settings."
    2. Select the Object Name for each object you want the user to have read-only access to (for example, Accounts, Contacts, Opportunities).
    3. Select “Edit” and check the "Read" permission and clear all other permissions (Create, Edit, Delete, etc.)
    4. Click Save
    5. Continue to add read permissions for any objects you want Calabi Connect to have access to.
  6. To grant access to uninstalled connected apps, you need to enable additional permission.
    1. Click "System Permissions"
    2. Select “Edit”
    3. If API Access Control is enabled, need to check the "Use Any API Client" permission. If API Access Control isn't enabled, need to check “Approve Uninstalled Connected Apps” permission.
    4. Click Save
Step 3: Assign the permission set to the new user​
  1. From the Permission Sets page, click "Manage Assignments" next to the read-only permission set you just created.
  2. Click "Add Assignments."
  3. Find and select the user you created in Step 1.
  4. Click Assign

Log into the email you used above and verify your new Salesforce account user. You'll need to set a password as part of this process. Keep this password accessible.

info

Profile vs. Permission Set: remember that the user's profile provides their baseline permissions. The permission set adds or restricts permissions on top of that. Object-Level vs. Field-Level Security: This guide focuses on object-level read-only access. While setting up your permission set, you can stick with object-level security or define more granular controls by scrolling down within each object settings page to select read access for only needed fields.

Get Salesforce OAuth credentials (Calabi Connect only)​

If you are using Calabi Connect, obtain the following OAuth credentials to authenticate:

  • Client ID
  • Client Secret
  • Refresh Token

To obtain these credentials, follow this walkthrough with the following modifications:

  1. If your Salesforce URL is not in the X.salesforce.com format, use your Salesforce domain name. For example, if your Salesforce URL is awesomecompany.force.com then use that instead of awesomecompany.salesforce.com.
  2. When running a curl command, run it with the -L option to follow any redirects.
  3. If you created a read-only user, use the user credentials when logging in to generate OAuth tokens.

Set up the Salesforce connector in Calabi Connect​

For Calabi Connect:​

  1. Log into your Calabi Connect account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Salesforce from the Source type dropdown.
  4. Enter a name for the Salesforce connector.
  5. To authenticate: For Calabi Connect: Click Authenticate your account to authorize your Salesforce account. Calabi Connect will authenticate the Salesforce account you are already logged in to. Please make sure you are logged into the right account.
  6. Toggle whether your Salesforce account is a Sandbox account or a production account.
  7. (Optional) For Start Date, use the provided datepicker or enter the date programmatically in either YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ format. The data added on and after this date will be replicated. If this field is left blank, Calabi Connect will replicate the data for the last two years by default. Please note that timestamps are in UTC.
  8. (Optional) In the Filter Salesforce Object section, you may choose to target specific data for replication. To do so, click Add, then select the relevant criteria from the Search criteria dropdown. For Search value, add the search terms relevant to you. You may add multiple filters. If no filters are specified, Calabi Connect will replicate all data.
  9. (Optional) For Lookback Window, enter an ISO 8601 duration (e.g., PT10M, PT30M, PT1H) to control how far back the connector re-reads data on each incremental sync. The default is PT10M (10 minutes). Increase this value if you observe missing records in your destination, which can occur due to Salesforce API eventual consistency delays.
  10. Click Set up source and wait for the tests to complete.

For Calabi Connect:​

  1. Navigate to the Calabi Connect dashboard.
  2. In the left navigation bar, click Sources. In the top-right corner, click + New source.
  3. Find and select Salesforce from the list of available sources.
  4. Enter a Source name of your choosing to help you identify this source.
  5. To authenticate: For Calabi Connect: Enter your Client ID, Client Secret, and Refresh Token.
  6. Toggle whether your Salesforce account is a Sandbox account or a production account.
  7. (Optional) For Start Date, use the provided datepicker or enter the date programmatically in either YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ format. The data added on and after this date will be replicated. If this field is left blank, Calabi Connect will replicate the data for the last two years by default. Please note that timestamps are in UTC.
  8. (Optional) In the Filter Salesforce Object section, you may choose to target specific data for replication. To do so, click Add, then select the relevant criteria from the Search criteria dropdown. For Search value, add the search terms relevant to you. You may add multiple filters. If no filters are specified, Calabi Connect will replicate all data.
  9. (Optional) For Lookback Window, enter an ISO 8601 duration (e.g., PT10M, PT30M, PT1H) to control how far back the connector re-reads data on each incremental sync. The default is PT10M (10 minutes). Increase this value if you observe missing records in your destination, which can occur due to Salesforce API eventual consistency delays.
  10. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Salesforce source connector supports the following sync modes:

Supported Streams​

The Salesforce connector supports reading both Standard Objects and Custom Objects from Salesforce. Each object is read as a separate stream. See a list of all Salesforce Standard Objects here.

Calabi Connect allows exporting all available Salesforce objects dynamically based on:

  • If the authenticated Salesforce user has the Role and Permissions to read and fetch objects. This would be set as part of the Permission Set you assign to the Calabi Connect user. See Create a dedicated Salesforce user for more information.
  • If the Salesforce object has the queryable property set to true. Calabi Connect can only fetch objects which are queryable. If you don’t see an object available via Calabi Connect, and it is queryable, check if it is API-accessible to the Salesforce user you authenticated with.

Syncing Permissions Data from Salesforce​

The Salesforce connector can be used to sync security-related objects that can be synced to understand user permissions, roles, and access patterns within your Salesforce organization.

Common use cases for syncing Salesforce permission data include:

  • Permission Replication: Leverage permissions from the Salesforce source to guide application of permissions downstream.
  • Security Auditing: Generate reports on user access rights and permission assignments.

The following streams contain security and permission-related data:

  • User - Core user accounts with security-related fields including profiles, roles, and user permissions. Contains information about user status, login history, and assigned licenses.
  • ActivePermSetLicenseMetric - Tracks permission set license usage metrics including assigned user counts, active user counts, and total available licenses.
  • ActiveProfileMetric - Provides metrics about user profile usage including user license associations and assignment counts.

For comprehensive information about Salesforce security objects, refer to the Salesforce Object Reference documentation.

How Salesforce Permission Syncing Works​

Salesforce provides some security-related data through its standard object model:

  1. Dynamic Object Discovery: The connector automatically discovers available Salesforce objects (sobjects) based on the authenticated user's permissions.
  2. Permission-Based Access: Which security objects are available depends on the permissions granted to the Salesforce user used for authentication and your Salesforce environment configuration.
  3. Standard Object Syncing: Available security-related objects are synced as regular Salesforce objects through the same sync mechanisms as other business data.
note

Security-related object availability varies by Salesforce environment (production vs sandbox) and user permissions. Security objects can be large datasets in organizations with many users, so monitor your Salesforce API limits accordingly.

Permissions Needed to Sync Permissions Data​

To sync security-related data from Salesforce, the authenticated Salesforce user must have appropriate permissions to read security objects. Consider granting these permissions through a dedicated permission set:

  • "View All Users" - Required to access comprehensive User data.
  • Standard read permissions for the specific objects you want to sync.

For more information about Salesforce security and permissions, refer to the official Salesforce documentation on User Permissions and Permission Sets.

Limitations & Troubleshooting​

Expand to see details about Salesforce connector limitations and troubleshooting.

Connector limitations​

Rate limiting​

The Salesforce connector is restricted by Salesforce's Daily Rate Limits. The connector syncs data until it hits the daily rate limit, then ends the sync early with success status, and starts the next sync from where it left off. Note that picking up from where it ends will work only for incremental sync, which is why we recommend using the Incremental Sync - Append + Deduped sync mode.

Syncing Formula Fields​

The Salesforce connector syncs formula field outputs from Salesforce. If the formula of a field changes in Salesforce and no other field on the record is updated, you will need to reset the stream and sync a historical backfill to pull in all the updated values of the field.

Syncing Deletes​

The Salesforce connector supports retrieving deleted records from the Salesforce recycle bin. For the streams which support it, a deleted record will be marked with isDeleted=true. To find out more about how Salesforce manages records in the recycle bin, please visit their docs.

Usage of the BULK API vs REST API​

Salesforce allows extracting data using either the BULK API or REST API. To achieve fast performance, Salesforce recommends using the BULK API for extracting larger amounts of data (more than 2,000 records). For this reason, the Salesforce connector uses the BULK API by default to extract any Salesforce objects, unless any of the following conditions are met:

  • The Salesforce object has columns which are unsupported by the BULK API, like columns with a base64 or complexvalue type
  • The Salesforce object is not supported by BULK API. In this case we sync the objects via the REST API which will occasionally cost more of your API quota. This includes the following objects:
    • AcceptedEventRelation
    • Attachment
    • CaseStatus
    • ContractStatus
    • DeclinedEventRelation
    • FieldSecurityClassification
    • KnowledgeArticle
    • KnowledgeArticleVersion
    • KnowledgeArticleVersionHistory
    • KnowledgeArticleViewStat
    • KnowledgeArticleVoteStat
    • OrderStatus
    • PartnerRole
    • RecentlyViewed
    • ServiceAppointmentStatus
    • ShiftStatus
    • SolutionStatus
    • TaskPriority
    • TaskStatus
    • UndecidedEventRelation

More information on the differences between various Salesforce APIs can be found here.

Force Using Bulk API

If you set the Force Use Bulk API option to true, the connector will ignore unsupported properties and sync streams using BULK API.

Missing Records (Salesforce API Eventual Consistency)​

Salesforce does not guarantee that recently created or updated records are immediately available through its API. A record may have its SystemModStamp set, but the underlying transaction may not yet be committed. During an incremental sync, the connector can advance its cursor past such records, causing them to be permanently missed in subsequent syncs.

Symptoms:

  • Records are missing in the destination but present when queried directly in Salesforce
  • The same source synced to a different destination at a later time does not have missing records
  • No errors appear in sync logs

Solution: Increase the Lookback Window in the connector configuration. This controls how far back the connector re-reads data from the last cursor position on each incremental sync. The default is PT10M (10 minutes). If you observe missing records, try increasing it to PT30M (30 minutes) or PT1H (1 hour). Because the connector uses append-dedup mode, re-reading overlapping data does not create duplicates in the destination.

The lookback window uses the ISO 8601 duration format. The format is PT<number><unit>, where P marks the start of the duration and T separates date from time components. Common examples:

ValueMeaning
PT10M10 minutes
PT30M30 minutes
PT1H1 hour
PT2H2 hours
P1D1 day