Configuring Salesforce Integration + Writeback

Rox periodically pulls Salesforce data into a managed warehouse. The integration user's permissions determine which data Rox can access. An Organization Admin configures the fields and activities Rox writes back.

Complete the setup in three stages: prepare the Salesforce integration user, complete onboarding in Rox, then manage mappings and activity writeback in Settings → Integrations → Salesforce. Test sync is available during onboarding only.

Before you begin

You need:

• A Rox Organization Admin to complete setup in Rox.

• A Salesforce administrator who can manage users, licenses, and permission sets.

• A Salesforce user with API access enabled. Use a dedicated integration user so Rox activity is easy to audit.

For the simplest setup, use a dedicated user with a full Salesforce license and the System Administrator profile. For restricted access, configure a custom permission set before connecting.

Activity writeback requires a full Salesforce license under the setup described here. The API-only Salesforce Integration license is supported for read sync or core entity writeback, but not activity writeback.

Create or confirm the integration user

1. In Salesforce, go to Setup → Administration → Users → Users.

2. Create a dedicated integration user or select the user you will connect.

3. Use the Salesforce license if you need activity writeback.

4. Assign the System Administrator profile for the full-access setup, or configure the restricted permissions below.

5. Complete the user's account details and confirm API Enabled is selected.

Create Salesforce integration user

Confirm Salesforce user details

Objects and required fields

Rox supports Account, Contact, Lead, Opportunity, Opportunity Contact Role, Opportunity Stage, Campaign, and Campaign Member. Rox also syncs User and Task data to support functionality such as account assignment and activity writeback.

During onboarding, map Salesforce fields to the corresponding Rox fields. After onboarding, use CRM Mappings to add custom mappings.

General Settings

For each object you sync, the integration user needs Read access to the object and its required fields.

Object	Required fields
Account (Required)	ID, NAME, WEBSITE, OWNER_ID, SYSTEM_MODSTAMP, CREATED_DATE
Contact (Optional)	ID, NAME, EMAIL, ACCOUNT_ID, CREATED_DATE, SYSTEM_MODSTAMP
Lead (Optional)	ID, CREATED_DATE, SYSTEM_MODSTAMP
Opportunity (Optional)	ID, NAME, STAGE_NAME, OWNER_ID, ACCOUNT_ID, CREATED_DATE, SYSTEM_MODSTAMP
Opportunity Contact Role (Optional, recommended if syncing Opportunity)	ID, OPPORTUNITY_ID, CONTACT_ID, ROLE, IS_PRIMARY, CREATED_DATE, SYSTEM_MODSTAMP
Opportunity Stage (Optional, recommended if syncing Opportunity)	ID, API_NAME, SORT_ORDER, and IS_CLOSED or DEFAULT_PROBABILITY. Prefer syncing both, along with IS_WON.
Campaign (Optional)	ID, NAME, CREATED_DATE, SYSTEM_MODSTAMP
Campaign Member (Optional, recommended if syncing Campaign)	ID, CAMPAIGN_ID, CONTACT_ID and/or LEAD_ID, STATUS, HAS_RESPONDED, FIRST_RESPONDED_DATE, CREATED_DATE, SYSTEM_MODSTAMP

Additional fields, such as industry, revenue, contact phone numbers, and opportunity amounts, can be mapped according to your team's needs.

Restrict access before connecting

Skip this section if you are using the System Administrator profile.

Create or configure a custom permission set for the integration user. Grant Read access to the objects and fields Rox should sync, including the required fields above. Check Salesforce sharing rules so the intended records are visible to that user.

Grant write permissions only for the objects and fields you intend Rox to create or update. Read sync and writeback require different permissions; configuring read access alone does not enable writeback.

Use the permissions for the actual integration user. If you need activity writeback, use the full Salesforce license described above. Complete the additional activity permissions in Enable writeback.

Validate the setup by confirming that the integration user can query the intended objects and fields.

Step 1 Connect Salesforce and Fivetran

1. Sign in to Rox as an Organization Admin.

2. Go to Settings → Integrations.

3. Find Salesforce and select Connect, or Action Required if shown.

Open Settings and Integrations

1. Confirm your Salesforce edition and the integration user's permissions.

2. Select Continue, then sign in to Salesforce as the integration user.

Select Salesforce Connect

1. After returning to Rox, select Connect Fivetran.

2. In Fivetran, select Continue, Authorize, then Save and Test. Use the same Salesforce credentials and custom domain, if applicable.

Connect Fivetran

Authorize Fivetran

Save, Test, and Finalize Fivetran Connection

1. Continue to Select objects.

Fivetran ingests Salesforce data into the warehouse used by Rox.

For a sandbox connection, choose Log In with a Different Username, select Use Custom Domain, enter the Salesforce custom domain, and continue.

Step 2 Select objects

Select the Salesforce objects your team needs, such as Contact, Lead, and Opportunity. Account and User are required.

You can enable additional objects after onboarding in Settings.

Select objects to sync

Step 3 Configure field mappings

1. Select an object tab.

2. Review the default Salesforce-to-Rox mappings.

3. Select the appropriate Salesforce field for each Rox field.

4. Keep required mappings in place and adjust optional mappings as needed.

5. Continue to Account assignment.

Configure field mappings

After onboarding, use CRM Mappings to create or refine custom mappings.

Step 4 Configure account assignment

Account assignment determines which Salesforce Accounts each Rox user can access.

1. Review the assignment rule for each user.

2. On Owner fields, select the Salesforce Account-to-User fields used to assign Accounts. Most organizations use Account Owner; select a supported custom owner field if needed.

3. On Account filters, optionally configure an additional filter. A user can have multiple owner fields and one additional filter.

