> 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.md).

# Notifications

Configure notification rules and channels to alert your team about errors, issues, and trace results.

Pharos notification rules deliver context-rich alerts to Slack, Teams, PagerDuty, Email, or Webhooks when issues, logs, or trace results match your criteria. Rules follow a **filter-then-action** pattern: when a record matches the filter criteria, the notification action runs.

Notification rules exist at three levels—**Issues**, **Logs**, and **Trace Results**—each corresponding to a tab in Pharos Admin. Most teams start with issue-level rules for production and add log or trace result rules for specific workflows.

{% hint style="info" %}
For alerting concepts, routing strategies, and best practices, see [Alerting](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting.md).
{% endhint %}

***

## Accessing Notification Rules

1. Open the **Pharos** app
2. Navigate to **Pharos Admin**
3. Select **Notifications** from the left-hand menu
4. Choose the appropriate tab:

| Tab               | What It Monitors                            | Typical Use                                          |
| ----------------- | ------------------------------------------- | ---------------------------------------------------- |
| **Issues**        | Grouped errors (recommended for production) | New problems, escalation thresholds                  |
| **Logs**          | Individual error occurrences                | Sandbox development, critical transaction monitoring |
| **Trace Results** | Debug log captures from tracing             | Awareness when a trace schedule captures a result    |

Each tab shows a list of configured rules with their name, description, filter criteria, notification actions, creator, and active status.

![Notification Rules page — Issues tab showing create rules with active status and rule details](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)

***

## Prerequisites

Before configuring notification rules:

