> For the complete documentation index, see [llms.txt](https://docs.rox.com/development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rox.com/development/product/organization-level-configurations/configuring-salesforce-integration-+-writeback.md).

# Configuring Salesforce Integration + Writeback

Connect Salesforce to Rox to keep CRM data in sync and, optionally, write selected field updates and activities back to Salesforce.

Rox uses a pull model: Salesforce data is periodically synced into a managed warehouse. You control which objects and fields Rox uses, and an Organization Admin controls which fields and activities Rox writes back.

### How to use this guide

Follow the guide in this order:

1. **Prepare Salesforce before onboarding** — create the integration user and, if needed, its restricted permission set.
2. **Complete the Salesforce onboarding wizard** — connect apps, select objects, configure fields, set account assignment, optionally enable writeback, and test the sync.
3. **Manage the integration after onboarding** — return to Settings to refine CRM mappings, activity writeback, account-assignment rules, and other ongoing configuration.

Some settings are shown during onboarding to establish an initial configuration, but can be changed later in **Settings → Integrations → Salesforce**. The **Test sync** step is onboarding-only.

### Before you begin

You need:

* A **Rox Organization Admin** to complete setup in Rox.
* A Salesforce administrator who can create and edit users, permission sets, and licenses.
* A Salesforce user to connect to Rox. We recommend a dedicated integration user so Rox activity is easy to audit.
* API access enabled for that Salesforce user.

#### Recommended Salesforce user

For the simplest setup, use a dedicated Salesforce user with a full **Salesforce** license and the **System Administrator** profile. This gives Rox access to all required objects and fields and supports activity writeback.

The API-only **Salesforce Integration** license can be used for read sync or core entity writeback, but it does **not** support activity writeback (Tasks, Events, logged emails, calls, meetings, or LinkedIn activity).

If your organization requires least-privilege access, use the restricted-access setup in Restrict Rox's access before connecting.

### Before onboarding: Create or confirm the integration user

In Salesforce, go to **Setup → Administration → Users → Users** and create a dedicated user, or confirm the user you will connect with has the required access.

1. Set **User License** to **Salesforce** if you need Activities writeback.
2. Set **Profile** to **System Administrator** for the recommended setup.
3. Add the user's email, username, and password.
4. Confirm **API Enabled** is selected.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252Fk57ChZtiIWhWbWl3Ks5B%252Fimage.png%3Falt%3Dmedia%26token%3Da8c449cf-5012-4398-8ca1-e28aa7d2d1e7&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=515f4d2e&#x26;sv=2" alt="Create Salesforce integration user"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FBXW8ok4bY08DtAyDKiUC%252Fimage.png%3Falt%3Dmedia%26token%3Da64c69ab-81af-4918-8618-c651c96ac5b5&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=6d3c4545&#x26;sv=2" alt="Confirm Salesforce user details"></div>

### Onboarding Step 1: Connect Salesforce and Fivetran

1. Sign in to [run.rox.com](https://run.rox.com/) as an Organization Admin.
2. Go to **Settings → Integrations**.
3. Find **Salesforce** and select **Connect**. If the card says **Action Required**, select it instead.

   <div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FJBo2JZVaz2vAAdUzNsbC%252Fimage.png%3Falt%3Dmedia%26token%3Dbeccea7a-3227-446d-b747-3cef1eea5e33&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=452d7f8&#x26;sv=2" alt="Open Settings and Integrations"></div>
4. Confirm your Salesforce edition and that the user creating the integration has the required permissions.
5. Select **Continue**, then sign in to Salesforce as the integration user.

   <div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FehqsY9KWwn5MyeTVYAa4%252Fimage.png%3Falt%3Dmedia%26token%3D6aeaaf90-d83e-4877-8efc-85d6563e56ab&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=46e441dd&#x26;sv=2" alt="Select Salesforce Connect"></div>
6. After returning to Rox, select **Connect Fivetran**. Fivetran is the secure service Rox uses to ingest Salesforce data into the warehouse and build the knowledge graph.
7. In Fivetran, select **Continue**, **Authorize**, then **Save and Test**. Use the same Salesforce credentials and custom domain, if applicable.

   <div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FwO3dAmuebMxXSWuaYrnP%252Fimage.png%3Falt%3Dmedia%26token%3D2caa42e3-e138-46c4-b665-42f7e70581a5&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=57598555&#x26;sv=2" alt="Connect Fivetran"></div>

   <div data-with-frame="true"><figure><img src="/files/iU2hNR7ftfc8Xfyk9pDm" alt=""><figcaption><p>Authorize Fivetran</p></figcaption></figure></div>

   <div data-with-frame="true"><figure><img src="/files/QHYjY0zbDplBsfXyC3iz" alt=""><figcaption><p>Save, Test, and Finalize Fivetran Connection</p></figcaption></figure></div>
8. Continue to **Select objects** in the onboarding wizard.

> **Sandbox connection:** choose **Log In with a Different Username**, then select **Use Custom Domain**, enter the Salesforce custom domain, and continue.

### Onboarding Step 2: Select objects

Select the Salesforce objects Rox should sync. **Account** and **User** are required. Enable the additional objects your team needs, such as Contact, Lead, Opportunity, or Task.

> You cannot unsync an object once it has been synced. You can enable additional objects later in Settings.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FiGVeeDBk23pLyytQ3OOa%252Fimage.png%3Falt%3Dmedia%26token%3D56317711-7767-4956-849d-2c689984e042&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=eb03a009&#x26;sv=2" alt="Select objects to sync"></div>

### Onboarding Step 3: Configure field mappings

Configure field mappings determines how Rox reads the selected Salesforce objects and fields during sync.

1. Select an object tab, such as **Account**, **Contact**, **Lead**, **Task**, or **User**.
2. Review the default Salesforce-to-Rox mappings and select the appropriate Salesforce field for each Rox field.
3. Keep all required mappings in place. You can adjust optional mappings as needed.
4. Continue to **Account assignment**. You can create or refine custom field mappings after onboarding in CRM Mappings.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FTkp8UhrwS8VjjXiftBRk%252Fimage.png%3Falt%3Dmedia%26token%3D2e468558-f403-4778-98bc-5c190639e4ee&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=866f7568&#x26;sv=2" alt="Configure field mappings"></div>

### Onboarding Step 4: Account assignment

Account assignment determines which Salesforce Accounts each Rox user can access. Complete this stage after **Configure fields** and before the optional writeback setup.

1. Review the assignment rule for each Rox user. Users with no matching rule do not see any Accounts.
2. On the **Owner fields** tab, select the Salesforce Account-to-User fields that should assign Accounts to a user. Most organizations use **Account Owner**; select a supported custom owner field when your CRM uses one.
3. On the **Account filters** tab, optionally configure an additional filter. A user can have any number of owner fields, but only one additional filter.
4. On the **Default rule** tab, configure the rule applied to users who have no owner fields or filters.
5. Use **Preview** to check the resulting Account set, then save the stage and continue to **Enable writeback** or, if you are not enabling writeback, **Test sync**.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252Fp929F98LYmqNmzAzBNlS%252FGemini_Generated_Image_33pda133pda133pd.png%3Falt%3Dmedia%26token%3D31957fe3-0906-418c-98f0-cd68d4f36e9a&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=f36b0df1&#x26;sv=2" alt="Configure account assignment rules"></div>

After onboarding, return to **Settings → Integrations → Salesforce → Account Assignment** to update assignment rules and filters.

### Onboarding Step 5: Enable writeback (optional)

Writeback lets Rox update only the Salesforce fields and activities an Organization Admin explicitly configures.

#### Install the Rox managed package

1. Install the [Rox managed package](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tUr000000Sg17IAC).
2. Select **Install for All Users**, then select **Install**.

The package creates:

* The **`RoxAI__ID_Mapping__c`** custom object (label: **ID Mapping**) used to resolve Rox and Salesforce entities during bi-directional sync.
* The **Rox Integration User Access** permission set, which gives access to that custom object.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FnpfEWo9Oup0NfsIT5AAZ%252Fimage.png%3Falt%3Dmedia%26token%3Dbbb6c946-2d5c-4484-b77f-f9bc11eb499b&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=28a0b54d&#x26;sv=2" alt="Install the Rox managed package"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FvTaoinyrJkCDqDDOtG8v%252Fimage.png%3Falt%3Dmedia%26token%3D121b5417-803d-48d3-a7da-25f6a672e6f5&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=8f986831&#x26;sv=2" alt="Grant package access to all users"></div>

#### Create the activity tracking field

To write activities back to Salesforce, create a **Text** field with a 100-character limit named **`RoxActivityId`**.

Create it on the parent **Activity** object—not directly on Task. Rox writes to Task, but fields on Activity flow down to Task.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FE9KefCIE3VTF9T0pn4Zo%252Fimage.png%3Falt%3Dmedia%26token%3D8a432fd0-5041-45d0-aa4c-11597a80b6c7&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=ab8905f7&#x26;sv=2" alt="Create RoxActivityId on Activity"></div>

#### Permissions for restricted setups only

If the integration user has the System Administrator profile with a full Salesforce license, writeback setup is complete. Otherwise:

1. Assign **Rox Integration User Access** to the integration user.
2. In your separately created custom permission set, grant **Edit** access to every object and field Rox should write back to.
3. Assign both permission sets to the integration user.
4. Enable **Access Activities** in the custom permission set's **System Permissions**.
5. In **Object Settings → Tasks**, enable **Create, Edit, and Delete Tasks**.
6. Grant **Edit** access to `RoxActivityId` and every Task field Rox should write.
7. Wait for the next sync (up to about 30 minutes), then confirm expected objects and fields are write-enabled in Rox CRM Mappings.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252Fjk7mhOGzyvR5C1lzqkmI%252Fimage.png%3Falt%3Dmedia%26token%3D7ada4b92-a087-4822-95c0-7cca8f95f3ea&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=274bf8ce&#x26;sv=2" alt="Assign Rox Integration User Access"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FdrW9YaOjCOsxFoBhsLoj%252Fimage.png%3Falt%3Dmedia%26token%3Da5853d26-c29a-42d9-82ef-6457656aa0fa&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=9bcbc10d&#x26;sv=2" alt="Assign both permission sets"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FLV1Jhp2nsB3J56yF6n9F%252Fimage.png%3Falt%3Dmedia%26token%3D54711fbf-917b-4a86-88f2-f32ac6e47099&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=31aca8&#x26;sv=2" alt="Enable Access Activities"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252Fx09deePh76ym2Jp3CI7q%252Fimage.png%3Falt%3Dmedia%26token%3D2c96e5a6-1bf3-42da-a413-d8018a0f4929&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=c5c02dcb&#x26;sv=2" alt="Enable Task permissions"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FErZ1ExyL0zMN1ggNSR2o%252Fimage.png%3Falt%3Dmedia%26token%3Df893cbf4-68dd-4552-82c5-9d871d743345&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=5c8ec5e5&#x26;sv=2" alt="Grant Task field access"></div>

> **Existing integrations:** If the Salesforce integration was connected before **2025-05-31**, re-authenticate it after granting write permissions so Rox receives a token with the new scopes. See Re-authenticate Salesforce and Fivetran.

#### After onboarding: Configure activity writeback

After you complete the package and permission setup above and finish onboarding, use the **Activities** tab to configure how Rox writes calls, emails, meetings, and LinkedIn touches back to Salesforce as Tasks or Events.

You can independently enable:

* **Email Writeback**
* **Phone Call Writeback**
* **LinkedIn Message Writeback**
* **LinkedIn Connection Writeback**
* **Mark Rox-created Activities**, which writes the word `Rox` to the selected Salesforce Task field

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FeB83zCSl47uJ13Qf69MS%252Fimage.png%3Falt%3Dmedia%26token%3D816e6c2e-28e5-4a2c-986e-fd041111dcb5&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=5082e04b&#x26;sv=2" alt="Configure activity writeback"></div>

#### After onboarding: Activity association and additional mappings

Choose which Salesforce entity receives each activity association when Rox writes activity data back.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252Fpu0vwUjMRg1V2VydMgMC%252Fimage.png%3Falt%3Dmedia%26token%3Dbeab9927-02c3-4124-9fd0-19de104b9385&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=7a09051e&#x26;sv=2" alt="Configure activity association"></div>

For restricted picklists or custom-field validation rules, use **Additional Mappings** to translate one field value to another.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FR1LRDR9APURoMMjjwIUM%252Fimage.png%3Falt%3Dmedia%26token%3D47558f3b-6bdc-483a-8b4a-d621fad88714&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=38f2c394&#x26;sv=2" alt="Configure additional mappings"></div>

#### After onboarding: Lead creation and resolution

Rox can resolve an existing Salesforce Lead or create a new Lead when processing a contact:

* If Rox finds a Lead with the contact's email address, it associates the activity with that Lead.
* If no matching Lead exists, Rox creates a new Lead.

Configure this in **Settings → CRM → Activities**. Lead creation and resolution currently support **email writeback only**.

### Onboarding Step 6: Test sync

Test sync is the final basic onboarding step. It lets you verify the selected objects and configured mappings before finishing setup.

1. Run the sync test.
2. Review any errors or warnings and return to the relevant onboarding step to correct them.
3. When the test succeeds, select **Submit** to finalize the Salesforce connection.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FhHVxodWqlIzs5OXeqoAd%252Fimage.png%3Falt%3Dmedia%26token%3Daf8a6233-ac08-4854-8abe-8eb50615f734&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=9c1b86d9&#x26;sv=2" alt="Test sync"></div>

### Before onboarding: Restrict Rox's access (optional)

Skip this section when using a System Administrator profile. If you must restrict access, grant the integration user the required permissions before connecting Rox.

1. On the integration user's detail page, assign the **Salesforce API Integration** Permission Set License.
2. In Salesforce, clone the **Rox Integration** permission set or create a Salesforce API integration permission set with **License** set to **None**.
3. Assign the permission set to the Salesforce user connected to Rox.

#### Give Rox access to Salesforce objects and fields

In the permission set, open **Object Settings**. For each object below, grant Rox **Read, Create, and Edit** access and access to the listed fields. You may need to update Salesforce sharing rules so the permitted records are visible to the integration user.

| Object                | Required fields                                                       |
| --------------------- | --------------------------------------------------------------------- |
| Account               | Company name, website, industry, revenue, employee count, and address |
| Contact               | Name, email, phone, title, and account                                |
| Opportunity           | Name, amount, stage, close date, next step, and account               |
| Lead                  | Name, email, phone, and lead source                                   |
| Opportunity Line Item | Grant object access                                                   |
| Custom objects        | Grant access to every custom object you want Rox to use               |

Also grant access to **Task** and **Event**.

#### Enable Task and Event permissions

In the permission set, go to **Permission Set → System Permissions** and enable:

* **Access Activities**
* **Edit Tasks**
* **Edit Events**

#### Make required Task fields visible

Go to **Object Manager → Task → Fields & Relationships**. For every field below, update **Field-Level Security** for **Minimum Access - API Only Integrations** and set it to **Visible**:

* Subject
* Description
* Status
* ActivityDate
* OwnerId
* WhoId
* WhatId
* Type
* TaskSubtype
* Priority
* CallType
* CallDisposition

To validate a restricted setup, sign in to [Salesforce Workbench](https://workbench.developerforce.com/login.php) as the integration user and confirm that required objects are visible and fields are queryable through SOQL.

### After onboarding: Manage CRM Mappings

After the first sync completes, go to **Settings → Integrations → Salesforce**. CRM Mappings controls how each object syncs.

#### Object tabs and general settings

CRM Mappings has tabs for **Accounts**, **Contacts**, **Opportunities** (coming soon), **Leads**, and **Activities**. Settings, field mappings, and writeback are configured per object—not globally.

For each object, you can:

* Turn that object's sync on or off.
* Enable writeback for new entities, after completing Onboarding Step 5.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252Fe4Z57wmnerJQdOOfSkAF%252Fimage.png%3Falt%3Dmedia%26token%3D49de6b69-cb51-41f8-bc01-9289296691ae&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=70f3a0fd&#x26;sv=2" alt="General object settings"></div>

#### Field-level mappings

For Contacts and Leads, mappings are organized into three sections:

1. **Read** — maps Salesforce fields into Rox during sync.
2. **Write** — maps Rox fields back to Salesforce and updates existing Salesforce Contacts or Leads. This does not create a new Salesforce record.
3. **Write (Activity)** — exposes additional writeback fields and can create new Salesforce Contacts or Leads that are referenced by a Rox activity.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FckDe01UcmKnXdBjLt5IX%252Fimage.png%3Falt%3Dmedia%26token%3Db0bd58f4-4dc0-4f32-a41e-8f5002069d3e&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=7776be67&#x26;sv=2" alt="Configure read and write mappings"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FYQGqUShVwiEiOJwFT0ZS%252Fimage.png%3Falt%3Dmedia%26token%3D288bbb9f-ded5-4bd7-98a1-de0b16e1f800&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=3757bdbf&#x26;sv=2" alt="Configure Write Activity mappings"></div>

#### Add a custom mapping

Use **+ Add Mapping** to create a custom Rox field for an entity type. Set its name, data type, access controls, and visibility; it then appears under **Custom Rox Fields** for mapping.

To map a Salesforce custom field into Rox:

1. Create a Rox field with the corresponding Salesforce data type.
2. Make the Rox field **Editable in Rox** and **Organization-Wide**.
3. Under **Inactive Fields**, select the Salesforce custom field and the new Rox field.
4. Choose the applicable **Read** or **Write** sync rule.

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FdgRioLPDKWdvGdmoKp9q%252Fimage.png%3Falt%3Dmedia%26token%3D3b65b946-68c8-4b7e-bf1b-5afbedd0ca40&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=d039c8dc&#x26;sv=2" alt="Add a custom field mapping"></div>

### Formula fields

Calculated/formula fields from Salesforce have some nuances with the way we ingest updates to those fields from Salesforce as the last modified date is not updated when those field types are updated on an opportunity.

If you'd like to pull in Formula Fields from your Salesforce instance to sync into Rox and be eligible for writeback from Rox back to your Salesforce, we recommend using "Process Builder" or creating a Workflow in Salesforce to automatically populate a new field on the object to match the current calculated/formula field whenever it’s updated. This will allow for us to pick the updated values when they are made since this will update the last modified date of that column.

### Re-authenticate Salesforce and Fivetran

Re-authenticate when the integration shows an error, requires action, has an expired/revoked token, or needs newly granted write permissions.

1. Go to **Settings → Integrations** and find Salesforce.
2. Select the **settings** icon next to the integration, regardless of whether it says **Error**, **Action Required**, or **Ready**.
3. On the **Authentication** tab, select **Re-authenticate** and complete Salesforce login as the integration user.
4. When Rox redirects you back, refresh if needed. The integration should show **Action Required**.
5. Select **Action Required**, then select **Map Key Values** to re-authenticate Fivetran.
6. Select **Re-authorize connection**, then **Save and Test**.
7. Return to Rox and refresh. The connection should show **Connected**.

#### OAuth approval error

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

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FBtz950QX7oTK8Mud1cUD%252Fimage.png%3Falt%3Dmedia%26token%3Dda75d80d-5b6e-4dd0-8ea6-371bd286a954&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=d0385f39&#x26;sv=2" alt="OAuth approval error"></div>

<div data-with-frame="true"><img src="https://docs.rox.com/development/~gitbook/image?url=https%3A%2F%2F2986926806-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FUBzWA2LkfjbdaffIaGlN%252Fuploads%252FkOPWVH3KHi8mjJ5qWIin%252Fimage.png%3Falt%3Dmedia%26token%3D40b8387b-ffba-427d-8074-19941395f3b1&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=68eacec1&#x26;sv=2" alt="Verify RoxAI in Connected Apps OAuth Usage"></div>

### How the integration works

| Component                  | Vendor    | Region        |
| -------------------------- | --------- | ------------- |
| Warehouse                  | Snowflake | United States |
| Ingestion                  | Fivetran  | United States |
| Rox application (frontend) | Vercel    | United States |
| Rox application (backend)  | AWS       | United States |

| Category         | Description                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| Data accessed    | The objects and fields the Salesforce integration user is permitted to sync. Fields can be selectively removed. |
| Data written     | Fields the integration user may access and an Organization Admin has configured for writeback in Rox.           |
| Purpose          | Supports account research, insights, and opportunity management in Rox.                                         |
| PII minimization | Rox uses only required fields that the integration user is permitted to access.                                 |
| Retention        | Synced data is retained for operational and product purposes and deleted upon user or tenant disconnection.     |
| Deletion         | On disconnection or a data-removal request, synced data can be purged under Rox data-lifecycle policies.        |

### You're done

Salesforce and Rox are connected. Use CRM Mappings to refine sync and writeback as your needs evolve. If newly granted permissions do not appear in Rox after a sync, contact Rox support for permission reconciliation.