workforce-pay-bill-p/WORKFLOW_TEMPLATES.md

Approval Workflow Templates

Overview

The Approval Workflow Templates system provides a flexible, configurable framework for managing multi-step approval processes across different batch types in WorkForce Pro. This system allows administrators to define, customize, and manage approval workflows that can be applied to payroll batches, invoices, timesheets, expenses, compliance documents, and purchase orders.

Key Features

1. Template Management

• Create Templates: Define reusable approval workflows for different batch types
• Edit Templates: Modify existing templates including steps, approvers, and rules
• Duplicate Templates: Clone templates to create variations quickly
• Delete Templates: Remove unused or obsolete templates
• Active/Inactive Status: Enable or disable templates without deletion
• Default Templates: Set default workflows for each batch type

2. Multi-Step Approval Workflows

Each template can contain multiple approval steps executed sequentially:

• Step Order: Define the sequence of approval steps
• Approver Roles: Assign specific roles responsible for each step
• Step Descriptions: Add context and instructions for approvers
• Required Comments: Force approvers to provide justification
• Skippable Steps: Allow conditional bypassing of steps

3. Escalation Rules

Prevent bottlenecks with automatic escalation:

• Time-Based Escalation: Escalate to senior roles after specified hours
• Escalation Targets: Define which role receives escalated approvals
• Original Approver Notification: Keep initial approvers informed
• Multiple Escalation Tiers: Chain escalations for critical processes

4. Conditional Logic

Smart workflows that adapt to batch characteristics:

• Skip Conditions: Automatically skip steps based on field values
• Auto-Approval Conditions: Approve steps automatically when criteria are met
• Field Operators: Support for equals, greater than, less than, contains, not equals
• Compound Logic: Combine conditions with AND/OR operators

5. Batch Type Support

Preconfigured templates for six core batch types:

• Payroll: Multi-step approval with finance oversight
• Invoice: Single or multi-tier approval based on amount
• Timesheet: Quick approval with optional manager review
• Expense: Two-step approval with finance authorization
• Compliance: Rigorous approval with legal review
• Purchase Order: Budget and finance approval workflows

Architecture

Data Models

WorkflowTemplate

interface WorkflowTemplate {
  id: string
  name: string
  description: string
  batchType: 'payroll' | 'invoice' | 'timesheet' | 'expense' | 'compliance' | 'purchase-order'
  isActive: boolean
  isDefault: boolean
  steps: ApprovalStepTemplate[]
  createdAt: string
  updatedAt: string
  createdBy?: string
  metadata?: {
    color?: string
    icon?: string
    tags?: string[]
  }
}

ApprovalStepTemplate

interface ApprovalStepTemplate {
  id: string
  order: number
  name: string
  description?: string
  approverRole: string
  requiresComments: boolean
  canSkip: boolean
  skipConditions?: StepCondition[]
  autoApprovalConditions?: StepCondition[]
  escalationRules?: EscalationRule[]
}

EscalationRule

interface EscalationRule {
  id: string
  hoursUntilEscalation: number
  escalateTo: string
  notifyOriginalApprover: boolean
}

StepCondition

interface StepCondition {
  id: string
  field: string
  operator: 'equals' | 'greaterThan' | 'lessThan' | 'contains' | 'notEquals'
  value: string | number
  logic?: 'AND' | 'OR'
}

Storage

• IndexedDB: All workflow templates are persisted in the browser's IndexedDB
• useIndexedDBState Hook: Provides reactive state management with automatic persistence
• No Server Dependencies: Fully client-side with instant updates

Components

ApprovalWorkflowTemplateManager

Main management interface with:

• Template list view with filtering by batch type
• Create, edit, duplicate, and delete operations
• Active/inactive status indicators
• Default template badges

WorkflowTemplateCard

Displays template summary:

• Template name and description
• Batch type badge with color coding
• Status indicators (active/inactive, default)
• Step count and overview
• Action buttons (edit, duplicate, delete)
• Escalation rule indicators

WorkflowTemplateEditor

Comprehensive editing interface:

• Template Details Section:
  • Name and description
  • Batch type selection
  • Active/inactive toggle
  • Set as default option
• Steps Section:
  • Add, remove, reorder steps
  • Step-by-step configuration
  • Expand/collapse individual steps
  • Visual step numbering
• Step Configuration:
  • Step name and description
  • Approver role selection
  • Requires comments toggle
  • Can skip toggle
  • Escalation rules management
• Escalation Rules:
  • Hours until escalation
  • Escalation target role
  • Original approver notification

Hooks

useApprovalWorkflowTemplates

Primary hook for template management:

• createTemplate(): Create new template
• updateTemplate(): Update existing template
• deleteTemplate(): Remove template
• duplicateTemplate(): Clone template
• addStep(): Add approval step
• updateStep(): Modify step configuration
• removeStep(): Delete step
• reorderSteps(): Change step sequence
• setDefaultTemplate(): Set default for batch type
• getTemplatesByBatchType(): Filter templates
• getDefaultTemplate(): Get default for batch type
• getActiveTemplates(): Get all active templates

useSampleWorkflowTemplates

Initializes sample templates on first load:

