> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts/update-based-triggering.md).

# Update-based Triggering

Learn about update-based rules and how they execute once per issue for advanced notification strategies.

Update-based notification rules fire when an **existing issue is updated**. These rules are ideal for escalation scenarios where you want to be notified when an issue crosses specific thresholds or becomes "hot."

Under the hood, these are `Rule__c` records with `Type__c = "Notification"` and the `Is_Update__c` checkbox checked—"update-based" describes that triggering mode, not a separate Rule Type value.

## When Update Rules Fire

An update-based rule evaluates when Pharos updates an existing issue record. This happens when:

1. A new log occurrence is added to an existing issue
2. Pharos updates the issue's metrics (log count, frequency, impact statistics, etc.)
3. The updated issue is evaluated against all active update-based notification rules (top to bottom)
4. The first rule with matching filter criteria fires

{% hint style="info" %}
**Fires Once Per Rule**

Each update rule fires **at most once per issue**. Once an update rule has fired for an issue, it will not fire again for that same issue, even if the issue continues to be updated.
{% endhint %}

## What Triggers an Issue Update

When an issue has a new occurrence (a new log is added to it), these fields are automatically updated:

| Field                  | What Changes                                           |
| ---------------------- | ------------------------------------------------------ |
| **Last Occurred Date** | Updates to the timestamp of the most recent occurrence |
| **Log Count**          | Increments by the number of new logs                   |
| **Frequency**          | Recalculated: average days between occurrences         |
| **Daily Volume**       | Recalculated: average occurrences per day              |
| **Impacted Users**     | Updates if new users are affected                      |
| **Impacted Records**   | Updates if new records are involved                    |
| **Impacted Objects**   | Updates if new object types are affected               |

## Use Cases for Update Rules

Update rules shine for escalation—alerting you when an existing issue crosses a threshold you care about.

### 1. Volume Threshold Escalation

**Scenario:** You want to be notified if an issue occurs more than 100 times.

**Rule Configuration:**

```
Rule Type: Notification (Is_Update__c = true)
Filter: Log Count > 100
Action: Post to Slack #escalations
```

**When It Fires:**

* Issue is created with 1 occurrence → No notification (create rule might fire)
* Issue grows to 50 occurrences → No notification (under threshold)
* Issue grows to 101 occurrences → **Update rule fires once**
* Issue grows to 200 occurrences → No additional notification (already fired)

### 2. Frequency-Based Escalation

**Scenario:** You want to know if an issue starts happening more than once per week (frequency drops below 7 days).

**Rule Configuration:**

```
Rule Type: Notification (Is_Update__c = true)
Filter: Frequency < 7
Action: Post to Teams #hot-issues
```

**How Frequency Works:**

* **Frequency** = average days between occurrences
* Lower frequency = more frequent problem
* Frequency of 1 = happens every day
* Frequency of 7 = happens once per week
* Frequency of 30 = happens once per month

### 3. User Impact Escalation

**Scenario:** Alert when an issue starts impacting more than 10 users.

**Rule Configuration:**

```
Rule Type: Notification (Is_Update__c = true)
Filter: Impacted Users Count > 10
Action: Create PagerDuty incident + Slack #critical
```

**When It Fires:**

* Issue created affecting 2 users → No notification
* Issue grows to 8 users → No notification
* Issue grows to 11 users → **Update rule fires once**
* Issue grows to 25 users → No additional notification

### 4. Daily Volume Threshold

**Scenario:** Alert when an issue starts happening more than 10 times per day on average.

**Rule Configuration:**

```
Rule Type: Notification (Is_Update__c = true)
Filter: Daily Volume > 10
Action: Post to Slack #high-volume-issues
```

## Available Filter Criteria

Update rules can filter on any field available on the issue object, including metrics that evolve over time:

**Aggregation Metrics (best for update rules):**

* **Log Count:** Total number of occurrences
* **Frequency:** Average days between occurrences
* **Daily Volume:** Average occurrences per day
* **Impacted Users:** Total unique users affected
* **Impacted Records:** Total unique records involved
* **Impacted Objects:** List of Salesforce objects affected

**Other Fields:**

* **Category:** Type of error
* **Functional Area:** Business process name
* **Priority:** Can be manually updated during triage
* **Status:** Can change from New → Triaged → Actioned → In Progress → In Review → Completed (or Duplicate)
* **Last Occurred Date:** When it last happened

## Combining Create and Update Rules

The most powerful notification strategies combine both create and update rules:

### Example: Comprehensive Escalation Strategy

