bmc_hub/docs/EMAIL_RULES_TO_WORKFLOWS_MIGRATION.md

Email Rules → Workflows Migration Guide

🎯 Formål

BMC Hub er ved at phase out det gamle Rules system til fordel for det nyere og mere kraftfulde Workflows system.

Status:

• ✅ Workflows er default aktiveret (EMAIL_WORKFLOWS_ENABLED=true)
• ⚠️ Rules er nu disabled by default (EMAIL_RULES_ENABLED=false)

🔄 Hvad Er Ændret?

I koden:

1. Koordinering tilføjet: Workflows kører først, rules kun hvis workflow ikke har processed emailen
2. Deduplication: Samme action køres ikke 2 gange
3. Config ændring: EMAIL_RULES_ENABLED er nu false by default
4. Silent failures fixet: extract_invoice_data fejler nu synligt hvis fil mangler

I .env:

# Gammelt (deprecated):
EMAIL_RULES_ENABLED=true
EMAIL_RULES_AUTO_PROCESS=false

# Nyt (anbefalet):
EMAIL_WORKFLOWS_ENABLED=true
EMAIL_RULES_ENABLED=false

📋 Migration Steps

Trin 1: Identificer Aktive Rules

-- Se alle aktive rules
SELECT id, name, action_type, conditions, priority, match_count 
FROM email_rules 
WHERE enabled = true 
ORDER BY priority ASC;

Trin 2: Opret Tilsvarende Workflows

For hver rule, opret en workflow:

Eksempel: Rule → Workflow

Gammel Rule:

{
  "name": "Link Supplier Invoices",
  "conditions": {
    "classification": "invoice",
    "sender_domain": ["example.com", "vendor.dk"]
  },
  "action_type": "link_supplier",
  "priority": 10
}

Ny Workflow:

INSERT INTO email_workflows (
  name, 
  description,
  classification_trigger,
  sender_pattern,
  confidence_threshold,
  workflow_steps,
  priority,
  enabled
) VALUES (
  'Link Supplier Invoices',
  'Automatically link invoice emails from known suppliers',
  'invoice',
  '(example\\.com|vendor\\.dk)$',  -- Regex pattern
  0.70,
  '[
    {"action": "link_to_vendor", "params": {"match_by": "email"}},
    {"action": "extract_invoice_data", "params": {}},
    {"action": "mark_as_processed", "params": {}}
  ]'::jsonb,
  10,
  true
);

Trin 3: Test Workflows

1. Send test email der matcher classification
2. Check email_workflow_executions tabel for results
3. Verificer at email blev processed korrekt

-- Se workflow executions
SELECT 
  e.id,
  w.name as workflow_name,
  em.subject,
  e.status,
  e.steps_completed,
  e.execution_time_ms,
  e.started_at
FROM email_workflow_executions e
JOIN email_workflows w ON w.id = e.workflow_id
JOIN email_messages em ON em.id = e.email_id
ORDER BY e.started_at DESC
LIMIT 20;

Trin 4: Disable Rules

-- Disable alle rules
UPDATE email_rules SET enabled = false;

Eller i .env:

EMAIL_RULES_ENABLED=false

Trin 5: Monitor

I de første dage efter migration:

• Check logs for fejl
• Verificer at workflows kører som forventet
• Check at ingen emails falder igennem

🗂️ Mapping: Rules → Workflows

Action Mapping

Rule Action	Workflow Action	Notes
link_supplier	link_to_vendor	✅ Direct replacement
link_customer	link_to_customer	⚠️ Not fully implemented yet
link_case	create_ticket	✅ Creates ticket from email
mark_spam	(none)	⚠️ Needs workflow action
create_purchase	(none)	⚠️ Not implemented

Condition Mapping

Rule Condition	Workflow Equivalent
classification	classification_trigger
sender_email	sender_pattern (exact match regex)
sender_domain	sender_pattern (domain regex)
subject_contains	subject_pattern (contains regex)
subject_regex	subject_pattern (direct)
confidence_score	confidence_threshold

🆕 Workflow-Only Features

Workflows kan mere end rules:

1. Multi-step execution: Chain multiple actions
2. Better error handling: Each step tracked separately
3. Execution history: Full audit trail
4. Regex patterns: More flexible matching
5. Stop on match: Control workflow chaining
6. Statistics: Success/failure rates

⚠️ Backward Compatibility

Hvis du MÅ beholde rules:

Set i .env:

EMAIL_RULES_ENABLED=true
EMAIL_WORKFLOWS_ENABLED=true

Systemet vil:

• Køre workflows først
• Kun køre rules hvis workflow ikke processede emailen
• Undgå duplicate actions

Men dette er ikke anbefalet - rules vil blive fjernet i fremtiden.

📊 Status Dashboard

Tilføj til admin UI:

-- Workflow statistics
SELECT 
  w.name,
  w.classification_trigger,
  w.execution_count,
  w.success_count,
  w.failure_count,
  ROUND(100.0 * w.success_count / NULLIF(w.execution_count, 0), 1) as success_rate,
  w.last_executed_at
FROM email_workflows w
WHERE w.enabled = true
ORDER BY w.execution_count DESC;

🐛 Troubleshooting

"Workflow ikke executed"

Check:

1. Er EMAIL_WORKFLOWS_ENABLED=true i .env?
2. Er workflow enabled i database?
3. Matcher classification_trigger?
4. Er confidence over threshold?
5. Matcher sender/subject patterns?

Debug:

# I logs se:
# "🔄 Finding workflows for classification: invoice (confidence: 0.95)"
# "📋 Found X matching workflow(s)"

"Email processed 2 gange"

Check:

1. Er både workflows OG rules enabled?
2. Har de samme actions?

Fix: Disable rules: EMAIL_RULES_ENABLED=false

"Workflow fejler stille"

Efter fix:

• extract_invoice_data raiser nu FileNotFoundError hvis PDF mangler
• Check email_workflow_executions.status = 'failed'
• Check error_message column

✅ Success Criteria

Migration er komplet når:

1. ✅ Alle rules er migrated til workflows
2. ✅ Workflows tested og virker
3. ✅ EMAIL_RULES_ENABLED=false i produktion
4. ✅ Ingen emails falder igennem
5. ✅ email_workflow_executions viser success

📞 Support

Hvis problemer:

1. Check logs: docker-compose logs -f api | grep "🔄\|❌\|✅"
2. Check database: SELECT * FROM email_workflow_executions ORDER BY started_at DESC LIMIT 10;
3. Revert: Set EMAIL_RULES_ENABLED=true midlertidigt

---

Tidslinje:

• ✅ Nu: Workflows aktiveret, rules disabled by default
• 🔜 Næste sprint: Fjern rule UI fra admin
• 🔜 Om 1 måned: Drop email_rules tabel helt

Anbefaling: Migrer nu, imens begge systemer er tilgængelige som fallback.