Home / admin / escalation-rules

escalation-rules

Configure and troubleshoot Salesforce Case Escalation Rules: time-based escalation entries, business hours configuration, escalation actions (email alerts and reassignment), and diagnosing why cases are not escalating.

• v1.1.2
• Salesforce Spring '25+
• Updated 2026-09-12
• Reliability
• Operational Excellence

• escalation-rules
• case-management
• business-hours
• service-cloud
• time-based-automation

Open the skill folder on GitHub

Escalation Rules

This skill activates when you need to configure, review, or troubleshoot Salesforce Case Escalation Rules — the declarative mechanism that automatically notifies stakeholders or reassigns cases when they are not resolved within a specified time window.

It owns the design and operation of the rule: entry criteria, staged action thresholds, engine behaviour, the cutover, and the monitoring that proves it still works. The calendar the entry points at belongs to admin/business-hours-and-holidays; the routing that put the case somewhere in the first place belongs to admin/assignment-rules.

Before Starting

Gather this context before working on anything in this domain:

• Active rule limit: Plan for one active escalation rule per org. If multiple rule configs exist, only the one marked Active fires. Confirm whether an active rule already exists before creating a new one. UNVERIFIED (2026-09-04): the Metadata API guide describes escalationRule as a repeating element "processed in the order they appear in the EscalationRules container" and gives each rule its own active flag; it does not state the one-active-rule ceiling, and help.salesforce.com cannot be fetched. Verify in the target org's Setup > Escalation Rules list before relying on it.
• Processing cadence: The time-based engine that drives escalation is not real time. A case that hits its threshold at 2:05 PM may not escalate until the next engine pass — plan SLA commitments accordingly. UNVERIFIED (2026-09-04): the widely-quoted "approximately every hour" cadence appears in no fetchable official source; treat the interval as "batched, not immediate" and measure it in your own org before promising a number.
• Business hours dependency: The Object Reference states it directly for the BusinessHours object — "Escalation rules are run only during these hours" — and adds that holidays attached to a calendar suspend both the hours and the escalation rules that use them. If no calendar is restricted, the org default is 24/7.
• Who else writes OwnerId: an escalation action that reassigns changes the case owner, which re-fires every record-triggered automation watching ownership. Inventory those before staging a reassign action.

Questions to Ask Before Configuring

Ask these before opening Setup. Each one maps to a failure documented in references/gotchas.md, and an LLM that skips them produces a rule that deploys cleanly and escalates the wrong cases at the wrong time.

What a proper configuration adds over just doing it: the timer measures the working time the SLA actually promised, the cutover is a comparison rather than a surprise, and someone is still looking at escalated cases a quarter later.

Core Concepts

How Escalation Rules Differ from Assignment Rules

Assignment rules route cases to users or queues when a case is created or re-opened. They fire once on creation.

Escalation rules operate on a timer: they fire when a case that matches defined criteria has been open for longer than a configured threshold. If a case is not resolved within X hours, escalation rules send notifications or reassign the case.

The two rules are complementary. Assignment routes the case on arrival; escalation follows up when response time is exceeded.

Rule Structure: One Rule, Many Entries

A single active escalation rule contains multiple rule entries. In metadata each ruleEntry carries:

Entries are evaluated in order. The first matching entry wins — subsequent entries are skipped, just like assignment rule evaluation. Rules themselves are "processed in the order they appear in the EscalationRules container".

Escalation Actions Are Staged Inside One Entry

Multi-tier escalation is built from several escalationAction elements inside a single entry, each with its own minutesToEscalation. It is not built from several entries — a case only ever matches one entry.

An action with no assignedTo is notification-only and is a legitimate first stage. An action with assignedTo writes OwnerId.

UNVERIFIED (2026-09-04): the commonly-cited ceiling of 5 escalation actions per entry is not in the Metadata API guide's EscalationAction table and does not appear in the Salesforce App Limits cheat sheet (grep -i escalation returns nothing). escalationAction is typed as an unbounded array. Confirm the Setup-UI ceiling in your org before designing a fifth stage; scripts/check_escalation_rules.py reports the count as INFO rather than failing on it.

Business Hours and the Escalation Clock

businessHoursSource decides per entry which clock runs:

Two facts from the Object Reference's BusinessHours entry govern the result: escalation rules run only during the calendar's hours, and holidays associated with the calendar suspend those hours and the escalation rules that use them. Restricting the calendar is what makes off-hours pausing real — a calendar left at the shipped 24/7 default makes Static and None behave identically. Calendar design itself lives in admin/business-hours-and-holidays.

Common Patterns

Pattern: Tiered Escalation by Case Priority

When to use: Different SLA windows for different priorities. P1 cases escalate in 1 hour; P3 cases escalate in 8 hours.

How it works:

1. Create rule entries in priority order: P1 entry first, P2 next, P3 last.
2. Each entry uses field criteria Priority = "P1" (or P2, P3).
3. Set minutesToEscalation per stage: P1 = 60, P2 = 240, P3 = 480.
4. Add staged actions per tier: P1 notifies the manager at stage 1 and reassigns at stage 2.

Catch: Rule entries are evaluated top to bottom. Put P1 first, otherwise a P1 case might match a lower-tier entry if that entry has looser criteria.

Pattern: Mixed Clocks in One Rule

When to use: Sev-1 must escalate at 3 AM Sunday; everything else must wait for the next working morning.

How it works: Give the Sev-1 entry businessHoursSource = None and the standard entries businessHoursSource = Case (or Static with a named calendar). The choice is per entry, so one rule carries both clocks. The full XML is in references/metadata-examples.md.

Why not two rules: a second rule is a cutover, not an addition — see the deploy-inactive pattern below.

