# Salesforce Connect Setup Guide (AOLL) — Full Detail

This guide is for a **new person** setting up Salesforce for AOLL Connect.

Follow every step in order.  
When Salesforce shows options, choose **exactly** what is written here.

> **Company switch later**  
> You may do this first on a **Developer Edition** (personal/test).  
> Later, create the Connected App on the **company Salesforce org** (or Partner / Dev Hub),  
> then replace Client ID + Secret in `Constants.php`.

---

# PART A — What you already have

From your screenshot, you are logged into:

**Salesforce Developer Edition**  
URL looks like:

```text
....develop.lightning.force.com/lightning/n/devedapp__Welcome
```

Page title: **Your Developer Edition Toolkit**

You are ready to create a **Connected App** (OAuth app for AOLL).

Also make sure:

- AOLL is available at `https://dev.aoll.com`
- Table `aoll_connections` already exists (same table used by HubSpot)

---

# PART B — Open Salesforce Setup (from your current screen)

## Step 1: Open Setup

On the top-right of Salesforce, click the **gear icon** ⚙️  
Then click **Setup**

(Do **not** click Help or Learning Paths.)

## Step 2: Confirm you are in Setup

Left side shows Setup menu.  
Top may say **Setup** / Home.

---

# PART C — Create Connected App

## Step 3: Open App Manager

1. In Setup Quick Find (left search box), type: `App Manager`
2. Click **App Manager**

## Step 4: Start new Connected App

Top-right of App Manager, click:

**New Connected App**

> If you only see **New External Client App**, use that instead.  
> It is the newer Salesforce name for the same idea.  
> Choose type that supports **OAuth** / web app.

---

# PART D — Fill Connected App form (exact values)

## Step 5: Basic Information

Fill:

| Field | Value |
|---|---|
| Connected App Name | `AOLL` |
| API Name | `AOLL` (auto-filled usually) |
| Contact Email | your company/work email |

Optional logo/description can be skipped for now.

## Step 6: Enable OAuth Settings

1. Find section **API (Enable OAuth Settings)**
2. Tick checkbox: **Enable OAuth Settings**

## Step 7: Callback URL (very important)

In **Callback URL**, paste exactly:

```text
https://dev.aoll.com/connectors/salesforce/callback
```

Rules:

- Must be HTTPS
- Must match AOLL `SALESFORCE_REDIRECT_URI` exactly
- Do **not** use `http://192.168.x.x`

(Optional later for production, add another line:)

```text
https://aoll.com/connectors/salesforce/callback
```

## Step 8: Selected OAuth Scopes

From Available OAuth Scopes, add these:

1. **Access and manage your data (api)**
2. **Perform requests on your behalf at any time (refresh_token, offline_access)**

How:

- Select each scope on the left
- Click **Add** (arrow) to move to Selected OAuth Scopes

Do **not** only choose “openid” or “profile”.  
AOLL needs `api` + refresh token.

## Step 9: Extra OAuth checkboxes

Set:

| Option | Choose |
|---|---|
| Require Secret for Web Server Flow | **Checked** (ON) |
| Require Secret for Refresh Token Flow | **Checked** (ON) |
| Enable Client Credentials Flow | OFF (not needed now) |
| Enable Authorization Code and Credentials Flow | leave default / as shown |
| Enable Device Flow | OFF |
| PKCE | optional; leave default if unsure |

## Step 10: Save

Click **Save**.

Salesforce may show a warning:

> changes can take 2–10 minutes to apply

That is normal. Wait a few minutes before first Connect test.

---

# PART E — Get Consumer Key and Consumer Secret

## Step 11: Open Manage Consumer Details

After save, on the Connected App detail page:

1. Click **Manage Consumer Details**  
   (or **Continue** / **Verify** if asked)
2. Salesforce may ask you to verify identity (email/code)
3. Complete verification

## Step 12: Copy credentials

You will see:

- **Consumer Key** → this is Client ID
- **Consumer Secret** → this is Client Secret

Copy both and store securely.

---

# PART F — Allow users to authorize the app

## Step 13: Open Manage policies

On Connected App page:

1. Click **Manage**
2. Click **Edit Policies**

## Step 14: Set policies

Set:

| Field | Value |
|---|---|
| Permitted Users | **All users may self-authorize** |
| IP Relaxation | **Relax IP restrictions** |
| Refresh Token Policy | Refresh token is valid until revoked (recommended) |

Click **Save**.

---

# PART G — Put credentials in AOLL

## Step 15: Open Constants file

Open:

```text
app/Config/Constants.php
```

## Step 16: Paste Salesforce values