| Requirement               | Details                                                                                                                                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration connected** | At least one channel (Slack, Teams, or PagerDuty) configured in [Integrations](https://docs.pharos.ai/configuration-guide/integrations.md). Email uses Salesforce's built-in delivery and does not require integration setup. |
| **Channel created**       | For Slack/Teams: create the channel and invite the app (or add users)                                                                                                                                                         |
| **Webhook endpoint**      | For Webhook actions: a reachable HTTP endpoint URL                                                                                                                                                                            |
| **Admin access**          | System Administrator or equivalent in Salesforce                                                                                                                                                                              |

***

## Anatomy of a Notification Rule

All notification rules—regardless of level—share the same structure. Once you understand how to build one rule, the others follow the same pattern.

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

Every rule has three sections:

### Rule Details

* **Rule Name** (required) — A descriptive name (e.g., "All new issues to #prod-errors" or "Hot issue: 20+ occurrences")
* **Description** (required) — Explain what the rule does and why it exists, for team reference

### Filter Criteria

Filters determine **which records** trigger the rule. Filter criteria work like Salesforce list views—you can select any field on the relevant object, choose an operator, and specify a value.

* **Create rules:** Filters are optional. Leave filters empty for a catch-all that matches every new record.
* **Update rules:** Filters are essential. Define the threshold or condition that triggers the notification.

Trace Results rules filter on **Issue** fields — the criteria apply to the Issue the trace result belongs to.

Filters support **AND/OR logic** and **parentheses** for complex conditions. By default, all conditions must be satisfied (AND). Use the **Filter logic** option to switch to OR or mixed logic.

{% hint style="info" %}
If your filter criteria become very complex (15+ conditions), consider creating a formula field on the object (e.g., a Boolean "Is Business Critical" field) and using that single field in your criteria instead.
{% endhint %}

### Notification Actions

Actions define **where and how** the notification is sent. Each rule can have one or more notification actions:

* Click **Add New** to create a new action
* Click **Add Existing** to reuse a previously created action template
* Supported types: **Slack**, **Teams**, **Email**, **PagerDuty**, and **Webhook**
* Multiple actions of the same type are supported (e.g., two Slack actions to different channels)

→ [Learn more: Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) — Detailed configuration for each action type

***

## Creating a Notification Rule

{% stepper %}
{% step %}

### Choose tab and rule type

1. Navigate to **Pharos Admin → Notifications**
2. Select the tab: **Issues**, **Logs**, or **Trace Results**
3. Click **Add New Rule**
4. By default, the rule opens as a **Create** rule. To create an update rule, use the **Rule Type** dropdown at the top

The Rule Type dropdown appears at the top of the rules list and also when creating a new rule. **Create** rules fire when a new record is created. **Update** rules fire when an existing record is updated.
{% endstep %}

{% step %}

### Fill in rule details

1. Enter a **Rule Name** — be specific enough that you can identify the rule at a glance in the list
2. Enter a **Description** — explain the intent so other admins understand what the rule does
   {% endstep %}

{% step %}

### Add filter criteria (optional for create rules)

1. Click **Add New** under Filter Criteria
2. Select a **Field** from the dropdown (fields come from the relevant object—Issue, Log, or Trace Result)
3. Choose an **Operator** (equals, not equal, contains, greater than, etc.)
4. Enter a **Value**
5. Repeat to add more conditions. Use **Filter logic** to switch between AND/OR

For update rules, each filter field has a **New/Old** toggle. Use **New** to filter on the current value after the update, and **Old** to compare against the previous value.
{% endstep %}

{% step %}

### Add notification actions

1. Click **Add New** under Notifications
2. Select the action type from the **Send notification to** dropdown
3. Configure the channel-specific fields (subject, body, channel, etc.)
4. Click **Add**
5. Repeat to add more actions if needed

→ See [Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) for detailed configuration of each type
{% endstep %}

{% step %}

### Save

Click **Save** in the top right. The rule is active immediately.
{% endstep %}
{% endstepper %}

***

## Managing Rules

### Viewing Inactive Rules

By default, the rules list shows only **active** rules. To see all rules including inactive ones, toggle the **Show Inactive** switch above the rules table.

### Activating and Deactivating Rules

Each rule in the list has an **Active** toggle. Click it to activate or deactivate a rule:

* **Active (blue toggle):** The rule is evaluated when records are created or updated
* **Inactive (grey toggle):** The rule is skipped during evaluation

Common reasons to deactivate:

* Temporary rules used during development or deployment windows
* Rules from a sandbox refresh that target production channels
* Seasonal rules that only apply during peak periods
* Rules being debugged or updated

### Editing and Deleting Rules

* Click the **pencil icon** to edit an existing rule
* Click the **trash icon** to permanently delete a rule

### Rule Type Filter

The rules list includes a **Rule Type** dropdown (Create / Update) to filter the view. Use this to see only create rules or only update rules.

***

## Execution Order and Reordering Rules

Notification rules are evaluated **top to bottom** and **stop at the first match**—like Salesforce lead assignment rules.

* **First matching rule** sends the notification and evaluation stops
* **Subsequent rules** are not evaluated for that record

**Ordering principle:** Put **most specific rules at the top**, **catch-all rules at the bottom**.

| Position | Rule Type              | Example                                   |
| -------- | ---------------------- | ----------------------------------------- |
| Top      | Specific filters       | Functional Area = "Sales" → #sales-errors |
| Middle   | Broader filters        | Category = "Flow" → #flow-errors          |
| Bottom   | Catch-all (no filters) | All issues → #prod-errors                 |

### Reordering Rules

Use the **up/down arrow controls** on the right side of each rule row to change its position in the evaluation order. Arrow controls appear between the active toggle and the edit/delete icons.

![Update rules list showing arrow controls for reordering — specific rules at top, broader rules at bottom](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)

{% hint style="warning" %}
If a catch-all rule (no filters) is at the top of the list, it will match every record and prevent any rule below it from ever firing. Always move catch-all rules to the bottom.
{% endhint %}

→ [Learn more: Order of Execution](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/order-of-execution.md)

***

## Message Templates

You can customize the **Subject** and **Body** of each notification action using merge fields:

* Use the **Insert Field** button to browse and insert fields from the relevant object
* Merge fields use `{!Object.Field_API_Name__c}` syntax
* The available fields depend on the notification tab: Issue fields for issue rules, Log fields for log rules, Trace Result fields for trace result rules
* Trace result templates can also reach the related Issue: `{!pharos__Trace_Result__c.pharos__Issue__r.pharos__Summary__c}` pulls an Issue field, and `{!pharos__Trace_Result__c.pharos__Issue__c.Link}` renders a link to the Issue record itself. The picker offers a **Link** entry for the trace result only — the Issue link has to be typed

**For create rules:** Fields like Log Count, Frequency, and Impacted Users are not meaningful on brand-new records. The default template (summary, category, link) is usually sufficient.

**For update rules:** Include evolving fields in the body—Log Count, Frequency, Impacted Users, First Occurred Date, Last Occurred Date.

{% hint style="warning" %}
**Keep messages short for Slack.** Slack displays full message content without truncation, so long messages (especially with full descriptions or stack traces) clutter the channel. Include the summary and a link—readers can click through for details. Teams is more forgiving because it truncates long messages with an expand option.
{% endhint %}

→ [Learn more: Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) — Message template details and channel-specific formatting tips

***

## Sandbox and Environment Separation

* **Production:** Configure notification rules to send to production channels (e.g., #prod-errors)
* **Sandbox:** Many orgs do not send notifications from sandbox to avoid noise in production channels. If you do, use separate channels (e.g., #sandbox-errors)

When refreshing a sandbox from production, notification rules are typically deactivated to prevent sandbox errors from posting to production channels. Re-enable and adjust channel targets after refresh.

***

## In This Section

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🎯 Issue Notifications</strong></td><td>The recommended notification pattern for production—alert on grouped errors with create and update rules.</td><td><a href="https://docs.pharos.ai/configuration-guide/notifications/issues.md">Issues</a></td></tr><tr><td><strong>📄 Log Notifications</strong></td><td>Individual error occurrence alerts for sandbox development and critical transaction monitoring.</td><td><a href="https://docs.pharos.ai/configuration-guide/notifications/logs.md">Logs</a></td></tr><tr><td><strong>📊 Trace Result Notifications</strong></td><td>Get notified when Pharos captures a debug log from a trace schedule.</td><td><a href="https://docs.pharos.ai/configuration-guide/notifications/trace-results.md">Trace Results</a></td></tr><tr><td><strong>🎬 Notification Actions</strong></td><td>Configure Slack, Teams, Email, PagerDuty, and Webhook notification actions—message templates, channels, and formatting.</td><td><a href="https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md">Notification Actions</a></td></tr></tbody></table>

***

{% hint style="info" %}
**Related:** [Integrations](https://docs.pharos.ai/configuration-guide/integrations.md) — Slack, Teams, PagerDuty setup · [Notification Channels](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels.md) — Channel capabilities · [Ticketing Rules](https://docs.pharos.ai/configuration-guide/ticketing/rules.md) — Jira/Azure ticket creation · [Notification Charts](https://docs.pharos.ai/configuration-guide/advanced/notification-charts.md) — Embed charts in notifications
{% endhint %}
