--- title: Rule Inspector description: "The Rule Inspector is the diagnostic surface inside each automation rule. It answers the question every automation user eventually asks: \"why didn't my rule fire?\" For each rule, the inspector shows recent results with the specific reason a run succeeded,…" url: "https://webstepper.io/docs/trustlens/automation/rule-inspector/" updated: "2026-10-18" category: Automation --- # Rule Inspector The Rule Inspector is the diagnostic surface inside each automation rule. It answers the question every automation user eventually asks: "why didn't my rule fire?" For each rule, the inspector shows recent results with the specific reason a run succeeded, was skipped, failed, or is still queued. This page covers how to read the inspector, what the SKIP reasons mean, and how to use it for tuning rules. --- ## Accessing the Inspector 1. Go to **TrustLens → Automation** 2. Click any rule in the list — its detail opens in place (the URL gains `?rule_id=…`, so you can bookmark it) 3. Look at the **Recent runs** panel The panel shows the latest 10 attempts for this specific rule. Next to it, the **Last 7 days** panel shows times fired, succeeded (with a success percentage), errors, skipped, average execution time and a 14-day sparkline of fires per day. There is no separate log screen for older history — see The Automation Log below. --- ## What an Entry Shows | Field | Description | | --- | --- | | Time | When the run was logged | | Action | The rule's action (e.g. Hold Order) | | Target | The order number (on order triggers) and the customer's email, or the start of their hash | | Refund details | On Refund Processed rules: amount, currency, refund ratio, classification, transition and delivery evidence | | Status | OK / ERR / SKIP / QUEUED badge | | Reason | Shown on SKIP and ERR rows | --- ## The Four Statuses ### OK All conditions passed and the action ran. For a webhook, OK means the receiver answered with a 2xx. OK and ERR rows count as "Times fired." ### SKIP The rule was evaluated but didn't act. The "Reason" tells you which: - `Condition not met: trust_score > 50` — the named condition evaluated false - `Cooldown active` — the rule already ran this action for this customer within the last hour - `Guest order: no customer email hash` — a customer-level action on an order with no billing email Disabled rules and a paused engine leave no rows at all — the rule isn't evaluated. ### ERR The action failed. The reason is shown: - `Webhook returned HTTP 500 after 4 attempt(s).` — receiver error after all retries - `Webhook delivery failed: …` — timeout (10s) or connection error after all retries - `Invalid webhook URL.` - `Action requires an order trigger (Order Placed, Order Completed, Refund Processed, or Dispute Recorded).` — an order action ran without an order, e.g. a dispute whose order couldn't be loaded Webhook retries happen in the background; the inspector shows a single ERR (or OK) row with the final result, not one row per attempt. ### QUEUED The run is waiting. A Send Webhook delivery is queued until Action Scheduler sends it; from 1.3.23 a Hold Order, Cancel Order or Require Verification on an unpaid Order Placed order is queued until the payment is confirmed (the order's notes say so). A second row — OK or ERR — is added when it resolves. QUEUED rows don't count as fires or errors. --- ## The "Condition not met" Reason The most common SKIP reason. Format: `Condition not met: {field} {operator} {value}` — the condition as you wrote it. The customer's actual value isn't shown; open their profile to see it. Example: `Condition not met: trust_score < 30` on a customer whose profile shows a score of 47. This tells you exactly why the rule didn't act. If the rule was supposed to fire on customers with score < 30 but the customer's actual score is 47, the rule is working correctly — the customer just doesn't meet the criterion. The engine evaluates conditions in order and stops at the first that fails. If multiple conditions would have failed, you'll only see the first. After fixing that, you may see a new "Condition not met" for the next condition. Customer conditions also fail when the customer has no TrustLens record yet, and order conditions fail when no order is in scope. --- ## Common Investigations ### "My rule should be firing but isn't" 1. Open the rule and check Recent runs 2. Look for SKIP entries on the customer who should have triggered the rule 3. The Reason tells you which condition rejected the trigger 4. Either: - Fix the condition (it's wrong — e.g. `segment = VIP` instead of `vip`) - Fix the customer's data (the field value is unexpected) - Wait — the trigger hasn't actually fired yet for this customer ### "My rule is firing too often" 1. Open the rule and check Recent runs 2. Look for repeated OK entries on the same target 3. Customer-level actions already have a fixed one-hour cooldown per customer; order actions have none, so they run on every matching order 4. Tighten conditions to fire on a narrower cohort, or pick a more specific trigger (Score Updated fires on every recalculation) ### "My webhook action is failing" 1. Open the rule and check Recent runs for ERR entries 2. The reason shows the HTTP status or the connection error 3. Test the webhook URL with a manual request 4. Verify HMAC signature handling on the receiver side 5. Check whether the receiver is reachable from your WordPress server (firewall, internal IP, etc.), and that the URL doesn't redirect — redirects aren't followed 6. If the URL is a Slack incoming webhook, route it through Zapier, Make or your own endpoint instead — Slack rejects the TrustLens payload ### "My rule fired but the action didn't happen" 1. OK status confirms conditions passed and the action ran 2. QUEUED means it hasn't happened yet — a webhook waiting for Action Scheduler, or a hold waiting for the order's payment 3. If OK but the downstream effect isn't visible, the action did fire but something downstream didn't follow through (mail delivery, a receiver that accepted and ignored the payload, Enable Blocking turned off, etc.) --- ## The Automation Log There's no log screen beyond the inspector's 10 most recent runs. Every run is stored in the `{prefix}trustlens_automation_logs` database table — rule ID and name, customer hash, trigger, action, order ID, status, duration, error message and created time — which you can query directly. Non-skipped runs also appear as automation events in the customer's Recent activity. Default retention is 90 days. Developers can change it (7 to 365 days) with the `trustlens/automation/retention_days` filter. --- ## Inspector vs Validator The save-time validator catches structural problems before a rule is even active — unsatisfiable conditions, fields or actions that don't fit the trigger, missing action values. The inspector catches runtime problems — conditions that *could* be true but aren't on the events you've seen, action failures, cooldown skips. The two together give you both pre-flight and in-flight diagnostics. A rule that passes the validator and fires correctly in the inspector is doing what you intended. --- ## Reading SKIP Reasons in Context SKIP isn't a failure — it's the engine doing its job. A rule like "send a webhook when score drops below 30" should SKIP every event where the score is 50, 60, 70. Those skips are correct. Look for SKIP reasons that are *wrong*: - A text value that doesn't match exactly (segment values are lowercase; payment methods are gateway IDs such as `stripe`) - A boolean written in a way that reads as false (only `1`, `true` or `yes` mean true) - A field's actual value isn't what you expected (data quality issue) - A `linked_accounts` condition on a version before 1.3.23, which always read 0 If every recent evaluation is SKIPPED for the same reason, the rule may never fire under your current store conditions — consider whether the conditions still make sense. --- ## Testing Rules There is no "Test Rule" button — rules run only on real trigger events. To test one, cause the event with a test customer and watch Recent runs: - Score Updated / Segment Changed — click **Recalculate** on the test customer's profile - Customer Blocked / Unblocked / Allowlisted / Allowlist Removed — use the buttons on the test customer's profile - Order Placed / Order Completed / Refund Processed — place, complete or refund a test order A second test within the hour SKIPs with "Cooldown active" for customer-level actions. On a staging site, developers can set the `trustlens/automation/rule_cooldown` filter to 0 while testing.