# Salesforce

Start building your salesforce integrations within Tray with Tray's Salesforce connector

## Overview

Salesforce provides customer relationship management service software, and has a complementary suite of enterprise applications as well. These are focused on customer service, marketing automation, analytics, and application development. It is the market leader in CRM solutions.

## API Information

The latest Salesforce connector **v8.8** exposes the **v65.0** of Salesforce's REST API. More information can be found on their primary [API documentation (v1)](https://developer.salesforce.com/docs/atlas.en-us.220.0.api_rest.meta/api_rest/intro_what_is_rest_api.htm) site.

## Authentication

> **Info:** **PLEASE NOTE**: SFDC Editions with API Access include: Enterprise, Unlimited,
> Developer, and Performance. Any licenses that do not have this edition cannot
> communicate to external services via API.

### Authentication Options

Salesforce provides two methods for OAuth authentication with external applications:

1. **External Client Apps (Recommended)** - Salesforce's newer, streamlined OAuth authentication method introduced in Winter '24. This is the recommended approach for creating custom OAuth apps.
2. **Connected Apps (Legacy)** - The traditional method that continues to work for existing integrations.

> **Info:** **Tray's Default OAuth App**: When you create a Salesforce authentication without using "Use own OAuth app", you're using Tray's production OAuth app, which is a Connected App. This works seamlessly for most use cases.**Creating Your Own OAuth App**: If you need to create your own custom OAuth app, Salesforce recommends using External Client Apps for new implementations.

### Setting up External Client Apps (Recommended)

External Client Apps provide a modern, simplified approach to OAuth authentication in Salesforce. This method is recommended by Salesforce for all new integrations as it offers streamlined configuration and improved security controls.

When creating a Salesforce authentication in Tray.ai, you'll see the option to **"Use own OAuth app"**. The following steps guide you through creating and configuring your External Client App in Salesforce to generate the Client ID and Client Secret needed for this option.

### Prerequisites

Before creating an External Client App, ensure you have:

* Administrative access to your Salesforce organization
* API access enabled for your Salesforce edition (Enterprise, Unlimited, Developer, or Performance)
* Understanding of which OAuth flows and scopes your integration requires

### Step 1: Enable OAuth Authorization Flows

First, you need to enable the OAuth flows that your External Client App will use.

1. In Salesforce Setup, use the Quick Find box to search for **"oauth"**
2. Select **OAuth and OpenID Connect Settings**

3) On the OAuth and OpenID Connect Settings page, ensure **Allow Authorization Code and Credentials Flow** is enabled

> **Info:** **Authorization Code and Credentials Flow** is required for the Tray.ai connector to authenticate users via OAuth 2.0.

### Step 2: Navigate to External Client App Manager

1. In the Setup Quick Find box, search for **"external"**
2. Under **Apps**, select **External Client App Manager**

3) Click **New External Client App** in the top right corner

### Step 3: Configure Basic Information

On the Settings tab, configure your External Client App's basic information:

* **External Client App Name**: Choose a descriptive name (e.g., "Tray.ai Integration")
* **API Name**: Auto-generated based on the app name
* **Contact Email**: Your admin or support team email
* **Distribution State**: Select **Local** (for use within your organization only)
* **Icon URL** and **Logo Image URL**: Optional branding elements
* **Description**: Optional description of the integration

> **Info:** Keep the **Distribution State** as **Local** unless you plan to distribute this app to other Salesforce organizations.

### Step 4: Enable OAuth Settings

Expand the **API (Enable OAuth Settings)** section:

1. Check **Enable OAuth**
2. The OAuth Settings section will expand with additional configuration options

### Step 5: Configure OAuth Settings

In the expanded OAuth Settings section:

1. Set the **Callback URL** to: `https://auth.tray.io/oauth2/token`

2) Select the **OAuth Scopes** your integration needs:

**Common scope configurations:**

* **Full access (full)** + **Perform requests at any time (refresh\_token, offline\_access)** - Provides comprehensive access
* **API access (api)** + **Perform requests at any time (refresh\_token, offline\_access)** - Standard integration access
* Or select specific scopes based on your integration needs

> **Info:** **Recommended**: Always include **Perform requests at any time (refresh\_token, offline\_access)** scope. This allows Tray.ai to maintain long-term access to your Salesforce org without requiring users to re-authenticate frequently.

> **Warning:** **CRITICAL - Scope Configuration Rules**:- **If you select "Full access (full)" in Salesforce**: Do NOT select any scopes when creating authentication in Tray.ai. Leave all scopes unchecked in Tray - the authentication will use the scopes configured in your Salesforce External Client App. Selecting scopes in Tray when "Full access (full)" is configured will cause authentication to fail.
>
> - **If you select specific scopes (without "Full access")**: You can select scopes in Tray.ai, but they MUST exactly match the scopes you configured here in Salesforce. Mismatched scopes will cause authentication failure.
>
> - **Best practice**: Configure all necessary scopes in your Salesforce External Client App, then leave scopes unchecked in Tray.ai. This ensures Tray uses exactly what's configured in Salesforce and avoids scope mismatch errors.

