Salesforce Setup

This guide will walk you through configuring your Salesforce organization to work with Sync or Swim.

Overview

To connect Sync or Swim to your Salesforce organization, you’ll need to:

1. Create a Salesforce Connected App
2. Configure OAuth settings
3. Generate your security token
4. Gather credentials for Sync or Swim configuration

Note

Connected App creation cannot be automated and must be done manually by a Salesforce administrator. This is a Salesforce platform requirement for security purposes.

Prerequisites

• Salesforce Administrator access
• Salesforce edition: Any edition (Professional, Enterprise, Unlimited, Developer)
• API access enabled for your organization

Setup Steps

1. Create a Connected App

   A Connected App allows Sync or Swim to authenticate and communicate with your Salesforce organization using OAuth 2.0.

   Navigate to Setup:

   1. Log in to your Salesforce organization
   2. Click the gear icon in the upper right corner
   3. Select Setup

   Create the App:

   1. In the Quick Find box, type App Manager
   2. Click App Manager
   3. Click New Connected App (upper right)

   Configure Basic Information:

   • Connected App Name: Sync or Swim Data Sync (or your preferred name)
   • API Name: This auto-populates based on the name
   • Contact Email: Your administrator email address

2. Configure OAuth Settings

   1. Check the box Enable OAuth Settings

   2. Callback URL: Enter a placeholder URL (required but not used for username-password flow)

      https://login.salesforce.com/services/oauth2/callback

   3. Selected OAuth Scopes: Add the following scopes:

      • Access and manage your data (api)
      • Perform requests on your behalf at any time (refresh_token, offline_access)
      • Access your basic information (id, profile, email, address, phone)

   4. Leave other settings at their defaults

   5. Click Save, then Continue

3. Retrieve Consumer Key and Secret

   1. On the Connected App detail page, find the API (Enable OAuth Settings) section
   2. Click Manage Consumer Details
   3. Verify your identity (you may need to enter a verification code sent to your email)
   4. Copy and save:
      • Consumer Key (this is your client_id)
      • Consumer Secret (this is your client_secret)

4. Generate Security Token

   Salesforce requires a security token when accessing the API from outside your organization’s trusted IP ranges.

   1. Click your profile picture in the upper right
   2. Select Settings
   3. Navigate to My Personal Information > Reset My Security Token
   4. Click Reset Security Token
   5. Check your email for the new security token

5. Configure Sync or Swim

   1. Navigate to /settings in the Sync or Swim web interface
   2. Click “Add Service”
   3. Select “Salesforce” as the adapter type
   4. Enter your credentials:
      • Instance URL: Your Salesforce instance URL (e.g., https://na1.salesforce.com)
      • Host: login.salesforce.com (production) or test.salesforce.com (sandbox)
      • Username: Your Salesforce username
      • Password: Your Salesforce password
      • Security Token: Token from Step 4
      • Client ID: Consumer Key from Step 3
      • Client Secret: Consumer Secret from Step 3
   5. Click “Test Connection” to verify
   6. Click “Create Service” to save

Required Credentials Summary

Field	Description	Example
Instance URL	Your Salesforce instance URL	https://na1.salesforce.com
Host	Login host	login.salesforce.com (production) or test.salesforce.com (sandbox)
Username	Your Salesforce username	[email protected]
Password	Your Salesforce password	Your account password
Security Token	Token from email	Emailed to you
Client ID	Consumer Key	Starts with 3MVG9...
Client Secret	Consumer Secret	Long alphanumeric string

Tip

Finding Your Instance URL: While logged into Salesforce, look at your browser’s address bar. The format is https://[instance].salesforce.com or https://[domain].my.salesforce.com.

Troubleshooting

”Invalid Grant” Error

Cause: Usually indicates incorrect credentials or an expired security token.

Solutions:

• Verify your username and password are correct
• Reset your security token and update the configuration
• Ensure you’re using the correct host (login.salesforce.com vs test.salesforce.com)

“Invalid Client” Error

Cause: Incorrect Consumer Key (client_id) or Consumer Secret (client_secret).

Solutions:

• Re-check the Consumer Key and Secret from your Connected App
• Ensure you copied them completely (they can be very long)
• Verify the Connected App is active

”Insufficient Privileges” Error

Cause: The user account doesn’t have necessary permissions.

Solutions:

• Ensure the user has API access enabled
• Check the user’s profile has appropriate object and field permissions
• Verify the OAuth scopes in the Connected App include api access

API Rate Limits

Sync or Swim uses polling-based synchronization which consumes API calls:

• Typical usage: ~1,500-2,000 API calls per day (20 objects, 60-second polling)
• Enterprise edition: 1,000+ calls per user per day
• Unlimited/Performance editions: Higher limits

To monitor API usage:

1. Setup > System Overview > API Usage
2. Track daily API call consumption
3. Adjust polling frequency if needed

Security Best Practices

1. Use a dedicated integration user: Create a specific Salesforce user for Sync or Swim integration
2. Apply least privilege: Grant only the permissions needed for synchronization
3. Rotate credentials regularly: Update passwords and security tokens periodically
4. Monitor access: Review login history and API usage regularly
5. Use IP restrictions: Configure trusted IP ranges in the Connected App if possible

Additional Resources

• Salesforce Connected Apps Documentation
• OAuth 2.0 Username-Password Flow
• API Rate Limits

Support

If you encounter issues not covered in this guide, please contact Sync or Swim support with:

• Error messages from the Sync or Swim logs
• Salesforce edition and API version
• Connected App configuration (without credentials)