• Standard Payroll Approval (2-step with escalation)
• Client Invoice Approval (1-step standard)
• Large Invoice Approval (3-step for high values)
• Timesheet Batch Approval (1-step with skip conditions)
• Expense Claim Approval (2-step with conditional skip)
• Compliance Document Approval (2-step rigorous)
• Purchase Order Approval (2-step with escalation)

Usage Examples

Creating a New Template

const { createTemplate, updateTemplate } = useApprovalWorkflowTemplates()

const template = createTemplate(
  'High-Value Invoice Workflow',
  'invoice',
  'Special approval process for invoices over $50,000'
)

updateTemplate(template.id, {
  isActive: true,
  isDefault: false,
  steps: [
    {
      id: 'step-1',
      order: 0,
      name: 'Billing Manager Review',
      approverRole: 'Manager',
      requiresComments: true,
      canSkip: false
    },
    {
      id: 'step-2',
      order: 1,
      name: 'CFO Approval',
      approverRole: 'CFO',
      requiresComments: true,
      canSkip: false,
      escalationRules: [{
        id: 'esc-1',
        hoursUntilEscalation: 24,
        escalateTo: 'CEO',
        notifyOriginalApprover: true
      }]
    }
  ]
})

Adding Conditional Logic

const { updateStep } = useApprovalWorkflowTemplates()

updateStep(templateId, stepId, {
  canSkip: true,
  skipConditions: [
    {
      id: 'cond-1',
      field: 'totalAmount',
      operator: 'lessThan',
      value: 10000
    }
  ]
})

Setting Default Template

const { setDefaultTemplate } = useApprovalWorkflowTemplates()

setDefaultTemplate(templateId, 'payroll')

User Interface

Navigation

Access via: Configuration → Workflow Templates

Template List View

• Filter dropdown for batch type selection
• Card-based layout showing:
  • Template name with badges (default, active/inactive)
  • Batch type with color coding
  • Description
  • Step count and summary
  • Creation and update dates
  • Action buttons

Template Editor

• Modal dialog with scrollable content
• Two main sections: Template Details and Approval Steps
• Visual step ordering with up/down arrows
• Expandable step details
• Inline escalation rule management
• Save/Cancel actions

Color Coding

• Payroll: Blue accent
• Invoice: Info blue
• Timesheet: Success green
• Expense: Warning amber
• Compliance: Destructive red
• Purchase Order: Primary purple

Best Practices

Template Design

1. Keep It Simple: Start with minimal steps, add complexity only when needed
2. Clear Naming: Use descriptive names that indicate purpose
3. Document Steps: Add descriptions to guide approvers
4. Set Escalations: Prevent bottlenecks with time-based escalation
5. Test Thoroughly: Validate workflows before setting as default

Step Configuration

1. Logical Order: Arrange steps from least to most senior authority
2. Required Comments: Use for rejection scenarios and high-value approvals
3. Skip Wisely: Only allow skipping for low-risk, routine approvals
4. Role Alignment: Ensure approver roles match organizational structure

Escalation Rules

1. Reasonable Timeframes: Set escalation times based on typical response times
2. Clear Hierarchy: Escalate to next level of authority
3. Keep Informed: Enable notifications to maintain visibility
4. Multiple Tiers: Consider multi-level escalation for critical processes

Integration

With Payroll Batch Processing

The usePayrollBatch hook integrates workflow templates:

const batch = createBatch(periodStart, periodEnd, workers)
applyWorkflowTemplate(batch.id, templateId)

With Other Batch Types

Future integration planned for:

• Invoice generation workflows
• Timesheet batch approval
• Expense claim processing
• Compliance document submission
• Purchase order approval

Future Enhancements

Planned Features

• Parallel Approval: Multiple approvers at same step
• Delegation: Temporary approver substitution
• Approval History: Detailed audit trail
• Custom Fields: Dynamic field validation in conditions
• Email Integration: Direct approval from email
• Mobile Approval: Native mobile app integration
• Analytics: Workflow performance metrics
• Version Control: Template versioning and rollback
• Import/Export: Share templates between instances
• API Access: Programmatic template management

Advanced Conditional Logic

• Complex Expressions: JavaScript-based conditions
• Data Lookups: Reference external data sources
• Time-Based Rules: Approval requirements based on date/time
• User Attributes: Conditions based on submitter characteristics

Enhanced Notifications

• SMS Alerts: Critical approval reminders
• Slack Integration: Team channel notifications
• Custom Webhooks: Integration with external systems
• Digest Emails: Grouped pending approvals

Troubleshooting

Common Issues

Templates Not Appearing

• Check browser IndexedDB is enabled
• Clear cache and reload application
• Verify template is set to active

Steps Not Reordering

• Click and hold drag handle
• Use up/down arrows as alternative
• Refresh page if drag-drop fails

Escalation Not Triggering

• Verify hours until escalation is reasonable
• Check escalation target role exists
• Ensure approver has not taken action

Cannot Delete Template

• Check template is not set as default
• Verify no active batches use template
• Temporarily deactivate before deletion

Support

For issues or questions about approval workflow templates:

1. Check this documentation
2. Review sample templates for examples
3. Contact system administrator
4. Submit support ticket through platform

Version History

v1.0.0 (Current)

• Initial release
• Six batch type support
• Multi-step approval workflows
• Escalation rules
• Conditional skip logic
• Template management UI
• Sample templates included
• IndexedDB persistence