lorentz/wulf-pulse
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
wulf-pulse/docs/workflow-refactoring-complete.md

14 KiB
Raw Permalink Blame History

Workflow Engine Refactoring - Implementation Complete

🎉 Status: Backend & Frontend Complete (9/10 tasks)

✅ All Implementation Tasks Completed

  1. ✅ Migration 036 — Database tables created
  2. ✅ Workflow Step Executors — 7 executors implemented
  3. ✅ Ticket Workflow Engine — Core execution engine
  4. ✅ Webhook Integration — Updated to use new engine
  5. ✅ API Routes — Full REST API for workflows
  6. ✅ Workflow List UI — Master control + workflow cards
  7. ✅ Workflow Editor UI — 4-tab editor (Steps/Trigger/Test/History)
  8. ✅ Step Config Editor — Inline JSON editing (simplified approach)
  9. ✅ Navigation Menu — Reorganized admin dropdown

🧪 Remaining: Testing & Deployment (Task 10)

Quick Start Guide

Step 1: Run the Migration

# Connect to your database
psql -U postgres -d pulse

# Run migration 036
\i /opt/stacks/pulse/migrations/036_create_ticket_workflow_tables.sql

# Verify tables created
\dt ticket_workflow*

# Expected output:
# - ticket_workflows
# - ticket_workflow_steps
# - ticket_workflow_executions
# - ticket_workflow_execution_steps

Step 2: Verify Seed Data

-- Check "Ticket Triage" workflow was seeded
SELECT id, name, is_active, trigger_event FROM ticket_workflows;

-- Check workflow steps (should have 11 steps)
SELECT step_order, step_type, name, is_active
FROM ticket_workflow_steps
WHERE workflow_id = 1
ORDER BY step_order;

Expected steps:

  1. Branch Routing (classify)
  2. Ticket Type (classify)
  3. Issue Classification (classify)
  4. Priority (classify)
  5. Queue Routing (classify)
  6. Validate Classification (validate)
  7. AI Classification (ai_classify) — conditional
  8. AI Title Cleanup (ai_title) — conditional
  9. Delay Before Update (delay)
  10. Update Autotask Ticket (update_ticket)
  11. Generate Troubleshooting Steps (ai_troubleshooting) — conditional

Step 3: Start the Application

# Navigate to project directory
cd /opt/stacks/pulse

# Install dependencies (if needed)
npm install

# Start development server
npm run dev

# Build for production
npm run build
npm start

Step 4: Access the Admin UI

Navigate to: http://localhost:3000/admin/workflow

You should see:

  • Master Control card at top (currently disabled)
  • Ticket Triage workflow card (seeded from migration)
  • Quick links to Classification Rules, AI Templates, Settings

Testing Checklist

✅ Database Testing

  • Migration 036 runs without errors
  • All 4 tables created with correct schema
  • Indexes created successfully
  • Seed data inserted (1 workflow with 11 steps)
  • Foreign key constraints working

✅ API Testing

Test with curl or Postman:

# 1. List all workflows
curl http://localhost:3000/api/ticket-workflows

# 2. Get specific workflow with steps
curl http://localhost:3000/api/ticket-workflows/1

# 3. Update workflow
curl -X PUT http://localhost:3000/api/ticket-workflows/1 \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

# 4. Dry-run test (replace with real ticket ID)
curl -X POST http://localhost:3000/api/ticket-workflows/1/test \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 12345}'

# 5. Get execution history
curl http://localhost:3000/api/ticket-workflows/1/executions

✅ Admin UI Testing

Workflow List Page (/admin/workflow)

  • Master control toggle works
  • Workflow cards display correctly
  • Per-workflow toggles work
  • Step count and execution stats shown
  • "Edit" button navigates to editor
  • Quick links work

Workflow Editor (/admin/workflow/1)

Steps Tab:

  • All 11 seeded steps display
  • Can expand/collapse step config
  • Can reorder steps with up/down arrows
  • Can toggle step on/off
  • Can edit step config (JSON)
  • Can delete steps
  • Can add new steps
  • Save button works

Trigger Tab:

  • Workflow name editable
  • Description editable
  • Trigger event dropdown works
  • Trigger conditions JSON editable
  • Workflow active toggle works
  • Save button works

Test Tab:

  • Shows placeholder for dry-run testing
  • API endpoint documented

History Tab:

  • Shows placeholder for execution history
  • API endpoint documented

Navigation:

  • Admin dropdown shows "Ticket Workflows"
  • Admin dropdown shows "Classification Rules"
  • Admin dropdown shows "AI Templates"
  • Admin dropdown shows "Webhook Pipelines"
  • Admin dropdown shows "Notification Channels"
  • All links navigate correctly

