Connect Salesforce

Pipemetry connects to Salesforce with the Client Credentials OAuth flow and reads Opportunities, their field history, and owners. It never writes back — the Salesforce client has read operations only.

The same walkthrough is built into the app, with copy-to-clipboard values, under Onboarding → Salesforce.

What Pipemetry needs from you

Three values:

Value	Where it comes from
Login URL	Your org’s My Domain URL for the Client Credentials flow
Consumer Key	Your External Client App / Connected App — this is the client_id
Consumer Secret	The same app — this is the client_secret

Step 1 — Pick your Salesforce environment

Decide whether you are connecting Production or a Sandbox, then find your My Domain login URL under Setup → My Domain. It looks like https://your-domain.my.salesforce.com (a sandbox looks like https://your-domain--sandbox.sandbox.my.salesforce.com).

Use My Domain for Client Credentials

The Client Credentials flow is enabled per-app on your My Domain, so the generic https://login.salesforce.com / https://test.salesforce.com hosts often cannot issue Client Credentials tokens. Those generic URLs are only a safe default for the username + password flow.

Using the wrong login server is the single most common reason a connection fails.

Step 2 — Create an External Client App

As of the Spring ‘26 release Salesforce restricts creating new Connected Apps and recommends External Client Apps instead. Use an External Client App unless your org still relies on a legacy Connected App.

1. Gear icon → Setup.
2. Quick Find → type App → App Manager.
3. New External Client App.
4. Name it (for example Pipemetry Integration), let the API Name auto-fill, add your contact email, and leave Distribution State as Local.
5. Expand API (Enable OAuth Settings) and turn on Enable OAuth.
6. Callback URL: paste https://login.salesforce.com/services/oauth2/callback. Client Credentials never redirects a browser — the field just has to be present and valid.
7. Selected OAuth Scopes: add Manage user data via APIs (api). Perform requests at any time (refresh_token, offline_access) is harmless but not required.
8. Create, then wait 2–10 minutes for the app to propagate.
9. Enable the flow on the saved app: Quick Find → External → External Client Apps Manager → your app → Edit Settings → expand OAuth Settings → check Enable Client Credentials Flow → accept the warning → Save.

Legacy Connected App

If you are extending an existing Connected App: Setup → App Manager → New Connected App, then Enable OAuth Settings with the same callback URL and scopes. On that screen the Client Credentials toggle lives under Flow Enablement. The field names match; only the create button, where the toggle lives, and the later Run-As location differ.

Step 3 — Set the Run-As (integration) user

Pipemetry sees exactly what this one user can see. If the Run-As user cannot see every Opportunity, your numbers will be incomplete.

• Recommended: a dedicated user on the Salesforce Integration user license with the Minimum Access – API Only Integrations profile. These licences are included free in Enterprise, Unlimited, Performance and Developer editions and exist for exactly this.
• Alternative: a regular user with the API Only User permission who can see every Opportunity.

For an External Client App: Setup → Quick Find External → External Client Apps Manager → your app → Edit Settings → OAuth Settings → in the Client Credentials Flow area set Run As to the integration user → Save. (The exact in-product label can vary slightly by release.)

For a legacy Connected App: Setup → App Manager → your app → Manage → Edit Policies → under the OAuth Policies “Client Credentials Flow” section, set Run As → Save.

Step 4 — Grant data access with a permission set

1. Setup → Quick Find Permission → Permission Sets → New.
2. Name it (for example Pipemetry Read Access). If your Run-As user is on the Salesforce Integration licence, set the Permission Set License to Salesforce API Integration so it can be assigned.
3. System Permissions → enable API Enabled.
4. Object Settings → Opportunity → grant Read and enable View All, so the user sees every Opportunity regardless of owner or sharing rules.
5. Object Settings → Opportunity Field History (OpportunityFieldHistory) → grant Read.
6. Field-level Read on: Amount, Stage, Close Date, Forecast Category (API names Amount, StageName, CloseDate, ForecastCategory).
7. Save → Manage Assignments → Add Assignment → your Run-As user.

Pipemetry’s Verify step probes these five Opportunity fields:

Amount, CloseDate, CreatedDate, OwnerId, StageName

CreatedDate and OwnerId are Salesforce system fields with no field-level-security toggle — they become readable automatically once the Opportunity object is readable, so there is nothing to configure for them.

Step 5 — Turn on Opportunity Field History Tracking

This is recommended, not required. Pipemetry forecasts from your current pipeline immediately; field history is what makes point-in-time reconstruction accurate — “what was this deal’s amount, stage and close date on day N” — and it powers the trend and waterfall views.

1. Setup → Object Manager → Opportunity → Fields & Relationships.
2. Set History Tracking.
3. Check Enable Opportunity Field History, then select Amount, Stage, Close Date (add Owner if you forecast by owner). Save.

History is forward-only

Enabling tracking does not historise past changes. Immediately afterwards Pipemetry’s field mapping audit will still show Amount / Stage / Close Date as “Current only”, because there are zero history rows yet. That is expected, and the mapping still activates on current values.

To move a field from Current only to History tracked: change at least one deal’s Amount, Stage or Close Date (or let normal rep activity do it), then come back to Onboarding and re-run the backfill. The audit re-reads OpportunityFieldHistory, and your point-in-time views become accurate from that point on.

Two limits worth knowing: Salesforce tracks up to 20 fields per object, and without the OpportunityFieldHistory object read from step 4 Pipemetry sees zero history rows even when tracking is on.

Forecasting by Segment is optional: check the Opportunity field you want to use, grant the integration user Read on it, and map it on the Field Mapping step. Segment never blocks activation.

Step 6 — Enable Change Data Capture

This is what powers live streaming. Without it Pipemetry can read your data but will not receive real-time updates as deals change.

1. Setup → Quick Find Change Data Capture → Change Data Capture.
2. Find Opportunity in Available Entities and move it to Selected Entities.
3. Save. Salesforce creates the OpportunityChangeEvent channel that Pipemetry subscribes to.

There is no “start streaming” action inside Pipemetry — once the connection is verified and CDC is enabled here, the consumer subscribes automatically.

Why Verify says “unverified” for CDC

CDC cannot be confirmed over the Salesforce REST API, so Pipemetry’s connection test can only advise: it reports cdc_status as unverified. Seeing that is normal and does not mean CDC is broken. Saving this screen is the real confirmation.

Step 7 — Copy your credentials into Pipemetry

External Client App: Setup → External Client Apps Manager → your app → Settings tab → under OAuth Settings → Consumer Key and Secret.

Legacy Connected App: Setup → App Manager → your app → dropdown → View → Manage Consumer Details (you may be asked to verify your identity).

Then, in Pipemetry:

1. Paste the login URL from step 1, the Consumer Key (client_id) and the Consumer Secret (client_secret).
2. Leave Auth Mode as Client Credentials. Save.
3. Click Verify — it checks Opportunity read access, the required fields, history access, and advises on CDC.
4. Click Run Backfill to pull your existing Opportunities and field-history events. After that, live changes stream in via CDC.

Treat the Consumer Secret like a password: anyone with both values can pull your data. Pipemetry stores it encrypted and never returns it — secret fields are always blank when you reopen the form.

If Verify fails

Re-check step 4 (the permission set and field access) and step 3 (Run-As user visibility). Those are the usual causes. The Verify result lists exactly which object or field was unreadable.

Salesforce reference

• Client Credentials flow setup
• Configure the Client Credentials flow for External Client Apps
• Integration user licences
• Select objects for Change Data Capture
• Track field history for standard objects