Skip to main content

Approval Workflows

Overview​

The OWL AI Platform implements a sophisticated multi-level approval workflow system that routes AI agent actions to appropriate approvers based on risk scores, organizational hierarchy, and policy requirements. The system ensures high-risk actions receive proper oversight while maintaining operational efficiency through automated escalation and SLA tracking.

Key Capabilities​

  • Risk-Based Routing: Automatically routes actions to appropriate approval levels based on risk score
  • Multi-Level Hierarchy: Supports L1-L4+ approval chains for enterprise governance
  • SLA Escalation: Automatic escalation when approvals exceed time limits
  • Backup Approvers: Maintains approver chains for availability coverage
  • Emergency Override: Allows authorized personnel to bypass standard workflows
  • Department-Aware: Routes to approvers with relevant domain expertise
  • Audit Trail: Complete history of all approval decisions and reasoning

How It Works​

Approval Level Matrix​

Risk LevelScore RangeRequired LevelTypical ApproversSLA
Minimal0-24Auto-Approve (L0)SystemImmediate
Low25-44L1Team Lead / Peer5 min
Medium45-69L2Manager15 min
High70-84L3Director / Senior Manager30 min
Critical85-100L4VP / Executive60 min

Approval Workflow Architecture​

                         ┌─────────────────────────────────────────┐
                         │          ACTION SUBMITTED               │
                         │  (Risk Score: 72, Level: HIGH)          │
                         └─────────────────┬───────────────────────┘
                                           │
                                           v
                         ┌─────────────────────────────────────────┐
                         │         APPROVER ASSIGNMENT             │
                         │  - Find qualified approvers (L3+)       │
                         │  - Filter by department                 │
                         │  - Check availability                   │
                         │  - Assign primary + 2 backups           │
                         └─────────────────┬───────────────────────┘
                                           │
                                           v
           ┌───────────────────────────────┼───────────────────────────────┐
           │                               │                               │
           v                               v                               v
┌──────────────────────┐     ┌──────────────────────┐     ┌──────────────────────┐
│   PRIMARY APPROVER   │     │   BACKUP APPROVER 1  │     │   BACKUP APPROVER 2  │
│   john@company.com   │     │   jane@company.com   │     │   bob@company.com    │
│   Level: L3 Director │     │   Level: L3 Director │     │   Level: L4 VP       │
│   Dept: Engineering  │     │   Dept: Engineering  │     │   Dept: Engineering  │
└──────────┬───────────┘     └──────────────────────┘     └──────────────────────┘
           │
           │ ← Notification sent
           v
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              APPROVAL PENDING                                    │
│                                                                                  │
│  Action: Delete customer_records table                                          │
│  Risk Score: 72 (HIGH)                                                          │
│  Agent: data-cleanup-agent                                                      │
│  Environment: Production                                                         │
│                                                                                  │
│  SLA: 30 minutes (Expires: 2:30 PM)                                             │
│                                                                                  │
│  [APPROVE]  [DENY]  [ESCALATE]  [REQUEST INFO]                                  │
└─────────────────────────────────────────────────────────────────────────────────┘
           │
           │
           v
    ┌──────────────┐          ┌──────────────┐          ┌──────────────┐
    │   APPROVED   │          │    DENIED    │          │  ESCALATED   │
    │  → Execute   │          │  → Block     │          │  → L4 Review │
    │  → Audit Log │          │  → Notify    │          │  → Reset SLA │
    └──────────────┘          └──────────────┘          └──────────────┘

Approver Selection Algorithm​

The Workflow Approver Service selects approvers using the following criteria:

  1. Minimum Approval Level: Approver must have sufficient authority for the risk level
  2. Department Match: Prefer approvers from the same department as the action
  3. Availability: Check for active status and capacity
  4. Load Balancing: Distribute approvals evenly across qualified approvers
  5. Escalation Path: Maintain backup chain for SLA management
# Approver selection example
from services.workflow_approver_service import workflow_approver_service

result = workflow_approver_service.assign_approvers_to_workflow(
    db=db,
    workflow_execution_id=12345,
    action_id=67890,
    risk_score=72.5,
    required_approval_level=3,  # L3 for HIGH risk
    department="Engineering"
)

# Result:
# {
#   "primary": {
#     "email": "john@company.com",
#     "approval_level": 3,
#     "department": "Engineering"
#   },
#   "backups": [
#     {"email": "jane@company.com", "approval_level": 3, "department": "Engineering"},
#     {"email": "bob@company.com", "approval_level": 4, "department": "Engineering"}
#   ],
#   "total_available": 5
# }

Configuration​

Approval Level Thresholds​

Configure which risk scores require which approval levels:

{
  "approval_thresholds": {
    "auto_approve": {"max_risk": 24},
    "L1": {"min_risk": 25, "max_risk": 44, "sla_minutes": 5},
    "L2": {"min_risk": 45, "max_risk": 69, "sla_minutes": 15},
    "L3": {"min_risk": 70, "max_risk": 84, "sla_minutes": 30},
    "L4": {"min_risk": 85, "max_risk": 100, "sla_minutes": 60}
  }
}

SLA Escalation Settings​

{
  "escalation_settings": {
    "enabled": true,
    "escalation_percentage": 80,
    "notify_on_escalation": true,
    "max_escalation_level": "L4",
    "emergency_override_enabled": true
  }
}

Department Mapping​

{
  "department_approval_mapping": {
    "Engineering": ["engineering-leads", "platform-directors"],
    "Security": ["security-team", "ciso-office"],
    "Data": ["data-governance", "data-directors"],
    "Finance": ["finance-leads", "cfo-office"]
  }
}

Usage Examples​

Submit Action for Approval (Python SDK)​

