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

# Rule Structure

Learn about the basic fields involved in creating a rule: name, description, and optional order.

Understanding rule structure is key to effectively using Pharos automation. While different rule types serve different purposes, they all share a common anatomy that makes the system predictable and learnable.

## Anatomy of a Rule

Think of a rule as having three layers: metadata that identifies it, criteria that determine when it should act, and actions that define what it does. This layered structure separates concerns cleanly—who you are, when you fire, and what you do.

```mermaid
graph TD
    A[IDENTIFICATION<br/>Name + Description + Status]
    B[CRITERIA - Optional<br/>When should this rule fire?]
    C[ACTIONS - Required<br/>What should happen?]
    A --> B --> C
```

### The Identification Layer

Every rule begins with a name and description. The name serves as your rule's identity in lists and logs—it should be immediately meaningful to anyone on your team. Rather than generic labels like "Rule 1" or "Test," effective names communicate what the rule does and where it routes information.

Good naming often follows a pattern of condition → action: "Production Critical Errors → PagerDuty" or "Integration Timeouts → #eng-integrations Channel." This pattern makes scanning rule lists efficient and helps team members understand your automation strategy at a glance.

The description provides deeper context. It explains why the rule exists, what business process it supports, and any nuances about its configuration. This becomes your documentation—six months from now, when someone asks why a particular rule is configured a certain way, the description should provide the answer.

{% hint style="info" %}
**Description as Communication**

Many rule types use the description field in notification messages. When an alert fires, team members see your description in their Slack or Teams notification. This dual purpose means descriptions should be clear for both configuration documentation and runtime communication.
{% endhint %}

### The Criteria Layer

Filter criteria form the decision logic of your rule. These work exactly like filters in Salesforce reports—select a field, choose an operator, specify a value. You can build complex conditions using AND/OR logic, though simpler is usually better.

Criteria are entirely optional. A rule without filters acts as a universal matcher, firing for every record it evaluates. This catch-all behavior is useful for default routing or ensuring nothing falls through gaps, but it should be used intentionally rather than accidentally.

The sophistication you need in your criteria depends on your routing strategy. Sometimes a single field check suffices—"Functional Area equal Integration" for routing integration errors. Other times you need multiple conditions with custom logic—"(Priority equal Highest OR Impacted Users Count greater than 50) AND Category equal Apex."

### The Actions Layer

Actions are what make rules useful. They're the "then do this" part of your automation. Every rule must configure at least one action, though many rules execute multiple actions simultaneously.

The available actions depend on your rule type and what integrations you've configured. Actions might send notifications, create tickets, archive data, or trigger webhooks. When multiple actions are configured, they generally execute in parallel, though some rule types ensure logical ordering where necessary.

## Activation and Lifecycle

Rules exist in either an active or inactive state. This binary toggle controls whether the rule participates in evaluation. Activating a rule immediately puts it into the evaluation pipeline, while deactivating preserves the rule's configuration without executing it.

This activation model serves several practical purposes. During troubleshooting, you might temporarily disable a rule that's generating false positives while you refine its criteria. During known maintenance windows, you might deactivate certain rules to prevent noise from expected errors. Historical rules can be preserved as inactive references for team knowledge without cluttering your active automation.

Some rules develop constraints after their first execution. Fields that define fundamental timing or grouping characteristics may become read-only to prevent changes that would create inconsistent behavior. When you need to modify these locked aspects, the solution is to deactivate the original rule and create a new one with the desired configuration. The original rule remains as a historical reference if needed.

## Evaluation Order

Some rule types evaluate sequentially, while others evaluate in parallel. This distinction fundamentally affects how you design your rule strategy.

### Sequential Evaluation

When rules evaluate sequentially, they're checked from top to bottom until one matches. The first matching rule fires, and evaluation stops. This "ladder" approach prevents duplicate actions and gives you precise control over routing priority.

Sequential evaluation requires thoughtful rule ordering. More specific rules should appear at the top, with progressively broader rules below. A catch-all rule with no filters works well at the bottom to ensure nothing slips through, but placing it at the top would prevent all other rules from ever firing.

Consider this correctly ordered sequence: a rule targeting critical production failures fires first, followed by a rule for high-priority issues, then a rule for sandbox errors, and finally a catch-all for everything else. Each rule has decreasing specificity, and each subsequent rule only evaluates if the previous ones don't match.

Reordering rules is straightforward through the interface, and changes take effect immediately for subsequent evaluations. This makes it easy to adjust routing priority as your needs evolve.

### Parallel Evaluation

