PranavNagrecha/AwesomeSalesforceSkills / skills/admin/assignment-rules
assignment-rules
VerifiedUse this skill when configuring or troubleshooting Lead or Case assignment rules in Salesforce: creating rule entries, setting filter criteria, assigning records to users or queues, understanding when rules run, and implementing round-robin patterns with Apex. Trigger keywords: lead assignment, case assignment, assignment rule, queue assignment, auto-assign. NOT for creating the queue or public group a rule routes into — use admin/queues-and-public-groups. NOT for Omni-Channel or skills-based routing — use admin/omni-channel-routing-setup. NOT for approval routing — use admin/approval-processes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.6 KB |
| references/examples.md | markdown | 6.4 KB |
| references/gotchas.md | markdown | 10.5 KB |
| references/llm-anti-patterns.md | markdown | 5.9 KB |
| references/metadata-examples.md | markdown | 13.5 KB |
| references/migration-and-sandbox.md | markdown | 4.1 KB |
| references/routing-selector.md | markdown | 3.7 KB |
| references/testing.md | markdown | 4.4 KB |
| references/troubleshooting.md | markdown | 6.0 KB |
| references/well-architected.md | markdown | 4.9 KB |
| scripts/check_assignment_rules.pyexecutable | script | 13.0 KB |
| templates/assignment-rules-template.md | markdown | 2.9 KB |
references/troubleshooting.md
View on GitHub# Troubleshooting — "The assignment rule didn't fire"
Work top to bottom. Each step has one check and one fix. Stop at the first step that fails; later steps assume the earlier ones pass. The same order applies to Lead and Case.
## 0. Establish the facts before touching Setup
| Fact | How to get it |
|---|---|
| How was the record created? | Owner is the integration user → API / Data Loader path (step 1). Owner is the rep who created it → UI checkbox (step 1). Owner is a queue, but the wrong one → criteria or entry order (step 3). |
| Which rule is active right now? | `SELECT Id, Name, Active FROM AssignmentRule WHERE SobjectType = 'Lead'` — the `AssignmentRule` object is read-only and queryable; `Active`, `Name`, `SobjectType` are its only business fields. |
| What did the record look like at save? | The payload the integration sent, or field history. Rule criteria evaluate the values at save time, not values an after-save automation wrote later. |
## 1. Did the creation channel invoke the rule at all?
Assignment rules are opt-in for every channel except the three web/email intake channels.
| Channel | Rule runs by default? | What to check | Fix |
|---|---|---|---|
| Web-to-Lead, Web-to-Case, Email-to-Case | Yes | Nothing here — go to step 2 | — |
| Lightning UI, new record | No | "Assign using active assignment rule" (Lead) / "Run assignment rules" (Case) checkbox was ticked | Train users, or replace manual entry with a screen flow + invocable Apex that sets the header (see gotchas #3) |
| REST API | No | Request carries `Sforce-Auto-Assign: true` (or a rule Id) | Add the header in the integration |
| SOAP API | No | Envelope carries `AssignmentRuleHeader` with `useDefaultRule` or `assignmentRuleId` | Add the header |
| Bulk API / Bulk API 2.0 / Data Loader | No | Job or Settings specifies the assignment rule Id | Set `sfdc.assignmentRule` (Data Loader) or the job's assignment rule; the Id is per org — look it up with the SOQL in step 0 |
| Apex | No | `Database.DMLOptions` with `assignmentRuleHeader.useDefaultRule = true` passed to `Database.insert` | Plain `insert` never invokes rules — switch to `Database.insert(records, dmo)` (see references/testing.md) |
| Flow "Create Records" | No | Flow has no assignment-rule option on Create Records | Call an invocable Apex action that inserts with `DMLOptions`, or let the Flow set `OwnerId` itself and deactivate the rule for that path |
## 2. Is there exactly one active rule for this object?
Run the step 0 query. Zero active rules → activate one. The platform never allows two active rules on an object; if two admins each "activated" one, the second activation silently deactivated the first (gotchas #2).
## 3. Did an entry match, and was it the entry you expected?
- **First match wins.** A broad entry above a specific one swallows every record the specific one was meant to catch. Read the entries in Setup order, not alphabetical order.
- **Null values never match an equals entry.** `Lead.State equals CA` skips a lead with no State. Add a final catch-all entry with no criteria so unmatched records land somewhere visible instead of with the Default Lead Owner or the API user.
- **Values are compared at save.** A before-save Flow's writes are visible to the rule; formula and roll-up values may not be (gotchas #5). Route on a plain field the Flow populates.
- **Reproduce the match** by putting the entry's criteria into a list view or SOQL `WHERE` clause and checking whether the record appears. If it does not, the entry cannot have matched.
- **Picklist and boolean values** must be spelled exactly as the API value (`True` / `False` for checkboxes, comma-separated values for "equals any of").
## 4. Was the target usable?
- Queue exists **and supports the object**: `SELECT Queue.DeveloperName, SobjectType FROM QueueSobject WHERE SobjectType = 'Lead'`. A queue that does not list the object cannot own it.
- Queue has at least one active member (gotchas #4 has the `GroupMember` query).
- User target is still active. Audit entries after every offboarding; prefer queues so a departure does not break routing.
## 5. Did something overwrite the owner afterwards?
The rule's result is not the last word in the transaction. In save order the rule runs after before-save Flows and before after-save Flows and triggers, so:
- a **before-save Flow** that sets `OwnerId` loses to the rule;
- an **after-save Flow, Apex trigger, or legacy Process Builder** that sets `OwnerId` wins over the rule.
List every record-triggered Flow and trigger on the object and search them for `OwnerId`. Also check Omni-Channel push routing, escalation-rule reassignments, and lead conversion, all of which change ownership later. The full ordering is in `flow/flow-record-save-order-interaction`.
## 6. Auto-response email was not sent
The auto-response rule is only evaluated when the assignment rule fires, so steps 1 to 3 must pass first. Then check, in order:
1. The auto-response rule is active and its first matching entry is the one you expect (first match wins here too).
2. The entry's template exists, is active, and is a Classic template if the rule is deployed by metadata.
3. The sender address is a verified org-wide email address, and is **not** the Email-to-Case routing address (that creates a reply loop — `admin/email-to-case-configuration` gotchas).
4. In a sandbox, email deliverability is set to "All Email"; refreshed sandboxes default to system email only (`devops/sandbox-data-isolation-gotchas`).
5. Apex inserts set `dmo.emailHeader.triggerAutoResponseEmail = true` if the auto-response is expected from code.
Deeper treatment: `admin/case-management-setup` (Case) and `admin/lead-management-and-conversion` (Lead).
## 7. Escalation did not fire
Escalation is a timer, not a save-time rule, so it does not belong in steps 1 to 5. Check the escalation-rules skill's gotchas for the four usual causes: the engine's polling cadence, business hours pausing the clock, the age-over basis resetting on edit, and a rule that was deactivated and later reactivated. See `admin/escalation-rules`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |