bmc_hub/docs/WORKFLOW_SYSTEM_GUIDE.md

# Email Workflow System - Brugervejledning

## Oversigt

Email Workflow System automatiserer behandling af emails baseret på AI classification. Workflows består af multiple steps der udføres sekventielt når en email matcher specifikke kriterier.

## 🚀 Quick Start

### 1. Åbn Workflow Manager
Klik på "Workflow Management" knappen i email UI'et

### 2. Opret Workflow
Tre måder:
- **Fra Template**: Klik "Templates" og vælg en forudbygget workflow
- **Fra Scratch**: Klik "Ny Workflow" og byg selv
- **Dupliker Eksisterende**: Klik "Dupliker" på en eksisterende workflow

### 3. Konfigurer Workflow

#### Basis Information
- **Navn**: Beskrivende navn (fx "Leverandør Faktura Processing")
- **Beskrivelse**: Detaljeret formål
- **Classification Trigger**: Hvilken email type der trigger workflow
- **Confidence Threshold**: Minimum AI confidence (0.60-0.80 anbefalet)
- **Prioritet**: Lavere tal = højere prioritet (10 = meget høj)

#### Workflow Steps
Tilføj actions i den rækkefølge de skal udføres:
1. Klik "Tilføj Step"
2. Vælg action type fra dropdown
3. Konfigurer action parameters
4. Brug drag-and-drop til at ændre rækkefølge

### 4. Test Workflow
Klik "Test Workflow" før du gemmer for at verificere funktionalitet

### 5. Gem og Aktiver
Klik "Gem" og sørg for at enable switch er tændt

## 📋 Tilgængelige Actions

### Linking Actions
Link emails til eksisterende data:

```json
{
  "action": "link_to_vendor",
  "params": { "match_by": "email" }
}
```

```json
{
  "action": "link_to_customer",
  "params": {}
}
```

### Data Extraction
Ekstraher data fra emails/attachments:

```json
{
  "action": "extract_invoice_data",
  "params": {}
}
```

```json
{
  "action": "extract_tracking_number",
  "params": { "pattern": "CC[0-9]{4}" }
}
```

### Ticket/Case Creation
Opret tickets automatisk:

```json
{
  "action": "create_ticket",
  "params": {
    "module": "support_cases",
    "priority": "normal"
  }
}
```

```json
{
  "action": "create_time_entry",
  "params": {}
}
```

### Notifications
Send notifikationer:

```json
{
  "action": "send_slack_notification",
  "params": {
    "channel": "#alerts",
    "message": "🚨 Vigtig email modtaget"
  }
}
```

### Processing Control
Styr email status:

```json
{
  "action": "mark_as_processed",
  "params": {}
}
```

```json
{
  "action": "flag_for_review",
  "params": { "reason": "needs_manual_review" }
}
```

## 🎯 Workflow Templates

### Invoice Processing
Automatisk behandling af leverandør fakturaer:
- Link til vendor
- Ekstraher faktura data
- Marker som processed

**Classification**: `invoice`  
**Confidence**: 0.70  
**Priority**: 50

### Time Confirmation
Auto-link time confirmations til sager:
- Ekstraher CC#### nummer
- Opret ticket
- Marker som processed

**Classification**: `time_confirmation`  
**Confidence**: 0.60  
**Priority**: 30

### Spam Handler
Håndter spam emails:
- Flag for review
- Marker som processed

**Classification**: `spam`  
**Confidence**: 0.80  
**Priority**: 10

### Freight Note
Behandl fragtbreve:
- Ekstraher tracking nummer
- Link til kunde
- Marker som processed

**Classification**: `freight_note`  
**Confidence**: 0.65  
**Priority**: 40

### Bankruptcy Alert
Alert ved konkurs emails:
- Send Slack notifikation
- Flag for review
- Marker som processed

**Classification**: `bankruptcy`  
**Confidence**: 0.75  
**Priority**: 5

### Low Confidence Review
Fang emails med lav confidence:
- Flag for manuel review

**Classification**: `general`  
**Confidence**: 0.30  
**Priority**: 200

## 🔧 Advanced Features

### Import/Export
**Export**: Download workflow som JSON fil (del med andre systemer)  
**Import**: Upload JSON workflow fil