from owlai import OWLClient

client = OWLClient(api_key="your_api_key")

# Submit high-risk action
response = client.actions.submit(
    agent_id="data-processor",
    action_type="delete",
    target_resource="customer_records",
    environment="production",
    description="Delete inactive customer records older than 7 years",
    metadata={
        "record_count": 15000,
        "compliance_reason": "GDPR data retention policy"
    }
)

print(f"Action ID: {response.action_id}")
print(f"Status: {response.status}")
print(f"Risk Score: {response.risk_score}")
print(f"Approval Level Required: {response.approval_level}")
print(f"Assigned Approver: {response.pending_approver}")
print(f"SLA Deadline: {response.sla_deadline}")

# Output:
# Action ID: act_12345
# Status: pending_approval
# Risk Score: 78
# Approval Level Required: L3
# Assigned Approver: john@company.com
# SLA Deadline: 2026-01-20T14:30:00Z

Approve or Deny Action​

# As an approver, approve the action
client.actions.approve(
    action_id="act_12345",
    comment="Approved per GDPR compliance requirements. Verified backup exists.",
    conditions=["Confirm backup completed before execution"]
)

# Or deny with reason
client.actions.deny(
    action_id="act_12345",
    reason="Missing data backup verification. Please provide backup confirmation."
)

Check Approval Status​

curl -X GET https://api.owlai.io/v1/actions/act_12345/approval-status \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "action_id": "act_12345",
#   "status": "pending_approval",
#   "risk_score": 78,
#   "required_level": "L3",
#   "current_approver": "john@company.com",
#   "backup_approvers": ["jane@company.com", "bob@company.com"],
#   "sla_deadline": "2026-01-20T14:30:00Z",
#   "sla_remaining_seconds": 1200,
#   "escalation_at": "2026-01-20T14:24:00Z",
#   "approval_history": []
# }

Emergency Override​

For time-critical situations, authorized users can invoke emergency override:

# Emergency override (requires elevated permissions)
client.actions.emergency_override(
    action_id="act_12345",
    override_reason="Critical production incident - immediate data cleanup required",
    incident_ticket="INC-2026-0120-001"
)

Emergency overrides:

  • Bypass standard approval workflow
  • Require incident ticket reference
  • Generate enhanced audit trail
  • Trigger security team notification
  • Subject to post-incident review

Reassign Approver​

If primary approver is unavailable:

from services.workflow_approver_service import workflow_approver_service

# Reassign when approver is unavailable
new_approver = workflow_approver_service.reassign_on_unavailable(
    db=db,
    action_id=67890,
    unavailable_email="john@company.com"
)

print(f"Reassigned to: {new_approver}")
# Output: Reassigned to: jane@company.com

SLA Escalation​

Automatic Escalation Flow​

Time 0:00    → Action submitted, assigned to L3 approver
             │
Time 24:00   → 80% of SLA elapsed
             │  ├─ Send reminder to primary approver
             │  └─ Alert backup approvers
             │
Time 30:00   → SLA breached
             │  ├─ Escalate to L4 (next level)
             │  ├─ Reset SLA timer (60 min for L4)
             │  └─ Notify management
             │
Time 90:00   → L4 SLA breached
                ├─ Final escalation to executive
                └─ Generate compliance alert

Escalation API​

# Get escalation status
curl -X GET https://api.owlai.io/v1/actions/act_12345/escalation \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "current_level": "L3",
#   "original_level": "L3",
#   "escalation_count": 0,
#   "sla_breached": false,
#   "next_escalation_at": "2026-01-20T14:24:00Z",
#   "escalation_path": ["L3", "L4", "Executive"]
# }

# Manually escalate
curl -X POST https://api.owlai.io/v1/actions/act_12345/escalate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Primary approver on PTO, need urgent review",
    "target_level": "L4"
  }'

Approval Queue Management​

View Pending Approvals​

# Get approvals waiting for current user
pending = client.approvals.list_pending(
    status="pending",
    assignee="me",
    sort_by="sla_deadline",
    order="asc"
)

for approval in pending:
    print(f"{approval.action_id}: {approval.description}")
    print(f"  Risk: {approval.risk_score} | SLA: {approval.sla_remaining}")

Bulk Approval​

# Approve multiple low-risk actions at once
client.approvals.bulk_approve(
    action_ids=["act_001", "act_002", "act_003"],
    comment="Batch approval - routine read operations"
)

Audit Trail​

Every approval action is logged:

{
  "audit_entry": {
    "action_id": "act_12345",
    "event_type": "approval_granted",
    "timestamp": "2026-01-20T14:15:00Z",
    "actor": "john@company.com",
    "actor_level": "L3",
    "decision": "approved",
    "comment": "Approved per GDPR compliance requirements",
    "conditions": ["Confirm backup completed before execution"],
    "risk_score_at_decision": 78,
    "sla_status": "within_sla",
    "time_to_decision_seconds": 900
  }
}

Best Practices​

Approval Workflow Design​

  1. Right-size Approval Levels: Match approval requirements to actual risk
  2. Define Clear Escalation Paths: Ensure every level has defined escalation
  3. Maintain Backup Coverage: Always have 2+ backup approvers per level
  4. Monitor SLA Compliance: Track and report on approval times
  5. Review Auto-Approve Thresholds: Regularly audit auto-approved actions

Approver Guidelines​

  1. Review Context: Understand the full action context before deciding
  2. Document Decisions: Always provide meaningful approval comments
  3. Escalate When Unsure: Better to escalate than approve incorrectly
  4. Respond Promptly: Stay within SLA to avoid unnecessary escalations
  5. Use Conditions: Add execution conditions when partial approval is appropriate