```php
define('SALESFORCE_CLIENT_ID', 'PASTE_CONSUMER_KEY_HERE');
define('SALESFORCE_CLIENT_SECRET', 'PASTE_CONSUMER_SECRET_HERE');
define('SALESFORCE_LOGIN_URL', 'https://login.salesforce.com');
define('SALESFORCE_SCOPES', 'api refresh_token offline_access');
define('SALESFORCE_SIGNUP_URL', 'https://developer.salesforce.com/signup');
define('SALESFORCE_REDIRECT_URI', 'https://dev.aoll.com/connectors/salesforce/callback');
```

### Notes

- Developer Edition / Production login host: `https://login.salesforce.com`
- Sandbox login host: `https://test.salesforce.com`
- For your current Developer Edition, keep `login.salesforce.com`

Save file and **deploy to `dev.aoll.com`**.

---

# PART H — Confirm AOLL routes exist

These routes are already in AOLL code:

| Purpose | URL |
|---|---|
| Start connect | `https://dev.aoll.com/connectors/salesforce/connect` |
| Callback | `https://dev.aoll.com/connectors/salesforce/callback` |
| Disconnect | `https://dev.aoll.com/connectors/salesforce/disconnect` |

Same DB table as HubSpot:

```text
aoll_connections
```

provider value saved as: `salesforce`

---

# PART I — Test Connect in AOLL

## Step 17: Open AOLL

Go to:

[https://dev.aoll.com](https://dev.aoll.com/)

Log in.

## Step 18: Connect Salesforce

1. Open **Connectors**
2. Click Salesforce **Connect**
3. Click **Sign in to your Salesforce account**
4. Login to Salesforce if asked
5. Click **Allow** on permission screen
6. You return to AOLL

Success means:

- Green message: **Salesforce connected successfully**
- Button shows **Connected**
- Disconnect option available

---

# PART J — If you see errors

## “Salesforce is not configured…”
Client ID/Secret empty on server `Constants.php`. Deploy values.

## redirect_uri mismatch
Callback URL in Salesforce Connected App must exactly equal:

```text
https://dev.aoll.com/connectors/salesforce/callback
```

## invalid_client_id / app not found
Wait 5–10 minutes after creating Connected App, then retry.

## OAUTH_APPROVAL_ERROR / user cannot authorize
Check policies:

- Permitted Users = All users may self-authorize
- IP Relaxation = Relax IP restrictions

## Connected but API later fails
Confirm scopes include `api` and `refresh_token` / `offline_access`.

---

# PART K — Switch to company Salesforce later

When company org is ready:

1. Login to **company** Salesforce (Setup)
2. Create Connected App again with same Callback URL + scopes
3. Copy new Consumer Key / Secret
4. Replace in `Constants.php`:
   - `SALESFORCE_CLIENT_ID`
   - `SALESFORCE_CLIENT_SECRET`
5. Deploy to `dev.aoll.com` / production
6. Re-test Connect

Personal Developer Edition credentials should not be used in final production.

---

# Exact option cheat-sheet

| Step | Choose |
|---|---|
| Open Setup | Top-right **gear → Setup** |
| Create app | **App Manager → New Connected App** |
| App name | `AOLL` |
| Enable OAuth | **ON** |
| Callback URL | `https://dev.aoll.com/connectors/salesforce/callback` |
| Scopes | `api` + `refresh_token, offline_access` |
| Require Secret (Web Server) | **ON** |
| Require Secret (Refresh) | **ON** |
| Permitted Users | **All users may self-authorize** |
| IP Relaxation | **Relax IP restrictions** |
| Login URL in AOLL | `https://login.salesforce.com` |

---

# Final checklist

- [ ] Opened Salesforce Developer Edition
- [ ] Gear → Setup
- [ ] App Manager → New Connected App
- [ ] Named app `AOLL`
- [ ] Enabled OAuth
- [ ] Callback URL set to `https://dev.aoll.com/connectors/salesforce/callback`
- [ ] Scopes added (`api`, refresh/offline)
- [ ] Saved and waited a few minutes
- [ ] Copied Consumer Key + Secret
- [ ] Policies set (self-authorize + relax IP)
- [ ] Values pasted in `Constants.php`
- [ ] Deployed to `dev.aoll.com`
- [ ] Connectors → Salesforce → Connected works

---

# What AOLL code does (summary)

| Item | Purpose |
|---|---|
| `SalesforceController` | OAuth start / callback / disconnect |
| `ConnectionModel` | Save encrypted tokens (`provider = salesforce`) |
| Connectors UI | Connect / Connected / Disconnect |
| `SALESFORCE_*` constants | Credentials + redirect + login host |

Next product step (later): push Accounts/Contacts from AOLL into Salesforce using saved tokens.