Salesforce CRM

Overview

The Extole app for Salesforce connects Salesforce Sales Cloud to your Extole programs in both directions. It runs inside your Salesforce org as a Lightning app named Extole, and it is installed from Extole’s public extole-sfdc-app repository. The app has seven tabs and one record page component:

Feature	What It Does
Program Analytics	Shows each program’s funnel, a chart over time, and a breakdown by promotion and channel.
KPI Dashboard	Shows metric tiles from the Extole reports you choose, synced hourly, daily, or weekly.
Send Extole Events	Sends an event to Extole when a Salesforce record changes, such as a Lead being created or an Opportunity closing. The app builds and deploys the Salesforce Flow for you, so no code is needed.
Receive Extole Events	Receives events from Extole, such as an advocate creating a share link, and writes them to the matching Contact, Lead, or Person Account. My Extole calls this the Salesforce CRM integration.
Manage Share Links	Creates Extole share links for existing Contacts, Leads, or Person Accounts and writes each link to a field on the record.
Manage Audiences	Adds the people in a Salesforce report to an Extole audience by email, on a schedule.
Configure KPIs	Chooses the Extole reports behind the KPI Dashboard and how often they sync.
Person Card	A component for Lead, Contact, and Person Account record pages that shows the person’s share links, the friends they referred, and who referred them.

Each feature is controlled by its own permission set or toggle, so you can pause or remove one without affecting the others. Uninstalling the app is a standard Salesforce package removal.

How Installation Works

Installation takes about 20–30 minutes, in two phases, followed by the features you choose:

Phase 1 (Steps 1–3) deploys the app and connects it to the Extole API. After Step 3, Program Analytics, the KPI Dashboard, and Manage Share Links work.
Phase 2 (Steps 4–6) sets up the connection that Send Extole Events uses to build Salesforce Flows for you. Salesforce requires an External Client App and a signing certificate for this. It’s the most involved part of the setup, and you do it once per org. If you don’t plan to send Salesforce record events to Extole, skip Steps 4–6 and go to Step 7.
Steps 7–8 assign permissions and launch the app.
Optional features: Share Link Backfill, the Salesforce CRM Integration that receives Extole events, and the Person Card. Set up only the ones you plan to use.

Prerequisites

Git, with SSH access to GitHub configured. See GitHub’s SSH setup documentation.
The Salesforce CLI (sf). See Salesforce’s install guide.
jq and python3.
An Extole access token, created in the Security Center. See Get a Token from My Extole.
A Salesforce org on Lightning Experience, with API access enabled.
A Salesforce admin to install the app, with the Author Apex and Customize Application permissions.

Install the App

Step 1: Clone the Repository and Authenticate

In your terminal, clone the app and log the Salesforce CLI in to your org:

git clone git@github.com:extole/extole-sfdc-app.git
cd extole-sfdc-app
sf org login web --instance-url https://yourdomain.my.salesforce.com --alias extole-org
sf org list

sf org list should show the org under the alias you chose. The examples below use extole-org.

Step 2: Deploy the Package

sf project deploy start --target-org extole-org

This deploys the app’s Apex classes, Lightning components, custom objects, permission sets, and the Extole app.

Step 3: Configure the Extole API Credential

In My Extole, open the Security Center. In the Access Token section, click + New Access Token, give it a descriptive name such as Salesforce Integration, and copy the token. You can’t see it again later.
In Salesforce Setup, navigate to Named Credentials > External Credentials.
Click the Extole API name to open its detail page. Don’t click Edit, which opens a modal instead.
In the Custom Headers section, find the Authorization row, open the dropdown under Actions, and click Edit.
Replace REPLACE_WITH_BEARER_TOKEN with the word Bearer, a space, and your token, for example Bearer 1A2B3C4D.
Click Save.

Step 4: Create the External Client App

Skip Steps 4–6 if you won’t use Send Extole Events. Send Extole Events creates Salesforce Flows that send events to Extole when records change. Creating Flows requires an OAuth app in your org. The app signs in with the OAuth 2.0 JWT Bearer Flow, which needs no interactive sign-in and isn’t affected by Salesforce’s PKCE requirement for the authorization code flow.

