FlagGuard — Rule Engine & Smart Alerts for Perfex CRM

Important: FlagGuard is a module that runs inside Perfex CRM — not a standalone application. You need an existing install of Perfex — Powerful Open Source CRM to use it.

FlagGuard — the rule engine your Perfex CRM was missing

FlagGuard adds a full visual rule engine to Perfex CRM that flags Tasks, Projects, Leads and Invoices at risk: composable AND/OR conditions over time, tags, status, priority, assignee and client; a real-time Monitor with drilldown drawer; automatic alert emails with anti-spam cooldown; a unique Rule Tester preview engine (test a rule against live data before activating it); and compliance reports exportable to CSV. Built native to Perfex 3.x, fully self-hosted, no external services, no recurring fees.

Every team that uses Perfex loses visibility when work slips past its deadlines — an overdue task nobody touches, a lead that went silent for two weeks, an invoice stuck in draft, a project tagged “blocker” with no progress for days. Perfex core has fields and timestamps but no rule engine: no automatic flagging, no escalation logic that respects per-team permissions. SLA-style add-ons cover one entity only; generic automation tools want to ingest your CRM into their cloud. FlagGuard fills that gap natively, on your server, across the four core entities, with one consistent rule engine.

Why FlagGuard is different

• Four entities, one rule engine. Most monitoring add-ons cover one Perfex entity. FlagGuard applies the same composable rule logic to Tasks, Projects, Leads and Invoices — with the right field set for each. One module, four use cases, one consistent UI.
• Composable AND/OR groups, no ML black box. Every rule is a tree of conditions you can read top to bottom. “Overdue more than 5 days AND tagged Blocker AND priority High” is exactly what runs. Auditable, reproducible, explainable to your team.
• Rule Tester preview before activation. Before you turn a rule on, FlagGuard tells you exactly how many tasks, projects, leads or invoices would match right now. No surprise floods of notifications on day one.
• Anti-spam cooldown built in. Configurable globally and per rule. The engine never re-notifies the same flag inside the cooldown window. Default 60 minutes, override per rule.
• Strict permission scoping (IDOR-safe). Every query is filtered through Perfex’s native permission scopes — a sales rep never sees flagged tickets from another team’s pipeline, a project manager never sees overdue invoices outside their scope.
• Self-hosted, source included. No external API calls, no data leaves your server, no monthly fee. Install once on your VPS and own it.

What’s inside

Dashboard

• 4 KPI cards by flag color — critical (red), at risk (amber), monitoring (blue), healthy (green) — each with a 7-day sparkline
• Complementary metrics strip: total entities flagged lifetime, opened in last 24h, cleared in last 24h, rules active vs total
• Quick actions row: create rule, open Monitor, view Reports, settings
• Top-5 firing rules and top-5 staff with flagged work, each row clickable to drill into a filtered Monitor
• Recent activity feed (last 10 events) with deep link to the full History
• Onboarding panel when rules count is zero — gets the admin to the Rule Builder in two clicks
• Cron status banner when the last cron tick is overdue (alerts before silent detection gaps)

Visual Rule Builder

• 24 condition fields across the 4 entities: age since creation / start date, time to due date, overdue by, tag contains, status, priority, assigned staff, client, has no progress in, plus entity-specific fields like estimated time exceeded (tasks), lead age without conversion (leads), invoice overdue by / time since draft (invoices)
• 10 operators: =, !=, >, >=, <, <=, IN, NOT_IN, CONTAINS, NOT_CONTAINS
• Composable AND/OR groups with arbitrary nesting, drag-free row UI, validation in browser before submit
• Rule Tester sticky bar — live preview: “this rule would match 47 tasks and 3 projects right now”
• 4-color flag picker per rule (red / amber / blue / green) and per-rule notification recipients

Alert Monitor

• Server-side DataTable listing every open flag across the four entities
• Filterable by flag color, rule, entity type (Task / Project / Lead / Invoice), assigned staff, client, date range
• Cross-entity IDOR guard: staff without view-all permissions only see flags on entities they’re assigned to or own
• Direct deep link to the original Task / Project / Lead / Invoice in a new tab
• Stacked-card mobile layout for on-the-go review

Flag Detail Drawer

• Row click opens a lateral drawer with the entity summary, rule logic, and per-condition pass/fail breakdown
• Full history timeline for that flag (opened, notified, cooldown-suppressed, acknowledged, cleared)
• Three quick actions: Re-check (force evaluation now), Acknowledge (silence cooldown without closing), Clear (close the flag manually)
• Auditable: every action is logged in the History event log with timestamp and actor

History & Reports

