# Salesforce connections

> Connect a Salesforce org to an Arcus project so tests use its metadata, sign in without credentials, and report what each change affects.

A **Salesforce connection** links an Arcus project to one Salesforce org. Arcus reads the org's metadata, its objects, fields, picklist values, record types, list views, apps, and tabs, so you build Salesforce tests from the org itself instead of recording them.

With a connection, you get:

- **Steps from real metadata**: pick tabs, objects, fields, and picklist values from the org in the step editor.
- **Locators without recording**: Salesforce elements come with locators built from the org's own metadata.
- **Change reports**: every sync reports what changed in the org and which test cases the change affects.
- **Sign-in without credentials**: a test's first step signs in through the connection, so no password is stored in the test.

Without a connection, tests can still use recorded web elements and sign in through the browser, but you lose the picklist and required-field checks and change detection.

## Before you connect

An org admin creates a **connected app** in Salesforce once. Arcus signs in through it with Salesforce login (OAuth).

In Salesforce Setup, the admin:

1. Opens **App Manager** and creates a connected app.
2. Turns on OAuth settings and adds the callback URL `https://salesforce-callback.testsigma.com/authorize/`.
3. Selects the **api**, **refresh_token**, and **web** scopes.
4. Keeps **Require Proof Key for Code Exchange (PKCE)** on.

You need the connected app's **consumer key** (Salesforce also calls it the client ID) and **consumer secret** (the client secret).

Enter the same callback URL in Arcus when you connect the org.

## Connect an org

1. Open **Project Settings** and select **Salesforce**. If the project has no connection yet, click **Connect Salesforce**. Otherwise, click **Connect an org**.

   ![The Salesforce page in Project Settings, with a connection that needs re-auth and Connect an org outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_connections.webp)

   

2. In **Connection details**, enter a **Name** that's unique in the project.
3. Select the **Org type**: **Production**, **Sandbox**, or **Scratch**. Click **Continue**.

   ![Connection details, with the Name and Org type fields outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_connect_details.webp)
4. In **Credentials and connection**, enter the **Consumer key**, **Consumer secret**, and **Callback URL** from the connected app. The callback URL must start with `https://` and match one in the connected app. To see the connected app steps for your Salesforce admin, expand **Set up the connected app for Salesforce login (OAuth)**.

   ![Credentials and connection, with the setup steps expanded and the Consumer key, Consumer secret, and Callback URL fields outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_connect_credentials.webp)
5. Click **Log in with Salesforce**, and sign in on Salesforce's own page.

Arcus never sees your Salesforce password, and it stores the consumer secret encrypted. It shows **Connected to** your org, with its **Org ID**, the **Org type** Salesforce reports, and the **Instance URL**. Click **Next: choose what to sync**.

### Choose what to sync

Sync only what your tests need. Fewer objects make every sync faster and lighter on the org's daily API allowance.

1. Under **Start from**, choose:
   - **All objects**: every object in the org.
   - **Apps**: the objects on the tabs of the apps your team tests. Select one or more apps, for example **Sales** (Lightning). Each sync re-reads the tabs, so new ones are picked up.
   - **Page layouts**: the objects that have a page layout, the ones a person can open in Salesforce. All are ticked to start. Untick objects to sync only the ones you keep. While all stay ticked, objects that gain a page layout later sync too.
2. **(Optional)** If you chose **All objects**, under **Refine** > **Leave out**, exclude **Standard** or **Custom** objects, system objects such as **Change event**, **Share**, and **History**, or installed packages.
3. Check **What will sync**: how many objects will sync, and about how many API calls each sync uses.
4. Click **Next: schedule**. To sync everything instead, click **Skip: sync all objects**.

Objects your Salesforce elements already use always sync, whatever you choose.

### Set the schedule

1. Keep **Sync on a schedule** on to pick up new fields, picklist values, and record types, and report which test cases they affect.
2. Under **How often**, select **Hourly**, **Daily**, or **Weekly**, and check the **Time zone**.
3. Click **Save and sync**.

Each scheduled sync starts at a spread time in the period rather than on the hour. You can change the schedule later on the connection's page.

The first sync starts straight away. You can close the page while it runs. When it finishes, the org's fields are available in the step editor. See [Salesforce test steps](https://testsigma.com/docs/arcus/v2/apps/salesforce/steps/).

