> 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/rule-based-configuration.md).

# Rule-based Configuration

Understand Pharos's rule-based configuration model with entry criteria and actions.

Pharos uses a unified rule-based framework to automate responses to different conditions in your Salesforce environment. At its core, a rule is simply a combination of criteria and actions—if certain conditions are met, then specific actions are executed. This declarative approach allows you to build sophisticated automation without writing code.

## The Rule Framework

The rule-based system in Pharos is the foundation for several key capabilities throughout the platform. Whether you're setting up notifications, detecting anomalies, managing data lifecycle, or creating tickets, you're using the same underlying framework. This consistency means that once you understand how rules work, you can apply that knowledge across different features.

The framework operates on a straightforward principle: evaluate conditions, and if they match, execute actions. Think of it as similar to Salesforce Workflow Rules or Process Builder, but specifically designed for observability data with the nuances that log and issue management requires.

### How Rules Work

When a record is created or evaluated—whether it's a new log, a new issue, or a scheduled evaluation—Pharos checks all active rules to see if any should fire. Each rule examines the record against its configured filter criteria. If the criteria match (or if no criteria are specified), the rule executes its configured actions.

This pattern remains consistent across different rule types, though the timing and context may vary. Some rules fire immediately when a record is created, while others run on a scheduled basis. Some evaluate individual records, while others analyze patterns across multiple records over time.

{% hint style="info" %}
**Rule Types in Pharos**

The same rule framework powers different capabilities:

* **Alerting** - Send notifications when logs or issues are created
* **Monitoring** - Detect spikes and anomalies in error patterns
* **Retention** - Automate log archival and cleanup
* **Ticketing** - Create tickets in external bug tracking systems

Each type has unique features, but all share the same core structure.
{% endhint %}

## Core Components

Every rule, regardless of its type, consists of three fundamental elements: identification, criteria, and actions.

### Identification

Each rule needs a name and description that clearly communicates its purpose. The name serves as a quick identifier, while the description provides context about what the rule does and why it exists. This becomes especially important as your rule set grows—clear identification helps team members understand your automation strategy at a glance.

The description field often plays a double role. Beyond documentation, it's frequently used in notification messages, appearing in the alerts sent to your team. This means your description should be both informative for configuration purposes and clear for those receiving notifications.

### Criteria

Filter criteria determine when a rule should fire. These work much like filters in Salesforce reports or list views—you select a field, choose an operator (equal, greater than, less than), and specify a value. You can combine multiple criteria with AND/OR logic to create complex conditions.

Criteria are optional. A rule without filter criteria will always evaluate to true, effectively creating a "catch-all" rule that processes every record. This can be useful for default behaviors but should be used thoughtfully to avoid unnecessary actions.

The fields available for filtering depend on what object the rule operates on. Rules that evaluate logs have access to log fields, while rules that evaluate issues work with issue fields. Custom fields you create on these objects automatically become available for filtering.

### Actions

Actions define what happens when a rule's criteria match. At minimum, every rule must have at least one action—otherwise, there's no point in evaluating the criteria. Many rules configure multiple actions that execute together when triggered.

The available actions vary by rule type. Some rules send notifications to communication platforms, others create tickets in external systems, and still others manage data lifecycle through archival or deletion. The framework is flexible enough to support diverse action types while maintaining a consistent configuration experience.

## Evaluation Patterns

Rules in Pharos follow different evaluation patterns depending on their purpose. Understanding these patterns helps you design effective automation strategies.

### Sequential Evaluation

Some rule types evaluate rules in order from top to bottom and stop at the first match. This "ladder" approach is useful for routing—you place your most specific rules at the top and broader catch-all rules at the bottom. When a record matches the first rule, that rule fires and evaluation stops, preventing duplicate actions.

This pattern is particularly important for notification and ticketing rules, where you typically want only one rule to fire per record. The evaluation order is explicitly managed, and you can reorder rules to adjust routing priority.

### Parallel Evaluation

Other rule types evaluate all active rules regardless of matches. Each rule fires independently when its criteria are met, and multiple rules can trigger simultaneously for the same record or condition.

This pattern suits scenarios where different rules monitor for different patterns that aren't mutually exclusive. Each rule represents an independent monitoring concern, and you want all relevant rules to fire when appropriate.

### Scheduled Evaluation

Some rules run on a scheduled basis rather than in response to record creation. These rules batch-process records at regular intervals, typically daily or weekly, identifying records that meet criteria and executing actions on them.

This pattern is ideal for maintenance tasks like data cleanup, where immediate response isn't necessary and batch processing is more efficient.

## Rule Design Principles

Effective rule configuration requires balancing specificity with maintainability. Rules should be specific enough to target the right records without being so narrowly defined that they require constant updates as your system evolves.

### Specificity vs. Generalization

Start with more specific rules for your critical conditions. If production payment processing fails, you want an immediate, specific alert rather than a general notification that gets lost in noise. Place these specific rules early in your evaluation order where applicable.

Then add broader rules to handle other scenarios. A catch-all rule at the end ensures nothing falls through the cracks, even if it's just logging to a low-priority channel or performing a default action.

### Single Responsibility

Each rule should have a clear, focused purpose. Rather than creating one complex rule that tries to handle multiple scenarios with intricate filter logic, create multiple simpler rules that each handle one scenario well. This makes your automation easier to understand, test, and maintain.

### Iterative Refinement

Rules rarely emerge perfect from initial configuration. Start simple, observe behavior in production, and refine based on actual data. You might discover that your thresholds are too sensitive, your filters too broad, or your actions too noisy. The rule framework makes it easy to adjust and improve over time.

{% hint style="success" %}
**Starting Your Rule Configuration**

Begin with a single rule for your most critical use case. Test it in a sandbox environment if possible, then deploy to production and monitor its behavior for a few days. Once you're confident it's working as expected, add additional rules incrementally.

This approach helps you learn the framework without overwhelming your team with notifications or actions from untested rules.
{% endhint %}

## Active Management

Rules aren't a "set and forget" configuration. As your application evolves—new features launch, old code is refactored, team structures change—your rules need to evolve too.

### Activation States

Every rule can be toggled between active and inactive states. Inactive rules are preserved but not evaluated, useful for temporarily disabling noisy rules during known issues or for keeping historical rules as reference without executing them.

Some rules may become read-only after their first execution, particularly those involving time-based thresholds. If you need to modify locked fields, deactivate the rule and create a new one with updated settings.

### Regular Review

Schedule periodic reviews of your rule configuration—monthly or quarterly depending on your deployment frequency. Look for rules generating false positives, rules that never fire, or gaps where issues aren't being caught. Update filter criteria as your codebase changes, and disable rules for deprecated functionality.

Document significant changes in rule descriptions so team members can understand the evolution of your automation strategy.

## In This Section

This section explores the rule framework in detail, providing the foundation for understanding all rule-based features in Pharos.

<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>🏗️ Rule Structure</strong></td><td>The anatomy of a rule—required and optional fields, evaluation order, and common patterns.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/rule-based-configuration/rule-structure.md">Rule Structure</a></td></tr><tr><td><strong>🎯 Trigger Conditions</strong></td><td>Filter criteria in depth—available fields, operators, complex logic, and filtering strategies.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/rule-based-configuration/trigger-conditions.md">Trigger Conditions</a></td></tr><tr><td><strong>⚡ Rule Actions</strong></td><td>The actions rules can execute, how multiple actions combine, and configuration best practices.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/rule-based-configuration/rule-actions.md">Rule Actions</a></td></tr></tbody></table>

{% hint style="warning" %}
**Before You Begin**

While rules are powerful, they can generate significant notification volume or modify data at scale. Test new rules in a sandbox environment when possible, and start with conservative settings that you can relax as you gain confidence in their behavior.
{% endhint %}
