Skip to content
  • There are no suggestions because the search field is empty.

Integrating Salesforce Data with Cascade: Bridging CRM and Execution

Sync Key Metrics into Cascade

This guide explains how to securely pull data from Salesforce (CRM) and sync it into Cascade as Measures (single aggregate values) or Metrics (time-series datapoints).

Integration methods

Method 1: Salesforce Reports (recommended for single aggregate KPIs)

Use this when you want one number (ex: pipeline $, # of won deals, # of new leads) to update a Cascade Measure.

How it works

  • You build a Salesforce Report that calculates the KPI (sum/count/avg).
  • Cascade calls the Salesforce Reports API to run the report and read the primary summary value.
  • That value is used to update the mapped Cascade Measure.

Best practice

  • Create a dedicated “Cascade – KPI Reports” folder in Salesforce, so report IDs don’t change and access is easy to control.

Method 2: SOQL Query (recommended for detailed or time-series data)

Use this when you need:

  • Multiple fields (ex: Opportunity amount + stage + close date)
  • Multiple records (ex: all open opportunities)
  • Time-series datapoints to update Cascade Metrics (date + value)

How it works

  • Cascade executes a customer-provided SOQL query via the Salesforce REST API Query resource.
  • Salesforce returns records (with pagination if needed).
  • Cascade transforms the results into Measure updates or Metric datapoints.

1) Authentication setup (required)

Salesforce integrations require an OAuth-enabled Connected App. The Connected App generates the credentials needed for Cascade to authenticate to Salesforce.

Option A — JWT Bearer (recommended for server-to-server integrations)

This is the most common approach for scheduled integrations (no human login required once set up). Salesforce supports a JWT bearer flow for server-to-server access.

Refer to the following link to Create a Connected App for Oauth:

https://help.salesforce.com/s/articleView?id=platform.ev_relay_create_connected_app.htm&type=5

Refer to the following link to Enable OAuth settings for API integration

https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create_api_integration.htm&type=5

Customer steps (Salesforce Admin)

  1. In Salesforce Setup, go to App Manager → New Connected App.
  2. Enable OAuth Settings and configure required scopes (typically includes API access).
  3. Enable issuing JWT-based access tokens for a named integration user.
  4. Create (or choose) an Integration User in Salesforce and grant:
    • API access (“API Enabled”)
    • Read access to required objects/fields (Opportunities, Accounts, custom objects, etc.)
    • Access to required Reports/Folders (if using Method 1)

What the customer provides to Cascade

  • Salesforce Login URL (Production or Sandbox)
  • Consumer Key (Client ID)
  • Integration user identifier (as required by your internal setup)
  • Confirmation of permissions granted (objects/fields/reports)

Option B — Authorization Code + Refresh Token (if your security team prefers interactive approval)

This option requires an initial admin/user consent step, then scheduled syncs use the refresh token.

Customer steps

  • Create a Connected App with OAuth enabled
  • Complete one-time authorization with the integration user
  • Ensure the integration user has the same permissions listed above

What the customer provides

  • Consumer Key / Consumer Secret
  • Login URL (Production or Sandbox)
  • Confirmation the integration user can access the required data

2) Pulling Data from Salesforce

Method 1 setup: Salesforce Reports to Cascade Measures

Customer steps

  1. Build a Salesforce Report that returns your KPI.
  2. Ensure the report includes a summary value (ex: SUM(Amount), Row Count).
  3. (Recommended) Add a date filter such as “This Month”, “Last 90 Days”, etc. to control what the KPI represents.
  4. Copy the Report ID – the Report ID is visible in the report URL in Salesforce.

How Cascade pulls the value

Salesforce provides a Reports & Dashboards REST API that allows running a report and retrieving results.

What the customer provides to Cascade

  • Report URL (this will include the Report ID)

Method 2 setup: SOQL Query to Cascade Measures or Metrics

Provide a SOQL query that returns the fields needed. (This query will be used in the REST API URL)

Salesforce Query API Syntax:

  • GET /services/data/vXX.X/query?q=<SOQL>

Best Practices

  • Include a WHERE clause based on a stable field like LastModifiedDate or a business date (CloseDate, CreatedDate), this keeps syncs fast and predictable.
  • Add a custom field in Salesforce like “Cascade ID” and store the ID on the Salesforce record, Cascade will use this ID for reliable matching

Note: Cascade will run the report/query as provided. If you want “last 30 days” or “only recently changed records,” that logic must be defined in Salesforce (report filters) or in the SOQL query itself.

3) Data mapping into Cascade

If updating a Cascade Measure (single value)

Your Report or SOQL logic should produce one numeric value that becomes the Measure’s progress/completion.

If updating a Cascade Metric (time-series datapoints)

Your dataset should include:

  • metric_key (which Cascade Metric to update)
  • metric_date (the datapoint date)
  • metric_value (the numeric value)

4) Common troubleshooting

Authentication errors

  • Connected App OAuth settings missing/incorrect
  • Integration user not authorized for the selected OAuth flow

Permission errors

  • Integration user lacks API Enabled
  • Missing object/field permissions (especially for custom objects/fields)
  • Report folder not shared with the integration user

Data issues

  • KPI field not numeric
  • Report does not include a summary value
  • SOQL returns more data than expected (missing filters / no incremental clause)