In Salesforce Setup, navigate to External Client App Manager and click New External Client App.
Under Basic Information, enter:
- App Name: Extole Deployer
- API Name: Extole_Deployer
- Contact Email: your admin email address
- Logo Image URL: https://www.extole.com/wp-content/uploads/2023/07/Extole-icon-bug.svg
- Distribution: Local
Check Enable OAuth Settings. Under OAuth Settings:
- Set Callback URL to https://login.salesforce.com/services/oauth2/callback. This flow never redirects, but the field is required.
- Add two OAuth Scopes: Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access).
Under Flow Enablement, check Enable JWT Bearer Flow. Leave Enable Authorization Code and Credentials Flow unchecked.
Click Create.
From the app’s row action, select Edit Policies. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized. Under App Policies, move Extole App Admin into Selected Permission Sets. Click Save.

The JWT Bearer Flow has no consent step. With any other Permitted Users value, the token exchange fails with invalid_grant: user hasn't approved this consumer, even when everything else is correct.

Step 5: Run the Tooling Credential Setup Script

In your terminal, from the extole-sfdc-app directory:

bash scripts/setup_named_credential.sh --target-org extole-org

The script deploys the Named Credential and pauses at each step Salesforce only allows in Setup. Follow its prompts. It walks you through the following. Create a signing certificate. In Salesforce Setup, navigate to Certificate and Key Management and click Create Self-Signed Certificate:

Label: Extole Tooling JWT Cert
Unique Name: Extole_Tooling_JWT_Cert
Leave Key Size and Exportable Private Key at their defaults.

Click Save, then click Download Certificate and note where the .crt file was saved. Upload the certificate to the External Client App. Navigate to External Client App Manager > Extole Deployer, select Edit Settings from the row action, and expand OAuth Settings. Under Flow Enablement > Certificate Upload, click Upload Files, select the .crt file, and click Save. Copy the Consumer Key. On the Extole Deployer app’s Settings tab, under OAuth Settings > Consumer Key and Secret, copy the Consumer Key. This flow doesn’t use the secret. Create the External Credential. Navigate to Named Credentials > External Credentials and click New:

Field	Value
Label	`Extole Tooling Cred`
Name	`Extole_Tooling_Cred`
Authentication Protocol	OAuth 2.0
Authentication Flow Type	JWT Bearer Flow
Identity Provider URL	`https://yourdomain.my.salesforce.com/services/oauth2/token`
Issuer (iss)	The Consumer Key you copied
Subject (sub)	The username of the admin who runs Send Extole Events, ideally a dedicated integration user (see Step 7)
Audience (aud)	`https://yourdomain.my.salesforce.com`, with no path
Signing Certificate	`Extole Tooling JWT Cert`
Signing Algorithm	RS256 (the default)

Click Save. On the new credential’s detail page, under Principals, click New and enter Parameter Name Admin and Identity Type Named Principal, leaving Scope blank. Click Save, then return to the terminal and press Enter. The script also gives the Extole_App_Admin permission set access to this credential.

Step 6: Verify the Tooling Credential

In Salesforce Setup, navigate to Named Credentials > Named Credentials, click Extole Tooling, and confirm the page shows no errors. There is no Authenticate button to click for this flow. Step 8 tests the credential end to end. If an event later fails with an authentication error, check that the certificate in Certificate and Key Management hasn’t expired or been deleted, and that the External Credential’s Issuer, Subject, and Audience still match the Consumer Key and your org’s domain.

Step 7: Assign Permission Sets

Assign Extole_App_Admin to yourself and to every admin who will set up Program Analytics, the KPI Dashboard, or the events sent to and from Extole:

sf org assign permset --name Extole_App_Admin --target-org extole-org

Assign Extole_App_Viewer to users who only need to see Program Analytics and the KPI Dashboard:

sf org assign permset --name Extole_App_Viewer --target-org extole-org

To assign a permission set to another user, add --on-behalf-of followed by their username. Either permission set makes the Extole app appear in the App Launcher.

In a production org, create a dedicated integration user (a non-human Salesforce user with a full license), assign it Extole_App_Admin, and use its username as the Subject (sub) on the Extole Tooling Cred External Credential. Send Extole Events then keeps working if the admin who set it up leaves.

Step 8: Launch the App and Complete Onboarding