Pattern: Notify and Reassign at Different Thresholds

When to use: You want to warn the case owner at hour 2, then escalate to a queue at hour 4 if still unresolved.

How it works: Within a single rule entry, add two escalationAction elements:

• Action 1: minutesToEscalation 120 → notifyCaseOwner true, notifyTo the manager. No assignedTo.
• Action 2: minutesToEscalation 240 → assignedTo the escalation queue, assignedToType Queue, plus notifyEmail.

Both actions are attached to the same entry (same criteria). They fire as their thresholds are crossed.

Pattern: Deploy Inactive, Then Cut Over

When to use: Replacing or materially changing the live rule in production.

How it works:

1. Deploy the new rule with <active>false</active> alongside the incumbent. Nothing changes in production.
2. Compare the two rules' entry criteria against a sample of live cases before switching.
3. Activate the new rule in a separate, small deploy, in a window where a wave of instant escalations is survivable.
4. Watch escalated-case volume for one full SLA period before deleting the old rule.

The step-by-step with XML and CLI is in references/metadata-examples.md.

Decision Guidance

Recommended Workflow

1. Inventory the incumbent — retrieve the org's current rules (sf project retrieve start --metadata EscalationRules:Case) and record which rule is active, its entries, and its owner. Answer the table in ## Questions to Ask Before Configuring before designing anything.
2. Design the tiers — one entry per distinct clock-and-criteria combination, staged actions inside each entry; capture the design in templates/escalation-rules-template.md so the minutes, the calendar source, and the action targets are agreed before they are typed.
3. Confirm the calendar — check each entry's businessHoursSource against the calendar design in admin/business-hours-and-holidays; a Case source needs Case.BusinessHoursId populated at creation.
4. Build as metadata — shape escalationRules/Case.escalationRules-meta.xml from references/metadata-examples.md, with the new rule <active>false</active> for now.
5. Lint — run python3 skills/admin/escalation-rules/scripts/check_escalation_rules.py --manifest-dir force-app/main/default; it flags two active rules, a Static entry with no calendar, non-positive minutesToEscalation, assignedTo without assignedToType, a notified-but-templateless action (notifyCaseOwner or notifyTo with no notifyToTemplate), and catch-all entries.
6. Test the clock — reuse the after-hours clock test in admin/business-hours-and-holidays references/examples.md (Example 4) against a real case, then verify with the monitoring query in references/metadata-examples.md.
7. Cut over and watch — activate in its own deploy, then run the escalated-case monitoring query for one full SLA period; if nothing fired, work references/gotchas.md in order.

Review Checklist

Run through these before marking escalation rule work complete:

• [ ] Exactly one rule in the file has <active>true</active>, and it is the one you intend
• [ ] Rule entries are ordered correctly — most specific criteria appear first
• [ ] Every minutesToEscalation is a positive integer expressed in minutes, cross-checked against the SLA in hours
• [ ] Each entry's businessHoursSource (None / Case / Static) is the intended one, and businessHours is present exactly when the source is Static
• [ ] escalationStartTime and disableEscalationWhenModified were chosen deliberately per entry, not left at defaults
• [ ] No entry sets both criteriaItems and formula
• [ ] Every action with assignedTo also sets assignedToType, and the target user or queue exists in the target org
• [ ] Every action with notifyCaseOwner true or a populated notifyTo also sets notifyToTemplate — the org rejects the deploy without it even though the guide does not mark it Required
• [ ] Email templates referenced by notifyToTemplate / assignedToTemplate exist, are Classic templates, and are named folder-qualified (<folder>/<name>)
• [ ] The record automation that watches OwnerId has been reviewed for any reassigning action
• [ ] A test case has been aged past the threshold and escalation fired as expected
• [ ] Entry criteria values match the actual field values used in the org
• [ ] The cutover was a deploy-inactive-then-activate, and escalated-case volume was watched afterwards
• [ ] A monitoring report or query on escalated, still-open cases exists and has an owner

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems. Full treatment in references/gotchas.md.

1. The engine batches; it does not fire on the minute. Do not sell minute-level SLA precision on a declarative escalation rule.
2. Reactivating a rule can produce a wave. Cases already past their threshold escalate on the first pass after activation.
3. A 24/7 calendar makes the business-hours setting a no-op. Restricting the calendar is the work; selecting it is not.
4. minutesToEscalation is minutes; Setup shows hours. A "4 hour" tier written as 4 escalates after four minutes.
5. Reassignment writes OwnerId. Every record-triggered automation on ownership fires again, hours after the case was created.
6. Holidays on the calendar suspend the escalation rules that use it. An unmaintained holiday list silently changes SLA behaviour a year later.
7. IsEscalated is a plain writable boolean. Anything with update access — a data load, a flow, an integration — can set or clear it.
8. notifyToTemplate is required whenever the case owner or a named user is notified, but the guide never says so. An action with notifyCaseOwner true and no notifyToTemplate deploys as valid XML and fails only at org validation.

Output Artifacts

Reference Files

Related Skills

• admin/assignment-rules — initial routing; its references/metadata-examples.md holds the base EscalationRules shape and its references/troubleshooting.md step 5 covers ownership overwrites
• admin/business-hours-and-holidays — the calendar an entry consumes through businessHoursSource, and the after-hours clock test
• admin/case-management-setup — case intake, where Case.BusinessHoursId gets populated
• admin/entitlements-and-milestones — milestone timers, the other SLA clock; not the same engine
• architect/sla-design-and-escalation-matrix — the tier table and escalation matrix that decide what these entries should say
• admin/approval-processes — time-based routing for human decisions, not SLA escalation

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/escalation-rules-template.md
• scripts/check_escalation_rules.py