Documentation Plugins Salesforce data source Alerting

Salesforce alerting

The Salesforce data source supports Grafana Alerting, allowing you to create alert rules based on Salesforce data. You can monitor your Salesforce environment and receive notifications when specific conditions are met, such as when opportunity values drop, case counts spike, or tasks become overdue.

Before you begin

• Ensure you have the appropriate permissions to create alert rules in Grafana.
• Verify your Salesforce data source is configured and working correctly.
• Familiarize yourself with Grafana Alerting concepts.

Query requirements for alerting

Alert queries must return numeric data that Grafana can evaluate against a threshold. Use aggregate SOQL functions to return numeric values:

Create an alert rule

To create an alert rule using Salesforce data:

1. Go to Alerting > Alert rules.
2. Click New alert rule.
3. Enter a name for your alert rule.
4. In the Define query and alert condition section:
   • Select your Salesforce data source.
   • Write a SOQL query that returns numeric data.
   • Add a Reduce expression if your query returns multiple series.
   • Add a Threshold expression to define the alert condition.
5. Configure the Set evaluation behavior:
   • Select or create a folder and evaluation group.
   • Set the evaluation interval (how often the alert is checked).
   • Set the pending period (how long the condition must be true before firing).
6. Add labels and annotations to provide context for notifications.
7. Click Save rule.

For detailed instructions, refer to Create a Grafana-managed alert rule.

Example: Open case count alert

This example creates an alert that fires when the number of open high-priority cases exceeds a threshold:

1. Create a new alert rule.

2. Configure the query:

   soql Copy

   SELECT COUNT() FROM Case 
   WHERE IsClosed = false 
     AND Priority = 'High'

3. Add expressions:

   • Reduce: Last value
   • Threshold: Is above 50

4. Set evaluation to run every 5 minutes with a 10-minute pending period.

5. Save the rule.

Example: Opportunity pipeline alert

This example alerts when the total value of opportunities closing this month drops below a target:

1. Create a new alert rule.

2. Configure the query:

   soql Copy

   SELECT SUM(Amount) FROM Opportunity 
   WHERE IsClosed = false 
     AND CloseDate = THIS_MONTH

3. Add expressions:

   • Reduce: Last value
   • Threshold: Is below 1000000

4. Set evaluation to run every hour.

5. Save the rule.

Example: Overdue task alert

This example alerts when there are overdue tasks:

1. Create a new alert rule.

2. Configure the query:

   soql Copy

   SELECT COUNT() FROM Task 
   WHERE IsClosed = false 
     AND ActivityDate < TODAY

3. Add expressions:

   • Reduce: Last value
   • Threshold: Is above 0

4. Set evaluation to run every 15 minutes.

5. Save the rule.

Example: Converted lead count alert

This example alerts when the number of converted leads drops below an acceptable level. The query returns the count of leads converted this week:

1. Create a new alert rule.

2. Configure the query:

   soql Copy

   SELECT COUNT() FROM Lead 
   WHERE IsConverted = true 
     AND ConvertedDate = THIS_WEEK

3. Add expressions:

   • Reduce: Last value
   • Threshold: Is below 10

4. Set evaluation to run daily.

5. Save the rule.

Example: Average deal size alert

This example alerts when the average value of open opportunities in the current quarter falls below a target:

1. Create a new alert rule.

2. Configure the query:

   soql Copy

   SELECT AVG(Amount) FROM Opportunity 
   WHERE IsClosed = false 
     AND CloseDate = THIS_QUARTER

3. Add expressions:

   • Reduce: Last value
   • Threshold: Is below 25000

4. Set evaluation to run every hour.

5. Save the rule.

Example: Rolling time window alert

This example uses the $__timeFrom and $__timeTo macros to alert on cases created within the alert query’s time range, so the window follows the evaluation period instead of a fixed date:

1. Create a new alert rule.

2. Configure the query:

   soql Copy

   SELECT COUNT() FROM Case 
   WHERE CreatedDate >= $__timeFrom 
     AND CreatedDate <= $__timeTo

3. Set the alert query time range to the window you want to monitor, such as now-1h to now.

4. Add expressions:

   • Reduce: Last value
   • Threshold: Is above 100

5. Set evaluation to run every 5 minutes.

6. Save the rule.

For more information about the available macros, refer to Salesforce query editor.

Best practices

Follow these recommendations to create reliable and efficient alerts with Salesforce data.

Use aggregate functions

Always use SOQL aggregate functions (COUNT, SUM, AVG, MIN, MAX) for alert queries. These return numeric values that Grafana can evaluate against thresholds.

Consider API limits

Salesforce has API request limits. Set alert evaluation intervals appropriately to avoid excessive API usage:

• Use longer intervals (5+ minutes) when possible.
• Avoid very short intervals (less than 1 minute) for non-critical alerts.
• Monitor your Salesforce API usage in Setup under System Overview.

Use date literals

SOQL provides date literals that simplify time-based filtering:

• TODAY, YESTERDAY, TOMORROW
• THIS_WEEK, LAST_WEEK, NEXT_WEEK
• THIS_MONTH, LAST_MONTH, NEXT_MONTH
• THIS_QUARTER, LAST_QUARTER, NEXT_QUARTER
• THIS_YEAR, LAST_YEAR, NEXT_YEAR

Use time macros for rolling windows

The Salesforce data source supports the $__timeFrom and $__timeTo macros, which resolve to the start and end of the alert query’s time range. Use them when you want the alert to evaluate a rolling window that follows the evaluation period, rather than a fixed date literal. The $__quarterStart and $__quarterEnd macros resolve to the fiscal quarter derived from your Salesforce fiscal year settings. For more information, refer to Salesforce query editor.

Handle no data conditions

Configure what happens when no data is returned:

1. In the alert rule, find Configure no data and error handling.
2. Choose an appropriate action:
   • No Data: Keep the alert in its current state
   • Alerting: Treat no data as an alert condition
   • OK: Treat no data as a healthy state

Test queries before alerting

Always verify your query returns expected data before creating an alert:

1. Go to Explore.
2. Select your Salesforce data source.
3. Run the query you plan to use for alerting.
4. Confirm the data format and values are correct.

Troubleshoot alerting issues

For common alerting issues with the Salesforce data source, refer to the Troubleshooting guide.

Common issues include:

• Alert not firing: Ensure your query returns numeric data using aggregate functions.
• Evaluation errors: Check that your SOQL syntax is valid and the query executes successfully in Explore.
• Timeouts: The data source doesn’t expose a query timeout setting, so reduce the amount of data the query returns. Add selective WHERE filters or return an aggregate value instead of many rows.

Additional resources

• Grafana Alerting documentation
• Create alert rules
• Configure notifications
• SOQL aggregate functions