Other rule types evaluate all active rules for every relevant record or condition. Multiple rules can fire simultaneously, each independently assessing whether its criteria are met. There's no concept of order or "first match" behavior.

Parallel evaluation suits scenarios where rules monitor for different independent concerns. Each rule represents a distinct monitoring interest, and you want all relevant rules to trigger when appropriate. The rules don't compete with each other—they coexist.

{% hint style="warning" %}
**Evaluation Pattern Varies by Use Case**

Different rule types use different evaluation patterns based on their purpose. Routing-oriented features typically use sequential evaluation to prevent duplicate notifications, while monitoring-oriented features use parallel evaluation to detect multiple simultaneous conditions.
{% endhint %}

## Managing Rules

Rule management follows familiar Salesforce patterns. The administrative interface provides access to create, edit, activate, deactivate, and delete rules. New rules activate by default when saved, immediately participating in evaluation unless you explicitly deactivate them.

Editing existing rules works as expected, though some fields may become read-only after the rule has executed. This protection ensures consistency—you can't change fundamental parameters that would create confusion about historical behavior. If you need to modify locked fields, create a new rule with the desired configuration and deactivate the original.

Deactivation serves as a middle ground between active execution and deletion. Inactive rules preserve their configuration and remain visible for reference, but they don't participate in evaluation. This makes it safe to temporarily disable noisy rules or pause automation during maintenance without losing your configuration work.

Deletion is permanent and should be used sparingly. In most cases, deactivation serves your needs better—it preserves institutional knowledge while stopping execution. Reserve deletion for rules that are truly obsolete and have no historical reference value.

## Scale and Performance

Pharos supports extensive rule configurations, but practical considerations exist. While you can create dozens of rules, keeping your rule set focused and pruned improves both performance and maintainability. Complex filter logic and high volumes of rule evaluations consume platform resources, and external actions like API calls have their own rate limits.

Most organizations find that 20-30 well-designed rules per type serve their needs effectively. Beyond that threshold, you're often creating overlapping or overly specific rules that could be consolidated. Regular review helps identify rules that never fire, rules generating excessive noise, and opportunities to combine similar logic.

Rules execute within standard Salesforce governor limits. API callouts for external integrations, DML operations for record creation, and CPU time for evaluations all count against your org's limits. Typical rule configurations stay well within bounds, but extremely high-volume scenarios deserve monitoring.

## Design Patterns

Effective rule design often follows recognizable patterns that balance specificity with maintainability.

**Tiered Routing** organizes rules by severity or priority. The most critical conditions route to immediate alerting channels, moderate issues go to team notification channels, and low-priority events might only generate daily digest emails. Each tier has progressively broader criteria, creating a decision tree that appropriately escalates based on importance.

**Team-Based Routing** splits responsibility across functional areas. Integration errors route to the integration team, batch job failures go to the data team, and UI exceptions route to the frontend team. This pattern ensures errors reach people with the right expertise without creating notification overload for those outside the relevant domain.

**Environment Separation** applies different handling to production versus lower environments. Production errors might trigger immediate alerts and ticket creation, while sandbox errors only generate notifications during business hours. This acknowledges that production issues carry greater urgency without ignoring lower environment problems entirely.

{% hint style="success" %}
**Start Simple, Evolve Gradually**

Begin with a single broadly applicable rule, observe its behavior for a few days, then add specificity through additional rules. This iterative approach helps you learn what actually happens in your environment rather than trying to predict every scenario upfront.
{% endhint %}

## Troubleshooting Rule Behavior

When rules don't behave as expected, a systematic approach helps identify the issue. If a rule isn't firing when you expect it to, verify that it's active, check whether filter criteria actually match the records in question, and consider whether another rule in the evaluation order is matching first. For routing-oriented rules, the last point is particularly important—your specific rule might be perfect, but a broader rule above it catches the records first.

Conversely, if rules fire too frequently, the filter criteria may be too broad or evaluation order may need adjustment. Sometimes what appears to be excessive firing is actually correct behavior that reveals an underlying application problem worth addressing. Temporarily deactivating the rule gives you breathing room to investigate and refine.

When the wrong action executes, the issue is usually evaluation order in sequential rule types. The rule you intended to fire exists lower in the sequence than the rule that actually fires. Reordering resolves most of these scenarios, though sometimes it reveals overlapping criteria that need clarification.

***

**Continue to** [**Trigger Conditions**](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/rule-based-configuration/trigger-conditions.md) to explore filter criteria in depth, or [**Rule Actions**](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/rule-based-configuration/rule-actions.md) to understand what rules can do when they fire.
