UserEvidence Advocacy — Salesforce Admin Setup Guide · UE Advocacy Managed Package

Welcome! This guide walks you through everything needed to stand up UE Advocacy in your org: granting access, placing the Lightning components, connecting your UserEvidence account, and wiring up the UserEvidence → Salesforce connection. No developer experience is required — if you can install a managed package, assign a permission set, and edit a Lightning page, you can complete this setup. Budget about 45–60 minutes end to end.

Two guides, two audiences. This is the admin setup guide. For a plain-language explanation of what the tool does and how sellers and program managers use it day to day, see the companion Manage Package User Guide.

About the "Zealot" name. You may notice zealot / joinzealot.com in a few field API names and endpoint URLs (for example the API host api2.joinzealot.com). That is the product's original name — UE Advocacy was previously called Zealot. The functionality is identical, and those API names cannot be renamed because the sync depends on the exact strings. Nothing for you to do; just don't be surprised by them.

1. Overview

UE Advocacy connects your Salesforce org to the UserEvidence advocacy platform so that reference and advocacy activity is visible, actionable, and reportable directly inside Salesforce. Three things move between the two systems:

Part	Direction	How it works
Reference Management	In Salesforce	A Lightning panel on the Opportunity lets sellers request and track customer references without leaving Salesforce.
Advocacy writeback + advocate sync	UserEvidence → Salesforce	UserEvidence writes reference activity and advocate contacts into Salesforce by calling the package's own secure endpoints. This is the connection you set up in Step 6.
Data the panel sends	Salesforce → UserEvidence	When a seller submits a request, the panel calls UserEvidence server-side (behind the scenes, using your stored token) to create the reference.

The package supports two advocate journeys:

Reference flow — a seller needs a customer reference to help close a deal. They request or choose one from the Opportunity, and it moves through a fixed set of stages until it is completed.
Referral flow — an advocate refers a new prospect. UserEvidence creates a Lead with attribution, and when the seller converts it, the attribution carries onto the new Opportunity. (Setup for this flow is optional — see Step 7.)

2. Prerequisites

Before you begin, confirm the following:

Edition: Enterprise or higher.
Org settings: API Enabled, and the installing user must be allowed to install managed packages.
Admin permissions: a Salesforce admin with Customize Application and API Enabled.
Sandbox first: access to a sandbox — always install and validate there first, then repeat in production.
UserEvidence API token: your org's token (used in Step 4). Your UserEvidence CSM provides it.
A plan for the Run-As user (Step 6) — ideally a dedicated Salesforce Integration user license (free, API-only).

3. Installing the package

Install into a sandbox first, complete the configuration below, verify it, then repeat the same steps in production.

Your CSM provides an install URL (it ends in .../packaging/installPackage.apexp?p0=<version id>).
- Production / Developer: [Install link — to be provided]
- Sandbox: [Install link — to be provided]
Install into the right org. A production install link defaults to production. For a sandbox, log into the sandbox first (or swap login.salesforce.com for test.salesforce.com in the URL). Beta versions can only be installed in a sandbox, not in production.
Choose Install for All Users so the package is available to everyone who needs it. (You still control who actually uses each piece through the permission sets you assign in the next step.)
If prompted, check "Yes, grant access to these third-party web sites."
Click Install / Upgrade. Large installs finish by email — that is normal.

4. Post-install configuration

Complete these steps in order. Steps 1–7 below map to the setup tasks; the permission-set detail is expanded in Section 5.

Step 1 — Assign permission sets

Setup → Permission Sets, then for each set: Manage Assignments → Add Assignments → select users → Assign.

Permission set	Assign to	Grants
UE Advocacy Admin	Admins, program managers	Full access, the Configuration tab, and edit on the advocacy/config data.
UE Advocacy User	Sellers, CS	Day-to-day use of the panel and records within normal sharing; no Configuration tab.
UE Advocacy Integration	The Run-As user only (Step 6)	Least-privilege access for the UserEvidence → Salesforce connection. Do not assign it to people.

The Integration set exists specifically for the connection's Run-As user. Assign it in Step 6, not to your everyday users.

Step 2 — Add the components to the Opportunity page

Open any Opportunity → gear → Edit Page (Lightning App Builder).
From the Components palette (under Custom - Managed), drag on:
- Reference Management — the request/track panel.
- UE Reference Trackers — the stacked per-request stage trackers.
- UE Reference Matches (optional) — recommended advocates for the deal.
Save → Activate, and assign the page (usually Assign as Org Default for Opportunity).

The UE Advocacy record page ships preconfigured — those records open with the stage bar and grouped fields, no action needed.

Step 3 — Add the reference fields to your Opportunity layout

The package cannot place fields on your standard Opportunity layout, so add them once so the writeback is visible:

Setup → Object Manager → Opportunity → Page Layouts → open your layout.
Add a Section (for example "UE Advocacy") and drag in the writeback fields: UE Advocacy Reference ID, Reference Completed By, UE Advocacy Reference Status, Reference Received Date. (Optional: UE Opportunity UUID, the sync correlation id.)
Save.

Using Dynamic Forms or an Opportunity record page (Flexipage)? Add the same fields there instead: Setup → Object Manager → Opportunity → Lightning Record Pages → edit the page → drag the fields onto the form → Save & Activate.

Step 4 — Connect your UserEvidence account (API token)

The UE Advocacy Configuration tab (visible to UE Advocacy Admin) stores your org's UserEvidence token and settings. It is backed by a protected custom setting, so the token is never displayed back once saved.

Open the UE Advocacy Configuration tab → Connection.
Paste your org's API token (from your CSM) and Save. The token is held in protected storage and is never displayed back — pasting a new value simply rotates it.

Base URL stays locked to the UserEvidence production endpoint (api2.joinzealot.com) — no action needed. Proactive matches is an optional toggle, off by default.

Which buttons reps see. The Reference Management panel offers Request (the full form, with the questions your brand configured) and Choose (a shorter self-serve path). There is no setting for this in Salesforce — the panel follows your brand's Request Routing Mode in UserEvidence:

UserEvidence setting	Panel shows
Request Reference Only	Request only
AE Self-Serve	Choose only
Either	Both buttons

Change it under Settings → References → Request Routing Mode in UserEvidence, or ask your CSM. If the panel cannot reach that setting it shows both buttons, so a temporary outage never leaves a rep unable to raise a reference.

Earlier versions had a Reference actions dropdown on this screen. It was removed in favor of the UserEvidence setting; any value your org had saved is now ignored.

Hide advocate email. The same screen has a Hide advocate email on the reference tracker toggle (off by default). Turn it on if your org treats advocate email addresses as sensitive: the Reference Requests tracker then shows advocates by first name and account only (from their Contact record), and as Advocate assigned when no Contact matches. Nothing else changes — the address is still stored on the record for reporting.

Hide reference Title and Description. Reps can add a Salesforce-only Title and Description to each reference request (shown on the tracker, never sent to UserEvidence). They are on by default. Turn on Hide reference Title and Description to remove those two fields from the Request and Choose forms and from the tracker for your org.

Step 5 — Choose the fields to sync (Field Selection)

On the same Configuration console, the Field Selection tab is where you pick which Salesforce fields UserEvidence should sync, per model and direction.

Open UE Advocacy Configuration → Field Selection.
Pick a model (advocate / opportunity / reference request) and a direction (Read from or Write to Salesforce).
Choose an object, search, and tick the fields to include. Save.

The package only stores your picks; UserEvidence reads them and owns the mapping on its side. You are just telling it which fields you want in play.

Step 6 — Set up the UserEvidence → Salesforce connection (ECA + Run-As user)

This is how UserEvidence securely writes reference activity and advocate contacts back into your org. It uses a packaged External Client App (ECA) — you never handle any keys or secrets; you enable the flow and nominate a user. Allow about 20 minutes, once per org (and once per sandbox you want connected).

What "Run As" means: UserEvidence acts as a Salesforce user you nominate. Whatever that user can see and edit is exactly what UserEvidence can — nothing more.

6a — Create the Run-As user

Setup → Users → New User.
License: Salesforce Integration · Profile: Minimum Access - API Only Integrations.
Name it clearly (for example UserEvidence Integration), Save, and make sure it is Active.

This free, API-only license is Salesforce's purpose-built integration user — nobody can log in as it through the UI (that is intended). An existing active, API-enabled user also works for a quick sandbox test, but a dedicated user is strongly recommended for production.

6b — Give that user access

Assign the UE Advocacy Integration permission set to this user (Permission Sets → UE Advocacy Integration → Manage Assignments → Add Assignment).
Also grant this user Read + View All Records on the Opportunity object, through its profile or a permission set you create. This step is required, and it cannot come from the packaged set: Salesforce does not allow a managed package to grant permissions on standard objects like Opportunity, so that grant has to be yours.
- View All Records, not just Read. If your Opportunity sharing is Private, Read alone lets the user see the object but none of the records, and reference requests will not link to their deal.
- Edit is not needed. The package updates its own Opportunity fields itself. Read-only is enough.

Use UE Advocacy Integration for the Run-As user (not Admin, not User). It is the least-privilege set built for exactly this.

6c — Enable the connection

Setup → Quick Find → External Client App Manager.
Open UE Advocacy (Type shows Packaged (Installed)).
Policies tab → Edit → expand OAuth Policies.
Under OAuth Flows and External Client App Enhancements, tick Enable Client Credentials Flow.
In Run As (Username), enter the username of your Run-As user from 6a.
Save. Leave the other policies as they are.

