Salesforce Source

Connect Salesforce CRM as a source to extract data from your sales, service, and marketing operations.

Prerequisites

Before you begin, ensure you have:

• ✅ Access to an active Salesforce org (API-enabled Salesforce edition required. Don't have one? Sign up for a free Developer Edition)
• ✅ A Salesforce account configured for Supaflow (Configure Salesforce Account)
• ✅ For OAuth: Connected App configured (recommended)
• ✅ For Basic Auth: Your Salesforce security token
• ✅ IP restrictions configured (if applicable)
• ✅ Whitelist Supaflow IP (If Required)

If your Salesforce org has IP restrictions enabled, add this IP to your Network Access settings:

18.214.240.61

To add: Setup → Security → Network Access → New

OAuth: Grant User Permission (Required)

To connect to Salesforce using Supaflow Connected app that isn't installed in your organization, you must grant users the permission "Approve Uninstalled Connected Apps" to connect to uninstalled apps. You can assign this permission either by adding it to an existing permission set or by enabling it directly on the user's profile that you want to connect to Supaflow.

Steps to enable permission:

1. Create or edit a permission set: Navigate to Setup → Search for and select Permission Sets → Click New or select an existing one
2. Add the permission: Select System Permissions → Click Edit → Find and select "Approve Uninstalled Connected Apps" → Click Save
3. Assign to user: Go to the user's profile → In Permission Set Assignments, click Edit Assignments → Add the permission set → Click Save

Learn more in Salesforce documentation →

Basic Authentication (Security Token Required)

If using Basic authentication, you'll need a security token:

1. Go to your Personal Settings in Salesforce
2. Click on "Reset My Security Token" under Personal Information
3. Check your email for the new security token

Learn more about security tokens →

Configuration

Step 1: Choose Authentication Method

Authentication Type*

Select your authentication method

Options:

• oauth (Recommended) - Secure browser-based authentication
• basic - Username/password with security token

---

Option A: OAuth Authentication (Recommended)

Salesforce Domain*

Your Salesforce instance domain
Example: login.salesforce.com (production)
Example: test.salesforce.com (sandbox)
Example: mydomain.my.salesforce.com (custom domain)

Authorize*

Click the "Authorize" button to:

• Redirect to Salesforce login
• Grant permissions to Supaflow
• Automatically configure tokens

---

Option B: Basic Authentication

Username*

Salesforce username
Example: john.doe@company.com

Password*

Salesforce password
Note: Do not include security token here

Security Token

Salesforce security token (see instructions above)
Optional - required for API access from untrusted networks

Salesforce Domain*

Your Salesforce instance domain
Example: login.salesforce.com (production)
Example: test.salesforce.com (sandbox)

---

Step 2: Advanced Settings (Optional)

API Version

Salesforce API version
Default: 63.0

Use Bulk API

Use Salesforce Bulk API for large data operations
Default: true (recommended for large volumes)

Batch Size

Number of records per batch
Default: 10000 (Range: 1-50000)

Max Retries

Maximum number of retry attempts for failed operations
Default: 3 (Range: 0-10)

Min Retry Sleep Seconds

Initial sleep time between retry attempts in seconds
Default: 2 (Range: 1-60)

Connection Timeout Milliseconds

Connection timeout in milliseconds
Default: 30000 (Range: 1000-300000)

Read Timeout Milliseconds

Read timeout in milliseconds
Default: 30000 (Range: 1000-300000)

Max Pool Size

Maximum Connection Pool Size
Default: 10 (Range: 1-10)

Schema Refresh Interval

Interval in minutes for schema metadata refresh
0 = refresh before every pipeline execution
-1 = disable schema refresh
Default: 0 (Range: -1 to 10080)

Lookback Time

Time in seconds to look back for late-arriving data
Default: 0 (no lookback)
Salesforce recommends: 600 seconds (10 minutes) for production
Range: 0-86400 seconds (24 hours)

---

Step 3: Test & Save

After configuring your authentication method, click Test & Save to verify your connection and save the source.

Picklist values and labels

If you have ever compared a synced record against the Salesforce UI and seen different text in the same field, you have met the difference between a picklist value and its label. Every picklist entry in Salesforce has two parts:

• The API value is what Salesforce actually stores on the record. It is stable by design: admins rarely change it, because integrations, automations, and historical records all reference it.
• The label is what users see in the Salesforce UI. Admins can rename labels at any time without touching the underlying data.

Supaflow syncs the API value -- the same thing every other integration sees. This is intentional: if an admin renames a label, your warehouse history stays consistent and nothing downstream breaks. But it means your warehouse can show Pending where the Salesforce UI shows Not Compared, or US where the UI shows United States.

To let you report with the labels your users recognize, the connector provides two system tables alongside your Salesforce objects. They appear in the schema selection like any other table -- select them and they sync into your destination.

SUPAFLOW_PICKLIST_FIELD

One row per picklist, multi-select picklist, or combobox field in your org. Use it to discover which fields have picklists and how they relate.

Column	Description
picklist_field_id	Key, <object>.<field>, for example Account.Industry
object_name	Object API name
field_name	Field API name
field_label	Field display label
field_type	picklist, multipicklist, or combobox
restricted	Whether the picklist is restricted to defined values
dependent	Whether the picklist depends on a controlling field
controller_name	Controlling field API name (null unless dependent)

SUPAFLOW_PICKLIST_FIELD_VALUE

One row per picklist entry -- this is the value-to-label dictionary you join against.

Column	Description
picklist_field_id	Key part, joins to SUPAFLOW_PICKLIST_FIELD
value	Stored/API value, for example Pending
label	Display label, for example Not Compared
value_index	Position in Salesforce's metadata ordering
active	Whether the value is currently active
default_value	Whether this is the field's default value
valid_for_base64	Raw dependent-picklist bitset (advanced; not decoded)

Querying labels

Join your object table to SUPAFLOW_PICKLIST_FIELD_VALUE once per picklist column you want to translate. The join key is the field's picklist_field_id (<Object>.<FieldName>) plus the stored value:

select
  a.name,
  a.industry            as industry_value,
  ind.label             as industry_label,
  a.billingcountrycode  as country_value,
  cc.label              as country_label,
  a.cleanstatus         as cleanstatus_value,
  cs.label              as cleanstatus_label
from salesforce.account a
left join salesforce.supaflow_picklist_field_value ind
  on ind.picklist_field_id = 'Account.Industry'
 and ind.value = a.industry
left join salesforce.supaflow_picklist_field_value cc
  on cc.picklist_field_id = 'Account.BillingCountryCode'
 and cc.value = a.billingcountrycode
left join salesforce.supaflow_picklist_field_value cs
  on cs.picklist_field_id = 'Account.CleanStatus'
 and cs.value = a.cleanstatus;

Example result:

NAME	INDUSTRY_VALUE	INDUSTRY_LABEL	COUNTRY_VALUE	COUNTRY_LABEL	CLEANSTATUS_VALUE	CLEANSTATUS_LABEL
Edge Communications	Electronics	Electronics	US	United States	Pending	Not Compared
GenePoint	Biotechnology	Biotechnology	US	United States	Pending	Not Compared

For many standard picklists (like Industry here) the label equals the value, and the join passes the value through unchanged. Where they differ -- country codes, status fields, or any picklist an admin has relabeled -- the join surfaces the label your users expect.

Use a left join rather than an inner join so records keep flowing even if a value has no matching picklist entry (for example, a value that was deleted in Salesforce after the record was created).

Dependent picklists

Salesforce lets one picklist control another: a controlling field (for example Country) decides which values of a dependent field (for example State) are available. In Salesforce metadata this relationship is stored as a compact bitset that is not practical to query directly, so the connector decodes it into a third system table:

SUPAFLOW_DEPENDENT_PICKLIST_RELATION

One row per valid combination of a dependent value and the controlling value that allows it.

Column	Description
dependent_picklist_field_id	The dependent field, <object>.<field>
dependent_value	Dependent picklist API value
controller_field_id	The controlling field, <object>.<field>
controller_value	Controlling API value this dependent value is valid for

A dependent value that is valid for several controlling values gets one row per combination.

Example 1 -- list the allowed values per controlling value, with display labels. Join the relation to SUPAFLOW_PICKLIST_FIELD_VALUE to bring in labels and active status -- useful for building cascading filters in BI tools:

select
  r.controller_value,
  r.dependent_value,
  pv.label  as dependent_label,
  pv.active
from salesforce.supaflow_dependent_picklist_relation r
left join salesforce.supaflow_picklist_field_value pv
  on pv.picklist_field_id = r.dependent_picklist_field_id
 and pv.value = r.dependent_value
order by r.controller_value, r.dependent_value;

CONTROLLER_VALUE	DEPENDENT_VALUE	DEPENDENT_LABEL	ACTIVE
Food	Eggs	Eggs	True
Food	Milk	Milk	True
Service	Consulting	Consulting	True

Example 2 -- flag records whose dependent value is not legal for their controlling value. Dependency rules are only enforced in the Salesforce UI; records created by integrations or loaded before a rule changed can hold combinations that are no longer valid. This anti-join surfaces them:

select a.id, a.country__c, a.state__c
from salesforce.account a
where a.state__c is not null
  and a.country__c is not null
  and not exists (
    select 1
    from salesforce.supaflow_dependent_picklist_relation r
    where r.dependent_picklist_field_id = 'Account.State__c'
      and r.dependent_value = a.state__c
      and r.controller_value = a.country__c
  );

One limitation: dependencies controlled by a checkbox (rather than another picklist) are not included in this table. Those fields still appear in SUPAFLOW_PICKLIST_FIELD with dependent set and the checkbox named in controller_name.

How fresh is the picklist data?

These tables are built from Salesforce metadata, not record data, and reload fully on each historical sync. Like other snapshot tables, they follow the pipeline's historical sync frequency -- weekly by default. If your team changes picklists often, set the frequency to daily or every run. Two details to be aware of:

• Renamed labels and activation changes update automatically on the next historical sync, because each entry's identity is its stable API value.
• Values deleted in Salesforce can linger in the destination until you re-sync the table with a reset, since Salesforce metadata carries no deletion marker.

Troubleshooting

Common issues and their solutions:

Authentication failed - OAuth

Problem:

• OAuth authorization fails
• "Approve Uninstalled Connected Apps" permission error
• Cannot complete authorization flow

Solutions:

1. Verify permission is granted:
   • Navigate to Setup → Permission Sets
   • Ensure "Approve Uninstalled Connected Apps" is enabled
   • Assign permission set to your user
2. Check organization settings:
   • Verify your org allows OAuth connections
   • Check if Connected Apps are blocked by admin
3. Clear browser cache and retry:
   • Sometimes cached auth tokens cause issues
   • Try in incognito/private mode
4. Use correct domain:
   • Production: login.salesforce.com
   • Sandbox: test.salesforce.com
   • Custom domain: yourdomain.my.salesforce.com

---

Authentication failed - Basic Auth

Problem:

• "Invalid username, password, security token" error
• Login fails with correct credentials
• Connection timeout

Solutions:

1. Verify security token:
   • Reset security token in Personal Settings
   • Check email for new token
   • Ensure you're using the latest token
2. Check IP restrictions:
   • Add Supaflow IP (18.214.240.61) to Network Access
   • Navigate to: Setup → Security → Network Access → New
3. Verify credentials:
   • Username should be full email (user@company.com)
   • Password should NOT include security token
   • Enter security token in separate field
4. Check domain:
   • Use login.salesforce.com for production
   • Use test.salesforce.com for sandbox

---

API limit exceeded

Problem:

• "API request limit exceeded" error
• Sync stops mid-process
• Cannot fetch data

Solutions:

1. Check API limits:
   • Navigate to: Setup → System Overview → API Usage
   • Verify daily and concurrent limits
2. Upgrade plan if needed:
   • Enterprise+ plans have higher limits
   • Consider purchasing additional API calls
3. Reduce batch size:
   • Lower batch size in Advanced Settings
   • Default 10000 → try 5000 or lower
4. Schedule during off-peak hours:
   • Run syncs when fewer users are active
   • Distribute load throughout the day

---

Objects not appearing in schema

Problem:

• Some Salesforce objects don't appear
• Custom objects missing
• Expected fields not visible

Solutions:

1. Verify object permissions:
   • Ensure user has read access to objects
   • Check field-level security settings
2. Refresh schema:
   • Set Schema Refresh Interval to 0
   • Force immediate schema refresh
3. Check custom object settings:
   • Verify custom objects are deployed
   • Ensure objects are not hidden
4. Review API visibility:
   • Some objects require special API access
   • Check Salesforce object documentation

---

Bulk API errors

Problem:

• Bulk API jobs fail
• Timeout errors with large datasets
• Inconsistent sync results

Solutions:

1. Verify Bulk API is enabled:
   • Check organization settings
   • Ensure user has Bulk API permissions
2. Adjust batch size:
   • Reduce batch size for complex objects
   • Try 5000 or lower for objects with many fields
3. Disable Bulk API if needed:
   • Set "Use Bulk API" to false
   • Uses REST API (slower but more reliable for small datasets)
4. Check governor limits:
   • Review Salesforce governor limits
   • Ensure you're within daily Bulk API limits

---

Connection timeout

Problem:

• Connection times out during setup
• Slow response from Salesforce
• Test connection fails with timeout

Solutions:

1. Increase timeout values:
   • Connection Timeout: try 60000ms (60s)
   • Read Timeout: try 60000ms (60s)
2. Check network connectivity:
   • Verify internet connection is stable
   • Check if corporate firewall blocks Salesforce
3. Verify Salesforce status:
   • Visit: Salesforce Trust Status
   • Check for ongoing incidents
4. Try different time:
   • Salesforce may be slow during peak hours
   • Retry during off-peak hours

Support

Need help? Contact us at support@supa-flow.io