The automations engine is the workflow layer of the WPResidence real estate CRM. This article documents the rule storage, the condition evaluator, the 8 action handlers, and the cron architecture.
Files
- libs/automations.php – CRUD, condition evaluator, action executor, AJAX handlers, default seeder.
- libs/automations-cron.php – hourly batch processor, event dispatcher, queued executor.
- page-templates/wpestate-crm-dashboard_automations.php – list template.
- templates/crm_add_automation.php – add/edit form.
- templates/dashboard_automation_unit.php – single rule card.
Storage – wp_wpresidence_crm_automations
12 columns: automation_id, user_id, title, trigger_type (time_based or event_based), trigger_event, conditions (longtext JSON), action_type, action_config (longtext JSON), status (active or paused), last_run_at, created_at, updated_at.
Indexes on status, trigger_type.
CRUD API
| Function | Purpose |
|---|---|
| wpestate_crm_insert_automation($data) | Insert; required: title, trigger_type, action_type |
| wpestate_crm_get_automation($id) | Fetch one with JSON-decoded conditions/action_config |
| wpestate_crm_get_automations($args) | Filters: status, trigger_type, pagination |
| wpestate_crm_update_automation($id, $data) | Partial update, stamps updated_at |
| wpestate_crm_delete_automation($id) | Delete |
| wpestate_crm_toggle_automation($id) | Flip between active and paused |
AJAX Endpoints
| Action | Nonce |
|---|---|
| wpestate_crm_save_automation | wpestate_crm_save_automation |
| wpestate_crm_delete_automation | wpestate_crm_delete_automation |
| wpestate_crm_toggle_automation | wpestate_crm_toggle_automation |
Condition Evaluator
The evaluator supports 18 fields (mix of direct columns and computed metrics) and 10 operators: equals, not_equals, greater_than, less_than, contains, not_contains, is_empty, is_not_empty, in, not_in. Conditions are combined with AND – all must pass for the rule to fire.
Supported Fields
- Direct columns: lifecycle_stage, lead_source, lead_type, status, assigned_agent_id.
- Computed: days_since_created, days_since_last_activity, days_since_stage_change, activity_count, has_deal, deal_stage, deal_value, deal_days_in_stage, task_overdue_count, has_tasks_due_this_week, tags_contain, has_buyer_preferences, viewed_listing_count_last_24h.
Action Executor – 8 Types
- send_email – resolves placeholders via wpestate_crm_resolve_placeholders(), picks recipient (contact/agent/admin), sends via wpestate_send_emails() with wp_mail() fallback.
- send_sms – resolves placeholders, sends via Twilio if configured.
- change_stage – updates contact’s lifecycle_stage.
- create_task – builds task row from action_config (title, type, priority, due_days offset), resolves placeholders, calls wpestate_crm_insert_task().
- assign_agent – updates assigned_agent_id.
- add_tag – appends to contact’s tags CSV (no duplicates).
- run_matching – calls wpestate_crm_match_properties() and optionally notifies agent.
- send_digest – compiles tasks-due-this-week for the agent and emails a digest.
Cron Architecture
| Event | Schedule | Handler |
|---|---|---|
| wpestate_crm_process_automations | Hourly | Time-based batch processor |
| wpestate_crm_execute_queued_action | One-time | Event-based executor (args: automation_id, contact_id) |
| wpestate_crm_match_new_listing | One-time | Buyer matching when a listing is published (arg: post_id) |
| wpestate_crm_weekly_digest | Weekly | Weekly task digest |
Event-Based Dispatcher
wpestate_crm_process_event_automation() is attached to CRM entity hooks. It scans active rules whose trigger_type=event_based and trigger_event matches the fired event, evaluates conditions, then schedules one wpestate_crm_execute_queued_action cron per match (1-minute delay) to keep the triggering request fast.
Event Sources
- wpestate_crm_after_insert_contact → contact_created
- wpestate_crm_after_add_note → note_added
- wpestate_crm_after_record_activity (type=’call’) → call_logged
- wpestate_crm_after_insert_deal → deal_created
- wpestate_crm_after_update_deal → deal_stage_changed (and sub-events for specific stages)
- wpestate_crm_after_viewed_listing → viewed_listing
- publish_estate_property → schedules buyer matching
Time-Based Dedup
Hourly batch processing compares last_run_at and cross-checks the activities table for an automation_triggered row with matching automation_id + contact_id since last_run_at. Prevents the same rule firing on the same contact twice.
27 Default Rules
Seeded on activation by wpestate_crm_seed_default_automations(). All start status=’paused’. Categories and counts:
- Speed-to-Lead – 4
- Stale Lead Recovery – 7
- Deal Pipeline – 6
- Task Management – 2
- Contact Lifecycle Auto-Progression – 5
- Property Matching – 3
Permissions
wpestate_crm_user_can(‘automations’, $action). Default: all for administrators, none for everyone else.