6d — Send UserEvidence your domain

Send your My Domain URL to UserEvidence (find it under Setup → My Domain), for example https://yourcompany.my.salesforce.com. For a sandbox, send that sandbox's domain (it differs from production). UserEvidence confirms the connection from their side.

That is the whole connection. No keys, no secrets, nothing to copy out of Salesforce.

Step 7 — Add the Contact fields & set up the advocate sync

UserEvidence pulls your advocate contacts into its platform, and it decides which contacts to pull from a packaged field on Contact — UE Advocate Status. There are two parts: surface the fields, then decide how contacts get flagged.

7a — Add the Contact fields to your layout

Setup → Object Manager → Contact → Page Layouts → open your layout (add a Section like "UserEvidence" if you like), and drag in:
- UE Advocate Status (UE_Advocate_Status__c) — the field you (or your automation) set. Keep it editable.
- UE FanUser UUID (UE_FanUser_Uuid__c) — filled in by the package once a contact is synced; set it read-only for users.
Save.

Using Dynamic Forms or a Contact record page (Flexipage)? Add the same two fields there: Setup → Object Manager → Contact → Lightning Record Pages → edit the page → drag the two fields onto the form → Save & Activate.

7b — Flag the contacts to sync

You have two ways to do this. Pick one.

Option A — use the UE Advocate Status field (the default).

Set a contact's UE Advocate Status to Should Be Advocate to queue it for sync. The package fills in UE FanUser UUID and flips the status to Is Advocate once synced, so it is not sent twice. Disabled takes a contact out of scope.
Set it manually per contact, or drive it with your own automation (for example a Flow that flips it based on your criteria).

Option B — point us at your own field (Advocates tab).

If you already track advocates on Contact, or you want the rule to live in Salesforce rather than in a Flow:

Open UE Advocacy Configuration → Advocates.
Move one or more fields into Marks an advocate. The list shows every checkbox and true/false formula field on Contact — only those, because a criterion has to be a yes or no. Text and picklist fields (Title, Department, Lead Source…) never appear, so if the list looks short or empty that is expected: create a field first, as below.
If you pick more than one, choose whether a contact must match ALL of them or ANY of them.
Save. UserEvidence checks for newly matching contacts about once an hour and adds them automatically — there is no sync button to press. You can change your selection any time.

Rules more complex than a checkbox? Create a single formula field on Contact of type Checkbox that returns true when someone should be an advocate, then select it here. A formula can look at the parent Account, record types, multi-select picklists and so on — so an entire eligibility rule fits in one field. Formulas are also always up to date, so a newly qualifying contact is picked up with no extra work.

One tradeoff: formula fields are not indexed. If you have a very large number of contacts, a plain checkbox kept up to date by a Flow will be noticeably faster to sync than a formula.

Selecting nothing on the Advocates tab keeps Option A. Choosing fields here replaces the UE Advocate Status rule — contacts are then selected purely by your criteria, with one exception below.

Excluding one person without changing the rules. Set that contact's UE Advocate Status to Disabled. It overrides your criteria, so a contact who matches every rule is still held back. This is the intended way to take a single person out of scope — you should never have to loosen the rules for everyone to exclude one contact.

Note: if a contact later stops matching your criteria, the package does not delete anything on the UserEvidence side — they keep their UE FanUser UUID. What the package now does is report it: the contact is flagged as no longer qualifying whenever UserEvidence runs a reconciliation, so their team can retire the advocate. If you need it done immediately rather than at the next reconciliation, take them out of scope in UserEvidence directly.

Step 8 — (Referral flow only) Configure referral attribution

Skip this unless you use the referral flow (advocates submitting leads). A few fields live in your org, not the package:

Add the referral fields to Lead and Opportunity, and the Linked Lead lookup on UE Advocacy. (Your CSM or developer has the exact field spec.)
Add the Advocate Referral value to the Lead Source picklist (Object Manager → Lead → Lead Source).
Map Lead → Opportunity fields on conversion: Object Manager → Lead → Map Lead Fields, and map the referral fields to their Opportunity counterparts. Skipping this silently drops attribution on conversion.

Step 9 — Reports & dashboards

Reference KPIs: the UE Advocacy report folder + UE Advocacy Dashboard.
Referral KPIs: the UE Advocacy - Referrals folder (R-1…R-10) + Advocate Referral Performance dashboard.
Build your own: use the Opportunities with UE Advocacies report type (Reports → New Report).

5. Permission sets

Earlier versions of the package shipped without permission sets, and you may see older notes to that effect. The current package ships three permission sets — grant access with these rather than editing profiles by hand:

Permission set	Who gets it	In one line
UE Advocacy Admin	Admins / program managers	Everything, including the Configuration tab and edit on the advocacy/config data.
UE Advocacy User	Sellers / CS	Day-to-day use of the panel and records; no Configuration tab; most reference/referral fields read-only.
UE Advocacy Integration	The ECA Run-As user only	Least-privilege access for the UserEvidence → Salesforce connection.