✅ Workflow Engine Testing

Create Test Ticket:

Option A: Use Autotask webhook simulator Option B: Create ticket directly in database

-- Create a test ticket
INSERT INTO tickets (
  id, ticket_number, title, description,
  ticket_category, company_id, status, created_at
) VALUES (
  999999, 'T2026-TEST-001',
  'Test ticket for workflow engine',
  'This is a test ticket to verify the workflow engine',
  3, -- NOC category (eligible for triage)
  29682833, -- valid company_id
  1, -- New
  NOW()
);

Trigger Workflow Manually:

// In Node.js console or API route
import { ticketWorkflowEngine } from '@/lib/services/ticket-workflow-engine';

const ticket = {
  id: 999999,
  ticket_number: 'T2026-TEST-001',
  title: 'Test ticket for workflow engine',
  description: 'This is a test ticket',
  ticket_category: 3,
  ticket_type: null,
  priority: null,
  queue_id: null,
  issue_type: null,
  sub_issue_type: null,
  company_id: 29682833,
  // ... other fields
};

await ticketWorkflowEngine.processTrigger('ticket.created', ticket);

Verify Execution:

-- Check execution record
SELECT * FROM ticket_workflow_executions WHERE ticket_id = 999999;

-- Check execution steps
SELECT
  step_order, step_type, step_name, status, duration_ms,
  error_message, output_data
FROM ticket_workflow_execution_steps
WHERE execution_id = (
  SELECT id FROM ticket_workflow_executions WHERE ticket_id = 999999
)
ORDER BY step_order;

-- Check field changes
SELECT context, field_changes
FROM ticket_workflow_executions
WHERE ticket_id = 999999;

✅ Integration Testing

Webhook Flow:

  1. Enable master switch in UI (/admin/workflow)
  2. Enable "Ticket Triage" workflow
  3. Create ticket via Autotask webhook
  4. Verify execution in database
  5. Check Autotask ticket for updates

Dry-Run Testing:

  1. Select recent ticket in Test tab
  2. Run dry-run
  3. Verify proposed changes shown
  4. Verify no actual Autotask update made

Comparison with Old Engine:

  1. Run 100 tickets through old engine (keep results)
  2. Run same 100 tickets through new engine (dry-run)
  3. Compare classifications
  4. Expect >99% match rate

File Summary

Created Files (21 total)

Database:

  • migrations/036_create_ticket_workflow_tables.sql

Types:

  • lib/types/ticket-workflow.ts

Backend Services:

  • lib/services/ticket-workflow-engine.ts
  • lib/services/workflow-steps/classify.ts
  • lib/services/workflow-steps/validate.ts
  • lib/services/workflow-steps/ai-classify.ts
  • lib/services/workflow-steps/ai-title.ts
  • lib/services/workflow-steps/ai-troubleshooting.ts
  • lib/services/workflow-steps/delay.ts
  • lib/services/workflow-steps/update-ticket.ts
  • lib/services/workflow-steps/index.ts

API Routes:

  • app/api/ticket-workflows/route.ts
  • app/api/ticket-workflows/[id]/route.ts
  • app/api/ticket-workflows/[id]/steps/route.ts
  • app/api/ticket-workflows/[id]/test/route.ts
  • app/api/ticket-workflows/[id]/executions/route.ts

Admin UI:

  • app/admin/workflow/page.tsx (workflow list)
  • app/admin/workflow/[id]/page.tsx (workflow editor)

Documentation:

  • docs/workflow-refactoring-progress.md
  • docs/workflow-refactoring-complete.md (this file)

Modified Files (2 total)

  • lib/services/webhook-service.ts (added ticket workflow engine integration)
  • components/navigation/app-navigation.tsx (reorganized admin menu)

Deployment Plan

Phase 1: Staging Deployment (Current)

  1. Deploy Backend:

    • Run migration 036
    • Deploy updated code
    • Verify services start without errors

  2. Smoke Test:

    • Access admin UI
    • Verify workflow list loads
    • Verify workflow editor loads
    • Test dry-run endpoint

  3. Functional Test:

    • Create test ticket
    • Trigger workflow manually
    • Verify execution in database
    • Check for errors

  4. Parallel Run:

    • Keep old engine enabled (commented line in webhook-service.ts)
    • Enable new engine
    • Compare results for 3-7 days
    • Monitor for discrepancies

Phase 2: Production Deployment

Prerequisites:

  • Staging tests pass (>99% match with old engine)
  • No errors in execution logs
  • Performance acceptable (<1s avg execution time)
  • Admin UI stable and functional

Deployment Steps:

  1. Run migration 036 in production
  2. Deploy code (new engine runs alongside old)
  3. Monitor for 7 days
  4. If successful, disable old engine
  5. Monitor for another 7 days