### Duplicate
Kopier eksisterende workflow og tilpas - spar tid!

### Test Mode
Test workflow på specifik email uden at gemme ændringer

### JSON Editor
Switch til JSON view for direkte editing af workflow configuration

### Drag & Drop
Omarranger workflow steps ved at trække i dem

## 📊 Monitoring

### Execution History
Se alle workflow executions med:
- Status (completed/failed)
- Execution time
- Steps completed
- Error messages

### Statistics
Per-workflow stats:
- Total executions
- Success rate
- Failure count
- Last executed

### Debugging
Hvis workflow fejler:
1. Tjek execution history for error message
2. Verificer action parameters
3. Test workflow på sample email
4. Tjek confidence threshold

## ⚙️ Best Practices

### Prioritering
- **1-20**: Kritiske workflows (bankruptcy alerts, spam)
- **21-50**: Almindelige workflows (invoices, time confirmations)
- **51-100**: Low-priority workflows
- **100+**: Catch-all workflows

### Confidence Thresholds
- **0.80+**: Kun meget sikre matches
- **0.70-0.80**: Standard range (anbefalet)
- **0.60-0.70**: Acceptér mere usikkerhed
- **<0.60**: Kun til catch-all workflows

### Workflow Design
1. **Start med linking**: Link til vendor/customer først
2. **Extract data**: Hent data fra attachments
3. **Create tickets**: Opret tickets hvis nødvendigt
4. **Notify**: Send notifikationer
5. **Cleanup**: Marker som processed til sidst

### Testing
- Test altid nye workflows på sample emails
- Start med `enabled = false` og test grundigt
- Monitor execution history i de første dage
- Juster confidence threshold baseret på resultater

## 🚨 Common Issues

### Workflow kører ikke
- Tjek om workflow er enabled
- Verificer classification trigger matcher email classification
- Tjek confidence threshold (for høj?)
- Se om højere prioritet workflow har `stop_on_match = true`

### Action fejler
- Tjek execution history for error message
- Verificer action parameters er korrekte
- Tjek om required data er tilgængelig (fx PDF attachment)
- Test action individuelt

### Duplikering af actions
- Workflows med `stop_on_match = true` stopper andre workflows
- Tjek om flere workflows matcher samme email
- Brug prioritering til at styre rækkefølge

## 🔄 Migration fra Rules

Email Rules systemet er deprecated. Migrer til workflows:

1. Identificer aktive rules
2. Opret tilsvarende workflow (brug templates som udgangspunkt)
3. Test workflow grundigt
4. Disable original rule
5. Monitor execution history

Se `/docs/EMAIL_RULES_TO_WORKFLOWS_MIGRATION.md` for detaljer.

## 📚 Yderligere Dokumentation

- **Actions Reference**: Klik "Quick Guide" i Actions tab
- **Architecture**: Se `app/services/email_workflow_service.py`
- **API Endpoints**: `/api/docs` for komplet API reference
- **Migration Guide**: `/docs/EMAIL_RULES_TO_WORKFLOWS_MIGRATION.md`

## 💡 Tips & Tricks

### Template Modificering
Start med template og tilpas:
1. Vælg template der ligner din use case
2. Rediger navn og beskrivelse
3. Tilføj/fjern steps efter behov
4. Juster confidence og prioritet
5. Test og gem

### Multi-Step Workflows
Build komplekse workflows:
```
Step 1: Link to vendor
Step 2: Extract invoice data
Step 3: Create case if amount > 10000
Step 4: Send Slack notification
Step 5: Mark as processed
```

### Conditional Logic
Brug parameters til at styre adfærd:
```json
{
  "action": "create_ticket",
  "params": {
    "priority": "high",
    "assign_to": "billing_team",
    "condition": { "amount": { "gt": 50000 } }
  }
}
```

### Reusable Patterns
Gem ofte brugte step sekvenser som templates

## ❓ Support

Ved problemer:
1. Tjek execution history
2. Se i `/logs/` for detaljerede fejl
3. Test workflow i isolation
4. Kontakt system administrator

---

**Version**: 1.0  
**Last Updated**: 15. december 2025  
**Maintained By**: BMC Hub Development Team