3. Scroll down to the **Flow Enablement** section:

**Flow Enablement**:

* Ensure **Enable Authorization Code and Credentials Flow** is checked
* This flow is required for web-based OAuth authentication

**Security**:

* **Require secret for Web Server Flow**: Checked (recommended)
* **Require secret for Refresh Token Flow**: Checked (recommended)
* **Enable Refresh Token Rotation**: Checked (recommended for enhanced security)

These security settings ensure your External Client App follows OAuth 2.0 best practices.

### Step 6: Save the External Client App

Once you've configured all settings in the previous steps:

1. Review your configuration (Basic Information, OAuth Settings, Flow Enablement)
2. Click **Save** or **Create** to create your External Client App
3. Salesforce will save your app and redirect you to the app's management page

### Step 7: Retrieve Consumer Key and Secret

After creating your External Client App, you'll be redirected to the Policies tab:

To retrieve your OAuth credentials:

1. Click on the **Settings** tab (next to Policies tab)
2. Navigate to the **OAuth Settings** section
3. Click **Consumer Key and Secret** link

4) Copy both the **Consumer Key** (Client ID) and **Consumer Secret** (Client Secret)

You'll use these credentials when creating authentication in Tray.ai:

* **Consumer Key** → **Client ID** in Tray
* **Consumer Secret** → **Client Secret** in Tray

### Step 8: Create Authentication in Tray.ai

Now that your External Client App is configured in Salesforce, create the authentication in Tray.ai:

1. In your Tray.ai workflow, add a Salesforce connector step
2. Click **New Authentication**
3. Name your authentication (e.g., "Salesforce Production - External Client App")
4. Click **Use own OAuth app**
5. Enter your credentials:
   * **App Key**: Paste the Consumer Key from Salesforce
   * **App Secret**: Paste the Consumer Secret from Salesforce
6. **For Scopes** - Choose ONE of these approaches:
   * **Recommended**: Leave all scopes **unchecked**. Tray will automatically use the scopes configured in your Salesforce External Client App
   * **Alternative**: If you did NOT configure "Full access (full)" in Salesforce, you can select specific scopes here, but they must EXACTLY match what you configured in Salesforce
7. Click **Create Authentication**
8. You'll be redirected to Salesforce to authorize the connection

> **Warning:** **IMPORTANT**: If you configured "Full access (full)" in your Salesforce External Client App, you MUST leave all scopes unchecked in Tray.ai. Selecting any scopes when "Full access" is configured will cause authentication to fail.

> **Info:** **Best Practice**: Always leave scopes unchecked in Tray.ai when using External Client Apps. This ensures the authentication uses exactly what's configured in Salesforce and eliminates scope mismatch errors.

Your External Client App authentication is now complete and ready to use in your Tray.ai workflows!

### Setting up Connected Apps (Legacy Method)