Note on Opportunity access: the packaged sets grant the package's own objects and fields, but standard object access has to come from your org — Salesforce does not let a managed package grant permissions on standard objects such as Opportunity. Your everyday users get theirs from their profile as usual. The Run-As user needs it explicitly, because an API-only user starts with no standard object access at all: give it Read + View All Records on Opportunity as described in Step 6b.

6. Verifying the setup

Run through this smoke test after setup:

Access — open the UE Advocacy app from the App Launcher; confirm the UE Advocacy tab and (for admins) the Configuration tab load.
Panel — open a test Opportunity; confirm Reference Management renders and loads contacts, and the Reference Requests tracker appears below it.
Token — the Configuration tab shows the connected ("API token is configured") state.
Connection — after Step 6, UserEvidence confirms they can authenticate and write a test record.
Writeback — set a test UE Advocacy record to Completed (with a Reference ID + Advocate Email + its Opportunity link); confirm the Opportunity's writeback fields populate and the request shows in the tracker.
Reports — open a report in the UE Advocacy folder and the dashboard; confirm they render.
(Referral) submit a test referral, convert the Lead, and confirm the referral fields copied to the Opportunity.

Moving from sandbox to production

Installing the package carries the components (objects, fields, Apex, components, reports), but not your per-org configuration. After installing in production, redo the config there:

Redo in production	Step
Install the same version (prod host)	3
Assign permission sets	4.1
Add components + reference fields to the Opportunity page/layout	4.2–4.3
Enter the production API token (the sandbox token does not carry over)	4.4
Re-do Field Selection (or move it via change set)	4.5
Set up the ECA connection + Run-As user, and send your production My Domain	4.6
Add UE Advocate Status to the Contact layout / automation	4.7
Re-do the Advocates tab criteria (or move it via change set)	4.7
(Referral) referral fields + Lead Source value + Lead-field mapping	4.8

A change set or metadata deploy can carry the layout, Lightning page, field, and Field Selection config from sandbox to prod. Permission-set assignments, the API token, and the ECA connection must still be done directly in production. Test data does not migrate.

7. Troubleshooting

Symptom	Likely cause / fix
Can't see the UE Advocacy tab/app	Permission set not assigned (Step 4.1), or the app is not visible to the profile.
Configuration tab not visible	It is intentionally limited to UE Advocacy Admin.
UserEvidence says they can't connect	Step 6c — is Enable Client Credentials Flow ticked and Run As filled in?
Connected, but no records appear	Step 6b — is UE Advocacy Integration assigned to the Run-As user?
Records appear, but Opportunities don't update	Step 6b — does the Run-As user have Read + View All Records on Opportunity? Read on its own is not enough when Opportunity sharing is Private.
Reference requests don't show in the tracker	The reference is not linked to its Opportunity. Most often Step 6b: without View All Records on Opportunity the link is dropped as the record is written. Otherwise UserEvidence is not sending the Opportunity id (coordinate with your CSM).
Advocate contacts aren't syncing	Step 7 — check the Advocates tab. If nothing is selected there, is UE Advocate Status set to Should Be Advocate? If fields are selected, do those contacts actually match them?
Connection stopped working suddenly	Is the Run-As user still Active? Deactivating it breaks the connection.
Referral attribution blank after conversion	Step 8 — the Map Lead Fields step was not configured, or the `Advocate Referral` Lead Source value is missing.

8. Support

Setup, access, page layout, or configuration questions: your Salesforce admin (this guide).
Advocate/reference progress, tokens, or connection confirmation: your UserEvidence CSM.
How your team uses the tool day to day: see the companion Manage Package User Guide.

Appendix — Reference stages

References move through a fixed, linear set of stages. Match these strings exactly in reports and automation:

Requested → Awaiting Advocate → Awaiting Prospect → Booked → Completed, plus Cancelled (terminal). Do not rely on any other status values.

Appendix — Key fields for reporting

On the Opportunity (written back by the package):

Field	API name	Meaning
UE Advocacy Reference ID	`UE_Advocacy_ReferenceID__c`	Set when a reference completes for this Opportunity.
Reference Completed By	`Reference_Completed_By__c`	Advocate who completed the reference (name, else email).
UE Advocacy Reference Status	`UE_Advocacy_ReferenceStatus__c`	Mirrors the reference's current stage.
Reference Received Date	`Reference_Received_Date__c`	When the reference completed.

On Contact (for the advocate sync): UE Advocate Status (UE_Advocate_Status__c) and UE FanUser UUID (UE_FanUser_Uuid__c).

Never rename an existing field API name. The sync depends on the exact strings and will break if they change.

UserEvidence Advocacy — Salesforce Admin Setup Guide