Open the Extole app from the App Launcher. The Getting Started screen appears the first time.
Open the Send Extole Events tab and click Test Connection. It should show that the app is connected.
Open the Configure KPIs tab, click Add KPI, and set up your first KPI. The report must already exist and be scheduled in Extole. A report that hasn’t run yet syncs no data.
Click Sync Now on the Configure KPIs tab. The KPI Dashboard fills in when the first sync finishes.

The Manage Share Links tab creates Extole share links for existing records and writes each link to the Extole_Share_Link__c field. The field is deployed with the app, but you must add it to your page layouts to see it on a record. To add the field to the Contact and Lead page layouts:

In Salesforce Setup, navigate to Object Manager > Contact > Page Layouts, and open the layout in use (usually Contact Layout).
Find Extole Share Link in the field palette and drag it onto the layout. Click Save.
Repeat for Object Manager > Lead > Page Layouts.

To create share links:

Open the Manage Share Links tab and choose Contacts, Leads, or, in an org with Person Accounts, Person Accounts.
Choose which records to process:
- Closed/Won opps: Contacts on accounts with a Closed Won opportunity.
- Created after date: records created on or after a date you pick.
- Salesforce Report: the records in a saved report, up to 2,000 rows.
Optionally choose a Campaign. Leave it blank to use the default campaign.
Click Create Share Links, and follow each record’s result in the log on the same tab.

Running it again for the same person returns their existing share link instead of creating a second one.

Salesforce CRM Integration

The Salesforce CRM integration in My Extole sends an event to the app’s Receive Extole Events tab each time an advocate creates a share link. The app writes the fields you map to the matching Contact, Lead, or Person Account in Salesforce. Extole calls into Salesforce in this direction, so Salesforce needs a second External Client App that uses the Client Credentials flow, and Extole needs a key that holds its credentials.

Create the External Client App for Receiving Events

In Salesforce Setup, navigate to External Client App Manager and click New External Client App.
Under Basic Information, enter an App Name (for example, Extole Receive Events), a matching API Name, and a Contact Email, and set Distribution to Local.
Check Enable OAuth Settings. Under OAuth Settings, add two scopes:
- Manage user data via APIs (api)
- Perform requests at any time (refresh_token, offline_access)
Under Flow Enablement, check Enable Client Credentials Flow, then click Create.
From the app’s row action, select Edit Policies. Under OAuth Policies:
- Set Permitted Users to Admin approved users are pre-authorized. The Client Credentials flow has no consent step, so with any other value the token exchange fails with invalid_grant: user hasn't approved this consumer.
- Under Client Credentials Flow, set the Run As user to a dedicated integration user or an admin, and assign that user the Extole_Webhook_Integration permission set. Every request from Extole runs as this user, and Salesforce shows it as the creator, last modifier, and owner of the records Extole writes.
Click Save.
On the app’s Settings tab, under OAuth Settings, copy the Consumer Key and Consumer Secret.

Create the Salesforce Key in Extole

In My Extole, create a new key in the Security Center with these values:

Field	Example Value
Key Name	Salesforce Client Credentials
Key Type	Webhook
Algorithm	OAUTH_SFDC
Key	The Consumer Secret from the previous step
Authorization URL	https://yourdomain.my.salesforce.com/services/oauth2/token
OAUTH Client ID	The Consumer Key from the previous step

Choose OAUTH_SFDC, not OAUTH_SALESFORCE or OAUTH_SFDC_PASSWORD. OAUTH_SFDC is the algorithm built for the Salesforce Client Credentials flow.

Set Up the Integration

The person who sets up Receive Extole Events needs the Extole_App_Admin permission set.

In Salesforce, open the Extole app’s Receive Extole Events tab and copy the Webhook Endpoint. The app builds it from your org’s own domain, so it ends in /services/apexrest/extole/events.
In My Extole, navigate to Partners, select Salesforce CRM, and click Install.
Set Salesforce Endpoint URL to the Webhook Endpoint you copied, and set Salesforce OAuth Credentials to your OAUTH_SFDC key.
Turn on Enable Salesforce Writeback. It’s off by default. While it’s off, the integration sends nothing and nothing is logged on either side, so you can use it to pause the integration and keep the endpoint and key filled in.
In Salesforce, on the Receive Extole Events tab, click Add Rule. Enter share_link_created as the event name and choose the Salesforce Object: Contact, Lead, or, in an org with Person Accounts, Person Account. For a Contact or Lead, turn on Create the record if it is not found if the app should create the record when none matches. Then map the event’s fields to the object’s fields. Target fields must be Text fields, because the app writes every value as text and a Number or Date field silently stays empty.
As an advocate, create a share link, then confirm the event appears in the Event Log on the Receive Extole Events tab.

