#431 App: Multi-Step Approval Chain (approval_chain)

## Overview Sequential and parallel approval workflows with escalation, reminders, and audit trail. ## App Metadata - **App Name:** approval_chain - **Publisher:** platform - **Version:** 1.0.0 - **Priority:** Medium - **Complexity:** Medium - **Phase:** 2 (Core business value) ## Actions ### 1. start_approval **Description:** Initiate a new approval request **Parameters:** - request_title (str, required): Title of approval request - request_details (dict, required): Details to show approvers - approvers (list, required): List of approver configs - email (str): Approver email - role (str): Approver role/title - required (bool): Must approve or can be skipped - timeout_hours (int): Time before escalation - approval_type (str, default='sequential'): Type (sequential|parallel|any) - requester_email (str, required): Person requesting approval - callback_workflow (str, optional): Workflow to trigger on completion **Returns:** { "approval_id": "apr_123", "status": "pending", "current_step": 1, "total_steps": 3, "created_at": "2025-01-01T00:00:00Z", "approval_link": "https://highway.rodmena.app/approve/apr_123" } ### 2. check_status **Description:** Get current approval status **Parameters:** - approval_id (str, required): Approval ID to check **Returns:** { "approval_id": "apr_123", "status": "pending|approved|rejected|expired", "current_step": 2, "decisions": [ {"approver": "a@x.com", "decision": "approved", "at": "...", "comment": "..."} ], "pending_approvers": ["b@x.com"], "time_remaining_hours": 12 } ### 3. escalate **Description:** Escalate pending approval to next level **Parameters:** - approval_id (str, required): Approval to escalate - escalation_email (str, required): Escalation recipient - reason (str, default='timeout'): Escalation reason - original_approver_notified (bool, default=True): Notify original approver **Returns:** {"escalated": true, "new_approver": "...", "escalation_level": 2} ### 4. send_reminder **Description:** Send reminder to pending approvers **Parameters:** - approval_id (str, required): Approval to remind about - custom_message (str, optional): Additional message **Returns:** {"reminders_sent": 2, "recipients": ["a@x.com", "b@x.com"]} ### 5. notify_completion **Description:** Send final notification when approval completes **Parameters:** - approval_id (str, required): Completed approval - notify_requester (bool, default=True): Notify original requester - notify_approvers (bool, default=True): Notify all approvers - additional_recipients (list, optional): Extra notification recipients **Returns:** {"notifications_sent": 5, "final_status": "approved"} ## Example Workflow - Expense Approval Chain builder = WorkflowBuilder(name='expense_approval', version='1.0.0') builder.task( task_id='start_approval', function='apps.platform.approval_chain.start_approval', kwargs={ 'request_title': 'Expense Report #{{expense_id}}', 'request_details': { 'amount': '{{amount}}', 'category': '{{category}}', 'description': '{{description}}' }, 'approvers': [ {'email': 'manager@co.com', 'role': 'Manager', 'timeout_hours': 24}, {'email': 'finance@co.com', 'role': 'Finance', 'timeout_hours': 48} ], 'approval_type': 'sequential', 'requester_email': '{{requester_email}}' }, result_key='approval_started' ) ## Approval Types Explained - **sequential**: Each approver in order, stops on rejection - **parallel**: All approvers notified at once, waits for all - **any**: All notified, first response decides ## Implementation Notes - Extend existing approval_email app - Store approval state in highway.approval_requests table - Use durable workflows for timeout/escalation handling - Generate unique approval links with tokens - Build simple approval UI (approve/reject with comment) ## Database Schema Addition CREATE TABLE highway.approval_requests ( approval_id UUID PRIMARY KEY, tenant_id VARCHAR NOT NULL, request_title VARCHAR NOT NULL, request_details JSONB, approvers JSONB, decisions JSONB DEFAULT '[]', status VARCHAR DEFAULT 'pending', approval_type VARCHAR DEFAULT 'sequential', current_step INT DEFAULT 1, requester_email VARCHAR, created_at TIMESTAMPTZ DEFAULT NOW(), expires_at TIMESTAMPTZ, completed_at TIMESTAMPTZ ); ## Configuration Schema { "default_timeout_hours": 48, "max_approvers": 10, "reminder_interval_hours": 24, "approval_link_base_url": "https://highway.rodmena.app/approve" } ## Secrets Config None (uses existing SMTP for emails) ## Dependencies - Existing approval_email app (extend or replace) - Database table for state - Email sending (SMTP)