When using the Salesforce connector for the first time you will need to create a new authentication:
![add-auth](https://tray.ai/documentation/images/connectors/service/salesforce/c56d6bf8-88d19335_a;sldfkj.png)
You will then have to select the necesary **Scopes** for your authentication. This will configure the access level your Tray workflow will have to your Salesforce account:

> **Warning:** Note that for standard use, you will **always need to tick the API scope**

![sf-api-always-tick](https://tray.ai/documentation/images/connectors/service/salesforce/5LbjB97ErEQ7dD2KfEwruD_alksdjfh.png)
You will then be prompted to enter the **credentials of the Salesforce user** you will be authenticating with.
This user must be set up with the **correct permissions in the Salesforce Admin UI** to ensure that they will be able to **access all the available connector operations**.

## **Granting Access to Tray in Salesforce**

Encountering issues while authenticating with Salesforce, especially during the integration of a third-party app like Tray, may result from Salesforce blocking the application.
Salesforce's default settings or specific organizational security policies can automatically block third-party apps that administrators have not pre-authorized. This is a standard precaution to prevent unauthorized access.
**Steps to Unblock an App in Salesforce:**

1. Log in to your Salesforce account.
2. Navigate to Platform Tools from the Home menu.
3. Under Platform Tools, select '**Apps'**, then choose '**Connected Apps'**.
4. Proceed to '**Connected Apps OAuth Usage'**.
5. In the list of apps, locate '**Tray'**.
6. In the Actions column, check the status of Tray.
7. If Tray is blocked, an option to '**Unblock**' will appear.
8. Click '**Unblock**' to grant Tray access.
   ![auth-unblock-an-app-in-salesforce](https://tray.ai/documentation/images/connectors/service/salesforce/1fNAhl8AKp58C8M9QCg6X5_auth-unblock-an-app-in-salesforce.png)
   This action removes the restriction, allowing Tray to interact with Salesforce as intended.
   Following these steps should effectively resolve any access issues related to app blockages in Salesforce.

## Correct setup of User Permissions

### Managing Access

The Salesforce connector gives you full access to all of your Salesforce account data such as your leads, contacts, custom objects/fields, workflow rules, outbound messages and more.
The way you handle who has access to this data is through the use of Salesforce **Users**, **Profiles** and **Permission sets**.
Your User will have access depending on their associated Profile permissions or Permission sets - in a read, write, create capacity; depending on whats required.
Be sure sure to note the following access rules before you confirm who has what level of access to which data sets. More information on Profiles and Permission sets can be found below.

* Every **User** **must be assigned a** **Profile**.
* There can **only be one Profile per User**.
* **The User you are creating an authentication for MUST have access to all the object types you want them to manipulate**.

> **Warning:** Currently the Salesforce connector can **only be used on the Enterprise
> Edition of Salesforce, and higher**. You may use the Salesforce connector on
> Professional Edition, but **ONLY** if you've requested API access from your
> Salesforce account manager. However, you will not be able to use instant
> WebHooks on the Professional Edition.

## Profiles

In Salesforce you can allocate a user to a pre-set **Profile** or you can create your own **Custom Profile**.
The available Profiles for a User will depend on the type of **License** that User has. More information on this can be found below.

> **Info:** Note that the **Contract Manager Profile** comes as standard and **is suited
> to the access level required by both the Salesforce Trigger and Connector**.

### Profile vs Custom Profile

Pre-set\*\* Profiles\*\* are included as part of your Salesforce account.
However please note that the kinds of pre-set Profiles that are available to you will depend on the type of **License** that a User has.
For example a **Salesforce Platform-licensed User** can only have a **Standard Platform User** **Profile**.
While a **Salesforce-licensed User** can have multiple Profiles. Including **Contract Manager** and **System Administrator** which will give them comprehensive 'super-user' access to all functions and objects within Salesforce.
**Custom Profiles** allows users to design their own original Profile based on use case specific requirements.
Please see [License Types](https://help.salesforce.com/articleView?id=users_license_types_available.htm\&type=5) for more details.

### Adapting Profiles

The **Contract Manager Profile** comes as standard and has a lot of the permissions needed in order to use the Trigger or Connector effectively.
You can see this by checking out the **Standard Object Permissions** section **within** the Contract Manager Profile setup page:
![contract-manager-object-permissions](https://tray.ai/documentation/images/connectors/service/salesforce/c56d6bf8-22b77352_Group%206.png)
Despite having a lot of access there may be more areas that you would like your User to have access to.
A good approach would be to **clone the Contract Manager profile** and then **edit the permissions** **while bearing in mind the following**:

### Profile Setup sections

Here are the key sections within any Profile Setup page you should be aware of:
**Standard Object Permissions**
Set basic read and write access to objects such as contracts, leads, accounts etc.
**Administrative Permissions**
Where key permissions can be set.
For example **API Enabled** **must be ticked or your authentication will not work**.
**General User Permissions**
Allow extra functionality that cannot be granted purely through object-level permissions.
For example **Activate Contracts** must be ticked for it to be possible to activate a contract. The **Edit** permission on **Contracts and Orders** is not enough to allow contract activation
(you can test activating contracts in Tray with the **Update Record** operation for the **Contract** record type - setting the **Status** field to **'Activated'**).
This applies to several other options within this section such as **Manage Cases** and **Activate Orders**.

### Helpful Resources

#### Tooltips

The Salesforce UI has tooltips which tell you what object settings are also required for certain permissions:
![salesforce-tooltip-manage-cases](https://tray.ai/documentation/images/connectors/service/salesforce/c56d6bf8-4ac85d74_salesforce-tooltip-manage-cases.png)

#### Object permissions

This [User profile permission descriptions](https://help.salesforce.com/articleView?id=000198725\&type=1) article is a great source of reference for explaining more about controlling what Users can do within your Salesforce Organization via User Profile permissions.

## Permission Sets

In Salesforce it is possible to use **Permission Sets** to **extend users' functional access,** **without altering their Profiles**. This means that the level of access within the Profile itself will not change.
The access level of other Users also using the same Profile type will remain the same. Only your selected User will have increased permissions. Permission sets are like access level 'add-ons'.

### Permission Set example

For example say you have a User that has a Read Only profile. Your User already has an allocated Profile with permissions based on that particular Profile group.
In order to extend the access rights for this particular User (without affecting the Profile grouping and thereby the rest of the Users who are also utilising this Profile) you would need to create a Permission set.
You could **create a Permission Set** which has **all the necessary access** required and then **assign the Permission Set to a particular user** .

#### Specifying a license

When you create a Permission Set you can also specify the License it is suppose to be used with:
![new-permission-set](https://tray.ai/documentation/images/connectors/service/salesforce/c56d6bf8-b6937bea_salesforce-new-permission-set.png)