4. On Default rule, configure the rule for users without owner fields or filters.

5. Use Preview to check the resulting Account set, then save.

Users without a matching assignment rule do not see Accounts. Continue to Enable writeback, or go to Test sync if you do not need writeback.

Configure account assignment rules

After onboarding, update rules in Settings → Integrations → Salesforce → Account Assignment.

Step 5 Enable writeback

Writeback is optional. Rox writes only the fields and activities configured by an Organization Admin and permitted by the Salesforce integration user's access.

Install the managed package

Install the Rox managed package. Select Install for All Users, then Install.

The package creates:

• ID Mapping (RoxAI__ID_Mapping__c), which resolves Rox and Salesforce entities during bidirectional sync.

• Rox Integration User Access, a permission set that grants access to the ID Mapping object.

Install the Rox Managed Package

Grant package access to all users

Configure write permissions

If the integration user has a full Salesforce license and the System Administrator profile, Salesforce-side permission setup is complete. Continue with the Rox-side mappings and activity configuration after onboarding.

For a restricted integration user:

1. Assign Rox Integration User Access.

2. In your custom permission set, grant the object and field access needed for the records Rox should create or update.

3. Assign the custom permission set to the integration user.

For activity writeback, also configure:

• Access Activities, Edit Tasks, and Edit Events in System Permissions.

• The Task permissions needed by the integration, including the documented Create, Edit, and Delete Tasks permissions.

• Access to the Task and Event objects and the activity fields Rox uses.

Review access to these Task fields: Subject, Description, Status, ActivityDate, OwnerId, WhoId, WhatId, Type, TaskSubtype, Priority, CallType, and CallDisposition. Grant write access to fields Rox must populate where Salesforce allows it.

Wait for the next sync, which may take about 30 minutes, then confirm that the intended fields are write-enabled in CRM Mappings.

Assign Rox Integration User Access

Assign both permission sets

Enable Access Activities

Enable Task permissions

Grant Task field access

For integrations connected before May 31, 2025, re-authenticate after granting write permissions. See Re-authenticate Salesforce and Fivetran.

Step 6 Test sync

1. Run Test sync.

2. Review errors or warnings and return to the relevant onboarding step to correct them.

3. When the test succeeds, select Submit to finalize the connection.

Test sync

After onboarding, configure the writeback mappings and activity types your team needs.

Manage CRM Mappings

After the first sync, go to Settings → Integrations → Salesforce.

CRM Mappings includes Accounts, Contacts, Opportunities, Leads, and Activities. Configure settings and mappings for each object.

For Contacts and Leads:

Mapping section	Purpose
Read	Maps Salesforce fields into Rox during sync.
Write (Activity)	Configures fields used when writing activities and creating Salesforce Contacts or Leads referenced by a Rox activity.

Enable writeback for new entities only after completing the managed-package and permissions setup.

Configure Write Activity mappings

Add a custom mapping

1. Select + Add Mapping to create a custom Rox field for the entity type.

2. Set its name, compatible data type, access controls, and visibility.

3. Make the field Editable in Rox and Organization-Wide.

4. Under Inactive Fields, select the Salesforce custom field and the new Rox field.

5. Choose the applicable Read or Write sync rule.

The new field appears under Custom Rox Fields. Confirm that the selected Rox data type supports the Salesforce field before saving the mapping.

Add a custom field mapping

Formula fields

Changes to a calculated value may not update the Salesforce record's modification timestamp, so an incremental sync may not pick up the change.

If you need these values synced reliably, have your Salesforce administrator configure automation to copy the calculated value into a stored field and keep it current. Design the automation around the formula's dependencies, then map the stored field in Rox. For new Salesforce automation, use Flow Builder rather than Process Builder or Workflow Rules.

Configure activity writeback

After onboarding and permission setup, open the activity writeback configuration in Settings → Integrations → Salesforce.

Configure the activity types your team wants Rox to write to Salesforce:

• Email Writeback

• Phone Call Writeback

• LinkedIn Message Writeback

• LinkedIn Connection Writeback

Use Mark Rox-created Activities to write the word Rox to the selected Salesforce Task field.

Configure activity writeback

For restricted picklists or custom-field validation rules, use Additional Mappings to translate values to the values Salesforce accepts.

Configure additional mappings

Re-authenticate Salesforce and Fivetran

Re-authenticate if the integration requires action, its token has expired or been revoked, or updated permissions require a new authorization.

1. Go to Settings → Integrations and find Salesforce.

2. Select the settings icon, regardless of whether the integration shows Error, Action Required, or Ready.

3. On Authentication, select Re-authenticate and sign in as the integration user.

4. Return to Rox and refresh if needed.

5. Select Action Required, then Map Key Values to re-authenticate Fivetran.

6. Select Re-authorize connection, then Save and Test.

7. Return to Rox and refresh. Confirm the connection shows Connected.

OAuth approval error

If you see OAUTH_APPROVAL_ERROR_GENERIC, check whether Salesforce is blocking the Rox Connected App. In Salesforce, open Connected Apps OAuth Usage and confirm RoxAI is installed or approved alongside Fivetran, then retry.

OAuth approval error

Verify RoxAI in Connected Apps OAuth Usage

How the integration works

Component	Service	Location
Warehouse	Snowflake	United States
Ingestion	Fivetran	United States
Rox application frontend	Vercel	United States
Rox application backend	AWS	United States

Rox accesses the objects and fields permitted for the Salesforce integration user and configured for sync. Writeback is limited by both Salesforce permissions and the Organization Admin's configuration in Rox.

Synced data supports account research, insights, and opportunity management. Data retention and removal follow Rox's applicable data-lifecycle policies.