Rollback Plan:

  • Disable master switch in admin UI (immediate)
  • Comment out ticketWorkflowEngine.processTrigger() in webhook-service.ts
  • Uncomment old workflowEngine.process() call
  • Redeploy

Phase 3: Deprecation (After 30 days)

  • Mark old workflow-engine.ts as deprecated
  • Archive old workflow_executions and workflow_execution_steps tables
  • Remove old engine code after 6 months
  • Remove old tables after 1 year (with backup)

Troubleshooting

Migration Fails

Error: "relation already exists"

  • Tables may exist from previous attempt
  • Check: SELECT * FROM ticket_workflows;
  • Solution: Drop tables and re-run, or use IF NOT EXISTS pattern (already in migration)

Error: "column does not exist"

  • Check table schema matches migration
  • Verify no column name typos

API Returns 500 Error

Check server logs:

# Development
npm run dev
# Look for [API] errors in console

# Production
pm2 logs pulse

Common issues:

  • Database connection failed → Check DATABASE_URL
  • Missing import → Check file paths and exports
  • Type mismatch → Check TypeScript types

Workflow Not Executing

Check master switch:

SELECT key, value FROM workflow_settings WHERE key = 'workflow_engine_enabled';

Check workflow is active:

SELECT id, name, is_active FROM ticket_workflows WHERE id = 1;

Check trigger conditions:

  • Verify ticket matches trigger_conditions
  • Check ticket.ticket_category is in [2, 3, 159, 161]
  • Check ticket.creator_resource_id not in exclusion list

Check logs:

# Look for [TICKET-WORKFLOW] messages
grep -i "ticket-workflow" logs/*.log

Steps Not Executing

Check step is active:

SELECT step_order, name, is_active FROM ticket_workflow_steps WHERE workflow_id = 1;

Check step condition:

  • If step has condition, verify it evaluates to true
  • Check context has required fields

Check for errors:

SELECT step_order, step_name, status, error_message
FROM ticket_workflow_execution_steps
WHERE execution_id = ?;

Performance Metrics

Target Performance:

  • Workflow execution: <1s for robotic classification
  • Workflow execution: <3s for hybrid (with AI)
  • API response time: <500ms for list endpoints
  • Admin UI load time: <2s

Monitoring Queries:

-- Average execution time
SELECT
  AVG(duration_ms) as avg_ms,
  MAX(duration_ms) as max_ms,
  MIN(duration_ms) as min_ms
FROM ticket_workflow_executions
WHERE created_at > NOW() - INTERVAL '24 hours';

-- Success rate
SELECT
  status,
  COUNT(*) as count,
  ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) as percentage
FROM ticket_workflow_executions
WHERE created_at > NOW() - INTERVAL '24 hours'
GROUP BY status;

-- Classification method breakdown
SELECT
  classification_method,
  COUNT(*) as count
FROM ticket_workflow_executions
WHERE created_at > NOW() - INTERVAL '24 hours'
  AND status = 'completed'
GROUP BY classification_method;

Support & Documentation

For Issues:

  1. Check this troubleshooting guide
  2. Review server logs
  3. Check database execution records
  4. Review docs/webhook-pipeline-engine.md for similar patterns

For Questions:

  1. Refer to docs/workflow-refactoring-progress.md for architecture details
  2. Review type definitions in lib/types/ticket-workflow.ts
  3. Check step executor code in lib/services/workflow-steps/

For Development:

  1. TypeScript types are fully defined
  2. All services are singleton exports
  3. Follow existing patterns in pipeline engine
  4. Use toast for user feedback in UI
  5. Use console.log with [TICKET-WORKFLOW] prefix for logging

Success Criteria

✅ Implementation Complete When:

  • All database tables created
  • All step executors implemented
  • Workflow engine processes tickets
  • Webhook integration updated
  • API routes functional
  • Admin UI accessible and functional

✅ Ready for Production When:

  • All tests pass
  • Parallel run shows >99% match
  • No errors in execution logs
  • Performance metrics within targets
  • Admin UI stable (no crashes)

Next Steps

  1. Run Migration — Execute 036 on dev database
  2. Start Application — Test locally
  3. Test Admin UI — Verify all pages work
  4. Test API — Run curl commands
  5. Test Workflow — Create test ticket
  6. Monitor Logs — Check for errors
  7. Compare Results — Verify match with old engine
  8. Deploy to Staging — If tests pass
  9. Monitor Staging — 3-7 days
  10. Deploy to Production — If staging stable

Implementation completed on: February 20, 2026 Total implementation time: ~2 hours Files created: 21 Files modified: 2 Lines of code: ~3500