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

Step 1: Create a Connected App

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

1.1 Navigate to Setup

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

1.2 Create the Connected App

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

1.3 Configure Basic Information

Fill in the following fields:

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

1.4 Configure API (Enable 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 by selecting them and clicking the Add arrow:

   • 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. Enable for Device Flow: Leave unchecked

5. Require Secret for Web Server Flow: Leave checked (default)

6. Require Secret for Refresh Token Flow: Leave checked (default)

1.5 Save and Continue

1. Click Save
2. Click Continue on the confirmation screen
3. You’ll be redirected to the Connected App detail page

1.6 Retrieve Your Consumer Key and Secret

Important: You’ll need these credentials to configure Sync or Swim.

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 the following values securely:
   • Consumer Key (this is your client_id)
   • Consumer Secret (this is your client_secret)

Security Note: Keep these credentials secure. Do not share them or commit them to version control.

Step 2: Generate Security Token

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

2.1 Navigate to Personal Settings

1. Click your profile picture in the upper right
2. Select Settings

2.2 Reset Security Token

1. In the left sidebar, navigate to My Personal Information → Reset My Security Token
2. Click Reset Security Token
3. Salesforce will email your new security token to your email address
4. Save this token securely

Note: Your security token is different from your password. If you change your password, your security token is also reset.

Step 3: Gather Required Information

You’ll need the following information to configure Sync or Swim:

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

Finding Your Instance URL

1. While logged into Salesforce, look at your browser’s address bar
2. The format is: https://[instance].salesforce.com or https://[domain].my.salesforce.com
3. For Classic UI: Use https://[instance].salesforce.com
4. For Lightning: Use https://[domain].my.salesforce.com or https://[instance].salesforce.com

Production vs Sandbox

• Production: Use login.salesforce.com as the host
• Sandbox: Use test.salesforce.com as the host

Step 4: Configure Sync or Swim

Once you have all the credentials, you can configure Sync or Swim with your Salesforce service:

# In your sync_config.yaml or via the UI
services:
  - name: "salesforce_prod"
    type: "salesforce"
    credentials:
      instance_url: "https://na1.salesforce.com"
      host: "login.salesforce.com"
      username: "admin@company.com"
      password: "your_password"
      security_token: "your_security_token"
      client_id: "3MVG9..."
      client_secret: "your_client_secret"

Step 5: Verify Connection

After configuring Sync or Swim, test the connection:

1. Start or restart the Sync or Swim application
2. Navigate to the dashboard
3. Check the service status - it should show as “Connected”
4. If there are connection errors, verify:
   • All credentials are correct
   • The security token is current
   • The Connected App is active
   • Your IP address is allowed (or use security token)

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 your Sync or Swim support team with:

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