• Immutable event log: every flag opened, notified, suppressed by cooldown, acknowledged, cleared
• Filterable by event type, rule, entity type, date range — with CSV export
• Reports view with date-range KPIs, breakdowns by rule / assignee / project / client, and an area chart of flags opened vs cleared over time
• One-click CSV export for every breakdown — paste directly into your board / sponsor reports
• Configurable retention (history default 180 days, logs default 90 days), purged automatically by the existing Perfex cron tick

Notifications & Cooldown

• In-app notifications via Perfex’s native add_notification()
• Email via two editable templates (instant flag alert + daily manager digest) available in Perfex’s native Setup → Email Templates
• Cooldown anti-spam configurable globally and per rule (default 60 minutes)
• Auto-clear on resolve: when an entity stops matching, the flag closes automatically — optional notification when cleared
• Test Mode: rules run, flags log, history records — emails do not send. A persistent banner reminds you while active

Settings

• Master engine on/off and Test Mode toggle
• Default cooldown minutes and per-rule overrides
• History retention days, log retention days
• Auto-clear notification toggle
• Sticky save bar with dirty-form detection — never lose unsaved changes

Security & reliability

• CSRF-protected AJAX on every action
• html_escape() on every dynamic value rendered in views
• CodeIgniter Query Builder only — zero raw SQL with interpolated variables; the rule compiler uses a hardcoded field/operator whitelist
• 5-tier permissions: view, manage_rules, view_reports, manage_alerts, settings
• Idempotent installer (safe to re-activate), versioned migration framework, clean uninstaller (drops only the module’s 4 tables — your CRM data stays intact)
• No external API calls, no telemetry, no third-party JS bundled

Internationalization

• English + Spanish language packs (331 strings each, full parity)
• Every UI string runs through Perfex’s _l() helper — ready for community translation
• Full UTF-8, zero mojibake

How it scales

The engine runs on the existing Perfex cron tick. Each tick evaluates active rules in priority order, batches re-evaluation of open flags grouped by rule (avoids N+1), and writes results with an idempotent UPSERT pattern protected by a SQL-computed sentinel hash. Native Perfex hooks (after_add_task, after_update_task, lead_created, after_invoice_added, after_payment_added and 9 more) provide instant re-evaluation between cron ticks for event-driven changes. A 5,000-task / 1,000-lead / 500-invoice install evaluates in under a second per tick. No background workers, no queue server, no extra cron container required.

Live demo

URL: https://onboarding.ticempresarial.com/demo5/admin
Email: admin@demo.com
Password: 14789632

Log in, open FlagGuard → Dashboard, inspect the KPI cards by flag color and the recent activity feed. Go to Rules → click any rule → press “Test rule against current data” to see the live preview. Open Monitor → click any row to open the drilldown drawer. Open Reports → export a CSV. The demo is pre-seeded with 194 tasks, 60 projects, 111 leads, 79 invoices, 8 active rules and 109 open flags spanning all four entities.

Requirements

• Perfex CRM 3.0.0 or later (tested up to 3.4.1)
• PHP 7.4 / 8.0 / 8.1 / 8.2 / 8.3
• MySQL 5.7+ or MariaDB 10.3+ (InnoDB engine required)
• PHP extensions: json, mbstring (both standard)
• No external API key required — FlagGuard runs 100% on your server
• Perfex cron enabled for automatic evaluation (every 5–15 minutes strongly recommended)

Support

Direct author support included for 6 months: bug fixes, install help, rule design questions. Submit a ticket via the Comments tab on this item page.

What’s NOT in v1.0 (transparency)

FlagGuard v1.0 is intentionally focused on the core flagging loop across the four entities. The following are on the roadmap for v1.1+:

• Webhook destinations (Slack, Microsoft Teams, Discord) on flag-open events
• AI-suggested rules based on historical match patterns (“tasks tagged X are late 80% of the time — want a rule?”)
• Rule templates library for first-time setup
• Bulk actions on flagged items from inside FlagGuard (re-assign, change due date, change priority)
• Real-time trend charts (lines, sparkbars) beyond the area chart already in Reports
• Per-tenant SaaS-mode isolation — FlagGuard works on single-tenant Perfex installs by symmetry, but multi-tenant SaaS configurations are not officially tested in v1.0

If any of these is critical for your workflow, contact us before purchasing — we will tell you straight whether the upcoming release will cover it or whether you should wait.

Why we built this

We run a CRM consultancy. The same kind of cleanup kept coming back across every client: “find the tasks overdue and nobody is touching”, “find the leads that went silent”, “find the draft invoices that were never sent”. Every alternative was a hard-coded threshold buried in someone’s custom code, an email blast that spammed the whole team, or a generic automation SaaS that wanted to slurp your CRM into a third-party cloud. We built FlagGuard — the configurable, native, in-CRM watchdog we wanted to buy, but couldn’t.

FlagGuard is a community-built add-on for Perfex CRM. We are not affiliated with Perfex Ltd.