Automation System - Implementation Guide
Complete technical implementation guide for developers working with the automation system.
Backend Infrastructure
AutomationRuleService
Location: apps/api/src/services/automation/AutomationRuleService.ts
475-line comprehensive automation execution engine with:
- Smart ExecutionexecuteRule() with retry logic and exponential backoff
- Health MonitoringTrack success/failure rates, execution statistics
- Dry Run ModeTest rules without executing actions
- Advanced Conditions17 operators: equals, contains, regex, greater/less than, in_list, etc.
- Rule CloningClone with automatic naming and reset statistics
API Routes
Location: apps/api/src/routes/automation-rules.ts
600+ lines of RESTful endpoints with 15+ routes:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/automation-rules | List all rules with filters |
| GET | /api/automation-rules/:id | Get rule details |
| POST | /api/automation-rules | Create new rule |
| PUT | /api/automation-rules/:id | Update rule |
| DELETE | /api/automation-rules/:id | Delete rule |
| PATCH | /api/automation-rules/:id/toggle | Enable/disable rule |
| POST | /api/automation-rules/:id/clone | Clone rule |
| GET | /api/automation-rules/health | Health report |
| GET | /api/automation-rules/needs-attention | Problem rules |
| POST | /api/automation-rules/:id/execute | Manual trigger |
| POST | /api/automation-rules/trigger/:event | Event-based trigger |
Database Schema
Migration: apps/api/src/migrations/1727740800000-EnhanceAutomationRules.ts
Enhancements
- workspaceId ColumnForeign key to workspaces table for multi-tenant isolation
- Statistics TrackinglastSuccessAt, lastFailureAt, lastError columns
- Performance Indexesidx_workspace_active, idx_trigger_active, idx_user
Migration Strategy
- 1. Make workspaceId temporarily nullable
- 2. Populate from workspace_users junction table
- 3. Make column non-nullable
- 4. Add constraints and indexes
Frontend Integration
Type-Safe API Client
Location: apps/web/src/api/automationRules.ts
300 lines of fully typed client with complete type coverage:
listAutomationRules()
getAutomationRule(id)
createAutomationRule(data)
updateAutomationRule(id, data)
deleteAutomationRule(id)
cloneAutomationRule(id, newName?)
toggleAutomationRule(id)
getAutomationHealthReport()
getRulesNeedingAttention()
executeAutomationRule(id)
User Interfaces
| Page | Route | Purpose |
|---|---|---|
| Main Dashboard | /automation | Overview with stats, tabs, recent activity |
| Management Hub | /automation/hub | Full CRUD, health monitoring, clone/toggle/delete |
| Help Documentation | /help/automations | User guides, best practices, quick start |
Testing Checklist
Backend API Tests
- □ Run migration: cd apps/api && npm run migrate
- □ Verify workspaceId populated correctly
- □ Test rule creation via API
- □ Test rule execution with dry run
- □ Test health report generation
- □ Verify workspace isolation
Frontend Integration Tests
- □ Navigate to /automation (should show dashboard)
- □ Navigate to /automation/hub (management interface)
- □ Create new rule from hub
- □ Toggle rule active/inactive
- □ Clone existing rule
- □ Delete rule with confirmation
End-to-End Flow Tests
- □ Pipeline Builder → Add stage automation → Create as Workflow
- □ Verify workflow saved to AutomationRule API
- □ View in Automation Hub
- □ Execute manually and verify action executed