Automations System — Full Reference

Last updated: 2026-05-31

How Biz1 automations work end-to-end: data model, execution paths, control flow, and where to read more.

1. Two-layer model

| Layer | Table | Role |

|-------|-------|------|

| **Event (trigger)** | `automation_event` | Defines **when** a flow runs |

| **Actions (steps)** | `automation` | Defines **what** happens (`flow_id` → `automation_event.id`) |

CRM event occurs (new lead, status change, …)
    → match automation_event rows (event + par/val filters + delay)
    → queue / run linked automation rows (ordered by step)
    → each row.type dispatches to include_file/automations/actions/{type}.inc.php

2. UI surfaces

| Page | Route | Purpose |

|------|-------|---------|

| Automation table | `dashboard/event/automation-table` | List flows; create/edit **triggers**; AI event chat |

| Canvas builder | `dashboard/event/automation/{flow_id}` | Build **action** graph; AI action chat; Save |

See include_file/AUTOMATION_AI_BUILDER.md for UI flows and AI builders.

3. Runtime entry points

| Function | File | When used |

|----------|------|-----------|

| `automations_cons()` | `automations.php` | Main hook from CRM (customer update, lead, etc.) |

| `run_automations_by_id()` | `automations.php` | Run one flow by `automation_event.id` |

| `doAutomations_config()` | `automations.php` | Execute action rows for one flow |

| Wrappers | `config.php`, `common_helper.php` | `automation()`, `doAutomation()`, `automations()` |

Execution loop (simplified)

1. Load `$auto_flow` rows for `flow_id`, ordered by `step`, `id` 2. For each row: check `$skip` (runtime + IF control) 3. Apply `$replace` placeholders to row strings (`{name}`, `{ai-message}`, …) 4. Evaluate `if` / `ai_agent` control rows → update skip/replace for following rows 5. `include` action file: `automations/actions/{type}.inc.php` 6. Action runs with customer context (`$contact_us`, `$User`, `$Org`, …)

4. Control actions

| Type | Purpose | Doc |

|------|---------|-----|

| `if` | JSON rules → skip steps / inject replace tokens | AUTOMATIONS_CHANGES.md §5–6 |

| `ai_agent` | Gemini call → `{ai-field}` tokens + optional skip | AI_AGENT_FUNCTIONALITY.md |

Both are evaluated in the **loop** (`automations_cons` / `run_automations_by_id`), not inside their `.inc.php` stubs.

5. Runtime controls (optional args)

Added in refactor — see AUTOMATIONS_CHANGES.md:

| Param | Effect |

|-------|--------|

| `$skip` | Array of action row IDs to skip this run |

| `$replace` | `[{"key":"value"}]` merged into `{key}` placeholders |

6. Action types catalog

49 action types extracted to `include_file/automations/actions/{type}.inc.php`.

**Per-type fields (popup UI, DB columns, shortcodes):** → include_file/AUTOMATION_NODE_OPTIONS_MAP.md

Common groups: - **Communication:** `sendSms`, `sendEmail`, `sendWhatsapp`, `sendNotification` - **CRM:** `moveToFolder`, `addTag`, `removeTag`, `changeStatus`, `shareWithUser`, `addMission`, `reminder` - **Documents / orders:** `create_doc`, order-related actions - **Control:** `if`, `ai_agent` - **Integrations:** `apiCall`, webhooks, etc.

7. Event triggers catalog

**All trigger types, form fields, delay rules, parameter types:** → include_file/AUTOMATION_EVENT_TYPES.md

Save endpoint: `POST dashboard/event/add_automation_event` Canvas link: each table row → `dashboard/event/automation/{id}`

8. Permissions

- Module: `module_sidebarmenu_automation` (sidebar link) - Create/edit: `allowed_to_add_automations` **or** owner / `member_admin` - See PERMISSIONS_MAP.md §D1

9. AI integration (three layers)

| Layer | What | Doc |

|-------|------|-----|

| **Event AI chat** | Draft trigger form on automation-table | AUTOMATION_AI_BUILDER.md § Event AI |

| **Canvas AI chat** | Draft action nodes on canvas | AUTOMATION_AI_BUILDER.md |

| **`ai_agent` step** | AI inside a running flow | AI_AGENT_FUNCTIONALITY.md |

| **Sidebar agent** | Natural language “create automation” from anywhere | BIZ1_SIDEBAR_AGENT.md |

10. Key files

| File | Role |

|------|------|

| `include_file/automations.php` | Engine, loops, dispatcher |

| `include_file/automations_functions.php` | Helpers, queues, AI builders, IF runtime |

| `include_file/automations/actions/*.inc.php` | One file per action type |

| `application/controllers/Event.php` | Table, canvas, save, AI draft APIs |

| `application/views/new-design/automation-table.php` | Event list + event AI chat |

| `application/views/automation.php` | Canvas + action AI chat |

| `application/views/include/jquery_margi.php` | Event table JS (legacy submit) |

| `new/js/project-general-js/automations-tables-jquery-v2.js` | Table v2 JS |

11. Logs & debugging

- Automation run issues: check org `automation_event.automation_status`, action row `type` + `parameter` - AI builder: OpenRouter via `sendPrompt()` — model `google/gemini-3-flash-preview` - Runtime `ai_agent`: direct Gemini API key from env / `$GLOBALS['public']`

12. Related docs

- AI_AND_AUTOMATION_INDEX.md — master index - AUTOMATIONS_CHANGES.md — refactor changelog - SETTINGS_MAP.md — automation-related settings modals