```
Rule 1 (Create):
  Name: New Critical Issue
  Filter: Priority = "Highest"
  Action: PagerDuty + Slack #urgent

Rule 2 (Update):
  Name: Issue Becoming Critical
  Filter: Log Count > 100
  Action: PagerDuty + Slack #escalations

Rule 3 (Update):
  Name: High User Impact
  Filter: Impacted Users Count > 10
  Action: Slack #escalations

Rule 4 (Update):
  Name: Increasing Frequency
  Filter: Frequency < 7
  Action: Slack #escalations

Rule 5 (Create):
  Name: All New Issues
  Filter: (none - catch all)
  Action: Slack #prod-errors
```

**How This Works:**

1. Every new issue posts to #prod-errors (Rule 5)
2. Critical issues also page on-call team (Rule 1)
3. As issues evolve, update rules catch escalation scenarios:
   * Volume threshold (Rule 2)
   * Growing user impact (Rule 3)
   * Increasing frequency (Rule 4)

## Best Practices

Keep update rules focused so they signal genuine escalation rather than adding noise.

### Use Update Rules Sparingly

**Don't overuse update rules:**

* Start with create rules only
* Add update rules only for specific escalation scenarios
* Too many update rules can create notification fatigue

**Good use:** Notify when issue crosses 100 occurrences **Poor use:** Notify on every 10th occurrence (use reporting/dashboards instead)

### Choose Meaningful Thresholds

Base thresholds on your actual data:

1. **Review your issues for 2-4 weeks**
2. **Identify what "normal" looks like:**
   * What's a typical log count for your environment?
   * What frequency indicates a real problem vs. occasional edge case?
3. **Set thresholds above normal baseline**

**Example:**

* If most issues have 5-20 occurrences, set threshold at 50 or 100
* If typical frequency is 30 days, alert when it drops below 7 days

### Consider One-Time Notification Behavior

Remember: **Update rules fire once per issue maximum.**

**Implications:**

* Good for threshold alerts ("Tell me when it crosses 100")
* Not good for recurring alerts ("Tell me every time it happens")
* If you need recurring notifications, consider log-level rules instead

### Monitor Rule Effectiveness

After implementing update rules:

1. Track how often they fire
2. Are the notifications actionable?
3. Adjust thresholds if too many/too few notifications

## Real-World Example

**Scenario:** E-commerce company wants to stay on top of order processing errors.

**Rule Strategy:**

```
Rule 1 (Create):
  Name: New Order Processing Error
  Filter: Functional Area contains "Order"
  Action: Post to Slack #order-processing

Rule 2 (Update):
  Name: Order Errors Escalating
  Filter: Functional Area contains "Order" 
     AND (Log Count > 50 OR Daily Volume > 5)
  Action: Post to Slack #escalations + PagerDuty

Rule 3 (Update):
  Name: Widespread Order Impact
  Filter: Functional Area contains "Order"
     AND Impacted Users Count > 20
  Action: Page on-call team (critical customer impact)
```

**How It Works:**

1. Every new order error posts to #order-processing (Rule 1)
2. If that error happens 50+ times or 5+ times/day, escalate (Rule 2)
3. If 20+ users are affected, page the on-call team (Rule 3)

## Common Pitfalls

Update rules have a few recurring traps, mostly around thresholds and their fire-once behavior.

### Pitfall 1: Threshold Too Low

```
Bad Rule (Update):
  Filter: Log Count > 2
  Action: Post to Slack
```

**Problem:** Almost every issue hits 2-3 occurrences quickly, creating notification spam.

**Better:**

```
Good Rule (Update):
  Filter: Log Count > 50
  Action: Post to Slack
```

### Pitfall 2: Overlapping Conditions

```
Rule 1 (Update): Log Count > 50 → Slack #escalations
Rule 2 (Update): Log Count > 100 → PagerDuty
```

**Problem:** Rule 2 will never fire because Rule 1 already fired at 50 occurrences.

**Better:**

```
Rule 1 (Update): Log Count > 100 → PagerDuty
Rule 2 (Update): Log Count > 50 AND Log Count <= 100 → Slack #escalations
```

Or use priority instead:

```
Rule 1 (Update): Log Count > 100 AND Priority = "Highest" → PagerDuty
Rule 2 (Update): Log Count > 50 → Slack #escalations
```

### Pitfall 3: Expecting Repeated Notifications

```
Rule (Update): Frequency < 7 → Notify
```

**Misunderstanding:** "This will notify me every week that the issue is happening weekly"

**Reality:** This fires **once** when frequency first drops below 7, then never again for that issue.

## Next Steps

* Review [Create-based Triggering](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts/create-based-triggering.md) for foundational notification patterns
* Explore [Notification Channels](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels.md) for integration setup (Slack, Teams, PagerDuty)
* See [Alerting Use Cases](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/alerting-use-cases.md) for complete notification strategies