## Manage a connection

**Project Settings** > **Salesforce** lists the project's connections with their **Environment**, **Health**, such as **Active**, and **Latest sync**. Click the ellipsis icon (⋯) on a row for **Open connection**, **Re-authorise**, **Verify**, or **Delete**. When the connection is **Active**, the menu also has **Sync now**.

![The connection row menu, with Open connection, Re-authorise, Verify, and Delete.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_connection_menu.webp)

A connection's page has four tabs.

### Overview

- **What syncs**: the scope, for example "The objects of 1 app". Click **Browse** to see the objects, or **Edit** to change the scope.
- **Schedule**: how often it syncs and when the next sync runs. Click **Edit** to change it.
- **Sync history**: how many syncs have run and whether they succeeded.
- **Connection**: the org, its edition, the Org ID, and how Arcus signs in. Click **Verify** to check the connection, or **Edit** to change it. **Technical details** shows the instance and login URLs, the consumer key, and which secrets are stored.

To sync now instead of waiting for the schedule, click **Sync now** in the header. The result shows how many objects were read, how many API calls the sync used, and how many changes it found.

When Salesforce stops accepting the connection, the page reads "Salesforce stopped accepting this connection", **Sync now** is unavailable, and the schedule shows **Paused**. Syncs and runs that use the connection fail until someone signs in again. Click **Re-authorise** and sign in to Salesforce. The step editor's pickers keep the metadata from the last sync that succeeded.

![The Overview tab of a connection that needs re-auth, with the Re-authorise banner and the unavailable Sync now outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_connection_overview.webp)

### Metadata

The **Metadata** tab lists what was synced: **Objects**, **Fields**, **Record types**, **List views**, **Validation rules**, **Apps**, **Tabs**, and **Flows**, each with a count. Search, or filter by **Category**. Click an object to see its key prefix, what it supports, its fields with their type and whether each is required, and its list views.

To sync more or fewer objects, click **Change scope**.

![The Metadata tab, with the metadata counts and Change scope outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_metadata.webp)

### Changes

The **Changes** tab shows what each sync found. Select a sync to see:

- **CHANGES** and **OBJECTS CHANGED**: how many changes the sync found, and on how many objects.
- **BREAKING CHANGES** and **TEST CASES AFFECTED**: changes that can break existing tests, and the tests they affect.

Each change says what changed and on which object and field, with the API name and **View in metadata**.

A removed object, field, record type, list view, or picklist value is a breaking change. Below the counts:

- **Test cases affected** lists the test cases that use what changed, with links. They break on their next run.
- **Breaking changes** lists the breaking changes, such as a picklist value that was removed.
- **Other changes** folds away the changes that break nothing. Click it to expand.

![The Changes tab for a manual sync, with the counts outlined and four picklist changes under Other changes.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_changes.webp)

One change in Salesforce can appear several times. Lead Source's values are shared by Account, Contact, Lead, and Opportunity, so adding one value shows four changes.

### Sync history

The **Sync history** tab lists every sync with when it started and how (for example **Manual**), its result, how many objects it described, left unchanged, or failed on, its API calls, how long it took, and its changes. Click a sync's changes, such as **4 changes**, to open them on the **Changes** tab.

![The Sync history tab, with a failed scheduled sync and a manual sync with 4 changes outlined.](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/application_types/salesforce_sync_history.webp)

## Limitations

- The connection described on this page is a metadata connection. Runs sign in to the org through the connection picked under **Salesforce connection** in the run configuration, as that connection's user. See [Run configurations](https://testsigma.com/docs/arcus/v2/run-tests/run-configurations/#salesforce). The setup FAQ in Arcus also mentions a runtime connection, an identity kept only for runs, but this build has no option to add one.
- Each connection is to one org. To test several orgs, add a connection for each.

## FAQs

### What Arcus stores about your Salesforce sign-in

Arcus never sees your password: you sign in on Salesforce's own page. Arcus stores the connected app's consumer secret, encrypted, and a refresh token, and shows neither again.

### The org type changed after connecting

Arcus shows the edition Salesforce reports, for example Developer Edition, alongside the type you chose.

### New fields are missing from the step editor

Click **Sync now** on the connection. New fields and picklist values appear in the step editor's pickers after the sync.
