> 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/configuration-guide/notifications/issues.md).

# Issues

Configure issue-level notification rules to alert your team when new problems appear or existing issues escalate.

Issue-level notifications are the **recommended notification pattern for production environments**. Because Pharos groups identical errors into a single Issue via fingerprinting, alerting at the issue level gives you one notification per problem instead of one per occurrence—avoiding spam while keeping your team informed.

{% hint style="info" %}
For the conceptual overview of issue-level alerts, see [Issue-level Alerts](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts.md).
{% endhint %}

Issue notification rules are configured in **Pharos Admin → Notifications → Issues**. The Issues tab supports both **Create** and **Update** rule types, selectable via the Rule Type dropdown.

![Issues tab — create rules list showing configured rules with active status](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-7efdea3753e109d8fc5e983976c827323370f5a2%2Fnotifications-issues-tab.png?alt=media)

***

## Why Issue-Level Notifications?

Issue-level rules fire once per problem rather than once per occurrence: if the same flow fails 10 times in an hour, you get 1 notification instead of 10. That makes them the right default for production monitoring and triage, and it's why they don't need the routine deactivation that log-level rules do.

For the full comparison of the two levels, see [Issue-level Alerts](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts.md#log-level-vs-issue-level-notifications).

***

## Create Rules

Create rules fire when a **new issue is created**—the first time Pharos encounters a unique error. This is the most common rule type.

### When to Use

* You want immediate notification when a new problem appears
* You need different teams notified based on error type or functional area
* You want a catch-all "tell me about every new problem" rule

### Configuration

{% stepper %}
{% step %}

### Name and type

1. Navigate to **Pharos Admin → Notifications → Issues**
2. Click **Add New Rule**
3. Enter a descriptive name (e.g., "All new issues to #prod-errors")
4. Set **Rule type** to **Create**
   {% endstep %}

{% step %}

### Filter criteria (optional)

Leave empty for a catch-all rule, or add filters:

* **Category** — Filter by error category (e.g., Flow, Apex, Bulk API)
* **Functional Area** — Route by business area (e.g., Sales, Service)
* **Priority** — Lowest, Low, Medium, High, or Highest
* **Summary** — Match specific error messages using "contains"

For the full list of filter fields and operators, see [Create-based Triggering](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts/create-based-triggering.md).
{% endstep %}

{% step %}

### Notification action

1. Click **Add New** under Notifications
2. Select channel (Slack, Teams, PagerDuty, Email, or Webhook)
3. Subject and the message body prefill with the Issues default template — see [Default Templates](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md#issues-tab)
4. Adjust the text if you need extra fields. For single-org setups, remove `{!pharos__Issue__c.pharos__Organization_Name__c}` from the subject
5. Click **Add**, then **Save**
   {% endstep %}
   {% endstepper %}

### Message Templates for Create Rules

Notification templates for issue rules reference the **Issue object**. Use the **Insert Field** button to browse Issue fields when building your template.

Fields like Log Count, Frequency, and Impacted Users are not meaningful on brand-new issues (they start at 1, 0, 1). Stick with:

* **Subject:** the [Issues tab default](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md#issues-tab) — category, organization, and summary
* **Body:** Link, Functional Area, Type (optionally Description—but keep it short for Slack)

→ See [Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) for detailed template configuration and channel-specific formatting tips

***

## Update Rules

Update rules fire when an **existing issue is updated** due to new error occurrences. They are used for escalation—notifying your team when a problem gets worse.

### When to Use

* You want to know when an issue becomes "hot" (increasing occurrences)
* You need alerts when user impact grows beyond a threshold
* You're monitoring for issues that cross specific severity thresholds

### Available Filter Fields

Update rules give access to fields that evolve over time:

| Field                  | What It Tracks                   | Example Use                                                  |
| ---------------------- | -------------------------------- | ------------------------------------------------------------ |
| **Log Count**          | Total error occurrences          | Notify when count > 20                                       |
| **Impacted Users**     | Number of unique users affected  | Notify when users > 10                                       |
| **Frequency**          | Average days between occurrences | Notify when frequency < 7 (more than once per week)          |
| **Daily Volume**       | Occurrences per day              | Notify on volume spikes                                      |
| **Last Occurred Date** | Most recent occurrence           | Monitor recency                                              |
| **Status**             | Issue lifecycle status           | Notify on regressions (status changes from Completed to New) |

Update rules use **old value** and **new value** comparisons (similar to `PRIORVALUE()` and `ISCHANGED()` in record-triggered flows). For example, "Log Count (New) > 20" means: when the count *becomes* 20 or more, the rule fires. Each filter row includes a **New/Old** toggle to select which value to compare.

![Update rule filter criteria — New/Old toggle for comparing current and previous field values](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-66397e4647071abeed0502e06de75b0f0516b371%2Fnotification-update-filters.png?alt=media)

{% hint style="info" %}
For the complete list of update trigger fields and operators, see [Update-based Triggering](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts/update-based-triggering.md).
{% endhint %}

### Configuration

The Update rule form is similar to the Create rule form but includes the **New/Old** toggle on filter criteria:

![Notification Rule (Update) form — Rule Details, Filter Criteria with New/Old toggle, and Notification Actions](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-dab87bddaa663ecc0c072d9227db597f7fb3fe5b%2Fnotification-rule-update.png?alt=media)

{% stepper %}
{% step %}

### Name and type

1. Navigate to **Pharos Admin → Notifications → Issues**
2. Click **Add New Rule**
3. Enter a descriptive name (e.g., "Hot issue: 20+ occurrences")
4. Set **Rule type** to **Update**
   {% endstep %}

{% step %}

### Filter criteria

Add threshold-based filters:

* **Log Count** (New) >= 20 — Issue crosses 20 occurrences
* **Impacted Users** (New) > 10 — Issue affects more than 10 users
* **Frequency** (New) < 7 — Issue occurs more than once per week
  {% endstep %}

{% step %}

### Notification action

1. Click **Add New** under Notifications
2. Select channel
3. For update rules, include evolving fields in the **Body**: Log Count, Frequency, Impacted Users, First Occurred Date, Last Occurred Date
4. Click **Add**, then **Save**
   {% endstep %}
   {% endstepper %}

### Update Rules Fire Once Per Issue

Update rules fire **at most once per issue**. Once an update rule has matched an issue, it will not fire again for that same issue, even if the condition is still met.

**Example:**

* Rule: Log Count > 20 → Slack #hot-issues
* Issue grows from 18 → 21 occurrences: **Notification sent**
* Issue grows from 21 → 50 → 100: **No further notifications** (already fired)

### Message Templates for Update Rules

For update rules, include fields that evolve over time in the message body: Log Count, Frequency, Impacted Users, First Occurred Date, Last Occurred Date. These fields are meaningful on updated issues because they reflect the issue's growth.

### Tiered Notifications (Laddering)

To notify at multiple thresholds, create separate rules with non-overlapping filters. Order them from most critical to least critical using the **arrow controls** in the rules list:

| Rule   | Filter                 | Channel          |
| ------ | ---------------------- | ---------------- |
| Rule 1 | Log Count (New) >= 100 | #critical-issues |
| Rule 2 | Log Count (New) >= 50  | #hot-issues      |
| Rule 3 | Log Count (New) >= 20  | #prod-errors     |

Over time, an issue that grows past multiple thresholds will trigger each rule as it crosses that threshold—a notification at 20, then at 50, then at 100.

![Update rules list with reorder arrows — functional area routing with specific rules ordered by priority](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-518e074ec6ddf2160da9871020a249d6371f5b01%2Fnotifications-issues-update-rules.png?alt=media)

### Regression Detection

You can detect issues that were marked resolved but reappear:

* **Filter:** Status (Old) = "Completed" AND Status (New) = "New"
* **Action:** Notify the team that a previously resolved issue has regressed

***

## Functional Area Routing

Route notifications to the right team based on error characteristics:

| Rule   | Type   | Filter                             | Channel        |
| ------ | ------ | ---------------------------------- | -------------- |
| Rule 1 | Create | Category = "Flow"                  | #flow-errors   |
| Rule 2 | Create | Functional Area contains "Sales"   | #sales-team    |
| Rule 3 | Create | Functional Area contains "Service" | #service-team  |
| Rule 4 | Create | Catch-all (no filters)             | #platform-team |

{% hint style="warning" %}
**Rule order matters.** Place specific rules at the top and the catch-all at the bottom. Evaluation stops at the first match—if the catch-all is first, it matches everything and no other rule fires.
{% endhint %}

***

## Recommended Starting Setup

From customer training sessions, a common starting point:

{% stepper %}
{% step %}

### Create rule (catch-all)

All new issues → Slack #production-errors

* No filters, one Slack action
* Gives you awareness of every new problem
  {% endstep %}

{% step %}

### Update rule (hot issues)

Log Count > 20 → Slack #production-errors (or a dedicated #hot-issues channel)

* Fires once when an issue crosses the threshold
* Alerts on problems that are growing
  {% endstep %}

{% step %}

### Refine over time

Run this for 1–2 weeks, then:

* Add category or functional area filters to route to specific teams
* Add more update rules at different thresholds (50, 100)
* Adjust channels as team preferences emerge
  {% endstep %}
  {% endstepper %}

→ [Learn more: Alerting Use Cases](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/alerting-use-cases.md)

***

## Best Practices

1. **Start with issue-level, not log-level.** Issue notifications give you one alert per problem. Add log-level rules only for specific, low-volume scenarios.
2. **Use a catch-all create rule as your safety net.** Even if you add specific routing rules, keep a catch-all at the bottom to ensure nothing slips through.
3. **Add update rules sparingly.** Only add them for escalation scenarios you will act on. Too many thresholds create noise.
4. **Keep Slack messages concise.** Include the summary and a link—readers can click through for full details. Avoid including the full error description in the message body.
5. **Use custom fields for advanced filtering.** If your filter criteria are complex (15+ conditions), create a formula field (e.g., "Is Business Critical") and use that in your rule criteria.
6. **Deactivate rules you're not using.** Unused active rules still consume evaluation cycles. Deactivate seasonal or temporary rules when they're not needed.

***

## Troubleshooting

| Issue                       | Cause                                                        | Resolution                                                                                                                                                                                      |
| --------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Notifications not appearing | Rule not matching or integration disconnected                | Verify filter criteria; check [Slack](https://docs.pharos.ai/configuration-guide/integrations/slack.md) or [Teams](https://docs.pharos.ai/configuration-guide/integrations/teams.md) connection |
| Wrong rule firing           | Catch-all above specific rules                               | Reorder rules: specific at top, catch-all at bottom                                                                                                                                             |
| Update rule never fires     | Threshold never crossed or rule already fired for that issue | Verify threshold is reachable; remember update rules fire once per issue                                                                                                                        |
| Too many notifications      | Overly broad filters or too many catch-all rules             | Tighten filters; consider fewer, more specific rules                                                                                                                                            |

***

{% hint style="info" %}
**Related:** [Log Notifications](https://docs.pharos.ai/configuration-guide/notifications/logs.md) — Individual error occurrence alerts · [Trace Result Notifications](https://docs.pharos.ai/configuration-guide/notifications/trace-results.md) — Debug log capture alerts · [Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) — Channel configuration · [Order of Execution](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/order-of-execution.md) — Rule ordering
{% endhint %}