How Records Are Matched and Created

The app matches a record by the person’s salesforce_id in Extole first, and by email when there is no salesforce_id or no record with that ID. A Person Account is matched by its person email. When no record matches, the app skips the event, unless the rule has Create the record if it is not found turned on:

The app creates a Lead or Contact from the event’s email, and from first_name and last_name when the event sends them. A missing last name becomes “Unknown”, because Salesforce requires one. In an org without Person Accounts, a created Lead’s Company is also “Unknown”.
The app doesn’t create a Lead or Contact when the email already belongs to a Contact or Person Account. The Event Log shows the event as skipped, with the reason.
The app never creates a Person Account.

Event Payload

Each share link sends one request. event_id is unique to the share link event, and the app ignores a repeated event_id. data holds the share link event’s data, plus the person’s email and salesforce_id:

{
    "event_id": "1234567890123456789",
    "event_name": "share_link_created",
    "data": {
        "email": "advocate@example.com",
        "salesforce_id": "003XXXXXXXXXXXXXXX"
    }
}

Send Other Events

The integration sends share link events (share_link_created) only. To send another event to Salesforce, such as a reward, a referral click, or a custom action:

In My Extole, add a Webhook step to that event’s flow, and set Webhook to the integration’s salesforce_crm_writeback webhook.

Set Webhook Body Data to the body the app expects: an event_name that matches a rule on the Receive Extole Events tab, an event_id the app uses to skip duplicates, and email and salesforce_id inside data. For example:

javascript@runtime:(function () {
    const person = context.getPerson();
    return {
        event_id: context.getStepEvent().getId(),
        event_name: "reward_earned",
        data: {
            email: person.getEmail(),
            salesforce_id: person.getData().get("salesforce_id") || null
        }
    };
})();

In Salesforce, add a rule on the Receive Extole Events tab for that event_name.
Save the change in My Extole, trigger a test event, and confirm it appears in the Event Log on the Receive Extole Events tab.

Add the Person Card to Record Pages

The Extole Person Card shows a person’s share links, the friends they referred and each friend’s progress, and who referred them. It shows referral activity only, so a reward from a program without a referral doesn’t appear on it. Give the card its own tab on the record page, rather than adding it to a crowded column:

Open a Lead or Contact record, click the gear icon, and select Edit Page.
Add a tab to the page’s tab set and name it, for example Refer-a-Friend.
Drag the Extole Person Card component into the new tab.
Click Save, then Activate the page for the org or profiles that need it.
Repeat for the other object. Lead and Contact pages are set up separately.

To turn the card off without removing it, select it in Lightning App Builder and check Disabled.

Person Accounts

The app detects Person Accounts on its own. In an org without them, nothing changes.

Feature	With Person Accounts
Person Card	Add Extole Person Card to the Person Account record page. It shows only on Person Accounts and stays hidden on business accounts.
Send Extole Events	Choose Account as the trigger object and map `PersonEmail` to `email`. For Opportunity events, map `Account.PersonEmail` to `email` and `Account.PersonContactId` to `partner_user_id`. An Account trigger also fires for business accounts, and those events carry no email.
Receive Extole Events	Choose Person Account as a rule’s Salesforce Object. The app finds the Person Account by its person email and updates it. It never creates one.
Manage Share Links	Choose Person Accounts. For a report, the first column must be `ACCOUNT_ID` or `PC_CONTACT_ID`. The link is written to the Account’s person field, such as `Extole_Share_Link__pc`.
Manage Audiences	Use a tabular Accounts report and choose Person Account: Email (`PC_EMAIL`) as the identity column.

With Person Accounts on, a Lead created by Create the record if it is not found has no Company, so converting it creates a Person Account instead of a business account. Custom Lead fields, such as the share link, reach the Person Account only if you map them in Setup under Object Manager > Lead > Fields & Relationships > Map Lead Fields. Each org sets this once.

Troubleshooting

Symptom	Likely Cause
`InvalidProjectWorkspaceError` on deploy	You aren’t in the cloned repository. Run `cd extole-sfdc-app` first.
Test Connection fails	The bearer token is wrong, missing, or expired. Check Step 3.
A Send Extole Events deploy fails with “named credential … might not exist”	The Named Credential must be named exactly `Extole_Tooling` (label Extole Tooling). Check Step 5.
A Send Extole Events deploy fails with a JWT or token exchange error	Check that the signing certificate hasn’t expired or been deleted, and that the External Credential’s Issuer, Subject, and Audience still match the Consumer Key and your org’s domain.
Token exchange fails with `invalid_grant: user hasn't approved this consumer`	The External Client App’s Permitted Users must be Admin approved users are pre-authorized. For the Extole Deployer app, Extole App Admin must also be in Selected Permission Sets.
The scheduled KPI sync doesn’t run	On Configure KPIs, change the sync cadence and save to register the job again.
Permission errors on the app’s objects	The user is missing `Extole_App_Admin` or `Extole_App_Viewer`.
The share link field isn’t visible on a Contact or Lead	The field isn’t on the page layout. See Set Up Share Link Backfill.
The Extole app doesn’t appear in the App Launcher	Confirm the user has `Extole_App_Admin` or `Extole_App_Viewer`. If they do, deploy the permission set again.
”You do not have access to the Apex class named …” on a tab	The user’s permission set doesn’t grant that class. Check Apex Class Access on the permission set.
A tab shows no data and no error	Check the user’s Apex debug log for a permission error before assuming the data is missing. A missing read permission on the `UserExternalCredential` object has caused this.
Receive Extole Events shows no incoming events	Confirm Enable Salesforce Writeback is on, the receiving External Client App has the Client Credentials flow enabled, and its Consumer Key and Consumer Secret match the key set as Salesforce OAuth Credentials. Check the Event Log for delivery attempts and errors.
Extole requests return `401 INVALID_SESSION_ID` though the token exchange works	The webhook’s request script uses `context.createRequestBuilder()` instead of `context.createRequestBuilderWithDefaults()`. Only the second attaches the key’s Authorization header.

For more detail, turn on Debug Logging Enabled on the Send Extole Events tab, and check the sync log on the Configure KPIs tab.

Integration Overview

Extole AI Tools

Platform Integrations

Partners

Building Partner Integrations

Solutions

Operational Tasks

Troubleshooting

Overview

How Installation Works

Prerequisites

Install the App

Step 1: Clone the Repository and Authenticate

Step 2: Deploy the Package

Step 3: Configure the Extole API Credential

Step 4: Create the External Client App

Step 5: Run the Tooling Credential Setup Script

Step 6: Verify the Tooling Credential

Step 7: Assign Permission Sets

Step 8: Launch the App and Complete Onboarding

Salesforce CRM Integration

Create the External Client App for Receiving Events

Create the Salesforce Key in Extole

Set Up the Integration

How Records Are Matched and Created

Event Payload

Send Other Events

Add the Person Card to Record Pages

Person Accounts

Troubleshooting

​Overview

​How Installation Works

​Prerequisites

​Install the App

​Step 1: Clone the Repository and Authenticate

​Step 2: Deploy the Package

​Step 3: Configure the Extole API Credential

​Step 4: Create the External Client App

​Step 5: Run the Tooling Credential Setup Script

​Step 6: Verify the Tooling Credential

​Step 7: Assign Permission Sets

​Step 8: Launch the App and Complete Onboarding

​Set Up Share Link Backfill

​Salesforce CRM Integration

​Create the External Client App for Receiving Events

​Create the Salesforce Key in Extole

​Set Up the Integration

​How Records Are Matched and Created

​Event Payload

​Send Other Events

​Add the Person Card to Record Pages

​Person Accounts

​Troubleshooting

Overview

How Installation Works

Prerequisites

Install the App

Step 1: Clone the Repository and Authenticate

Step 2: Deploy the Package

Step 3: Configure the Extole API Credential

Step 4: Create the External Client App

Step 5: Run the Tooling Credential Setup Script

Step 6: Verify the Tooling Credential

Step 7: Assign Permission Sets

Step 8: Launch the App and Complete Onboarding

Set Up Share Link Backfill

Salesforce CRM Integration

Create the External Client App for Receiving Events

Create the Salesforce Key in Extole

Set Up the Integration

How Records Are Matched and Created

Event Payload

Send Other Events

Add the Person Card to Record Pages

Person Accounts

Troubleshooting