# Travel Reimbursement Workflow Documentation

## Overview

The Travel Reimbursement Workflow is a comprehensive business process management solution designed to handle employee travel expense claims from submission to final approval and reimbursement. This workflow demonstrates the full capabilities of the Corrad ProcessMaker platform, including form integration, automated calculations, decision gateways, API integrations, and multi-level approval processes.

## Workflow Components

### 1. Form Components

#### Employee Travel Reimbursement Form
- **Purpose**: Primary form for employees to submit travel expense claims
- **File Location**: `docs/json/form/travel-reimbursement-form.json`
- **Key Features**:
  - Employee details collection (name, email, department)
  - Trip information (purpose, destination, dates)
  - Detailed expense breakdown with receipt uploads
  - Automatic cost calculations
  - Policy compliance validation

**Form Fields Structure**:
```
Employee Details:
├── Employee Name (span 6) - Required
├── Employee Email (span 6) - Required
└── Department (span 12) - Required

Trip Information:
├── Trip Purpose (span 6) - Required
├── Destination (span 6) - Required
├── Start Date (span 6) - Required
└── End Date (span 6) - Required

Expense Categories:
├── Transportation Costs (span 4)
├── Accommodation Costs (span 4)
├── Meal Costs (span 4)
├── Other Expenses (span 12)
└── Receipt Upload (span 12) - File upload

Calculations:
├── Total Cost (span 6) - Auto-calculated
├── Policy Limit (span 6) - Auto-populated
└── Over Budget Amount (span 12) - Auto-calculated
```

#### Manager Approval Form
- **Purpose**: Manager review and approval interface
- **File Location**: `docs/json/form/manager-approval-form.json`
- **Key Features**:
  - Display of employee claim details
  - Cost analysis with policy comparisons
  - Approval decision options (approve full, approve policy limit, reject)
  - Custom amount approval capability
  - Required justification comments

**Approval Options**:
- **Approve Full Amount**: Manager approves the entire claimed amount
- **Approve Policy Limit Only**: Manager approves only up to policy limits
- **Reject Claim**: Manager rejects the entire claim with required explanation

### 2. Process Workflow

#### Process Definition
- **File Location**: `docs/json/process-builder/travel-workflow-process.json`
- **Total Nodes**: 10 nodes with 12 connecting edges
- **Process Type**: Sequential workflow with decision gateways

#### Workflow Steps

1. **Start Node** (`start_travel_claim`)
   - Initiates the travel reimbursement process
   - Sets up initial process variables

2. **Employee Form Submission** (`employee_form_task`)
   - **Type**: Form Task
   - **Form**: Travel Reimbursement Form
   - **Assigned Roles**: Employee, HR
   - **Input/Output Mappings**: Maps form data to process variables
   - **Validation**: Ensures all required fields are completed

3. **Calculate Total Costs** (`calculate_costs_script`)
   - **Type**: Script Task
   - **Function**: Automatic calculation of total expenses
   - **Calculations**:
     ```javascript
     totalCost = transportation + accommodation + meals + otherExpenses
     overBudgetAmount = Math.max(0, totalCost - policyLimit)
     isOverBudget = totalCost > policyLimit
     ```

4. **Validate Policy Compliance** (`validate_policy_api`)
   - **Type**: API Call
   - **Endpoint**: `/api/travel/validate-policy`
   - **Method**: POST
   - **Purpose**: Check claim against company travel policies
   - **Output**: Policy validation results and limits

5. **Budget Decision Gateway** (`budget_decision_gateway`)
   - **Type**: Decision Gateway
   - **Logic**: Determines approval path based on budget compliance
   - **Conditions**:
     - If `totalCost <= policyLimit` → Direct to Finance Processing
     - If `totalCost > policyLimit` → Route to Manager Approval

6. **Manager Approval Task** (`manager_approval_task`)
   - **Type**: Form Task
   - **Form**: Manager Approval Form
   - **Assigned Roles**: Manager, Department Head
   - **Trigger**: Only when claim exceeds policy limits
   - **Decision Options**: Approve/Modify/Reject

7. **Approval Decision Gateway** (`approval_decision_gateway`)
   - **Type**: Decision Gateway
   - **Logic**: Routes based on manager's decision
   - **Paths**:
     - Approved → Finance Processing
     - Rejected → Employee Notification (Rejection)
     - Modified → Finance Processing with adjusted amount

8. **Finance Processing** (`finance_processing_api`)
   - **Type**: API Call
   - **Endpoint**: `/api/finance/process-reimbursement`
   - **Method**: POST
   - **Function**: Initiates payment processing
   - **Data**: Final approved amount and employee details

9. **Send Notification** (`send_final_notification`)
   - **Type**: Notification Task
   - **Recipients**: Employee, Manager, Finance Team
   - **Content**: Final decision and payment status
   - **Channels**: Email, In-app notification

10. **End Process** (`end_travel_claim`)
    - **Type**: End Node
    - **Function**: Completes the workflow
    - **Final Status**: Sets process completion status

### 3. Process Variables

**File Location**: `docs/json/process-builder/travel-workflow-variables.json`

#### Employee Information Variables
```javascript
employeeName: String         // Employee's full name
employeeEmail: String        // Employee's email address
department: String           // Employee's department
employeeId: String          // System employee identifier
```

#### Trip Details Variables
```javascript
tripPurpose: String         // Purpose of business trip
destination: String         // Travel destination
startDate: Date            // Trip start date
endDate: Date              // Trip end date
tripDuration: Number       // Calculated trip duration in days
```

#### Financial Variables
```javascript
transportationCost: Number  // Transportation expenses
accommodationCost: Number   // Hotel/lodging expenses
mealCost: Number           // Meal expenses
otherExpenses: Number      // Miscellaneous expenses
totalCost: Number          // Sum of all expenses
policyLimit: Number        // Company policy limit
overBudgetAmount: Number   // Amount exceeding policy
isOverBudget: Boolean      // Budget compliance flag
approvedAmount: Number     // Final approved amount
```

#### Process Control Variables
```javascript
processStatus: String       // Current process status
currentStep: String         // Current workflow step
approvalRequired: Boolean   // Manager approval needed flag
managerDecision: String     // Manager's approval decision
rejectionReason: String     // Reason for rejection (if applicable)
paymentStatus: String       // Finance processing status
```

### 4. Dynamic Form Behavior

#### Travel Reimbursement Form Script
**File Location**: `docs/json/form/travel-reimbursement-customScript.js`

**Key Functions**:
1. **Auto-calculation Engine**:
   ```javascript
   // Real-time cost calculation
   onFieldChange(['transportation_cost', 'accommodation_cost', 'meal_cost', 'other_expenses'], () => {
     const total = calculateTotalCost();
     setField('total_cost', total);
     checkPolicyCompliance(total);
   });
   ```

2. **Policy Validation**:
   ```javascript
   // Check against policy limits
   const checkPolicyCompliance = (totalCost) => {
     const policyLimit = getField('policy_limit') || 2000;
     const overBudget = Math.max(0, totalCost - policyLimit);
     
     if (overBudget > 0) {
       showError(`Amount exceeds policy limit by RM${overBudget.toFixed(2)}`);
     }
   };
   ```

3. **Date Validation**:
   ```javascript
   // Ensure end date is after start date
   onFieldChange(['start_date', 'end_date'], () => {
     validateDateRange();
   });
   ```

#### Manager Approval Form Script
**File Location**: `docs/json/form/manager-approval-customScript.js`

**Key Functions**:
1. **Decision Logic**:
   ```javascript
   onFieldChange('manager_decision', (decision) => {
     switch(decision) {
       case 'approve_full':
         showField('custom_approved_amount');
         break;
       case 'approve_policy':
         hideField('custom_approved_amount');
         break;
       case 'reject':
         showError('Please provide detailed rejection comments');
         break;
     }
   });
   ```

2. **Amount Validation**:
   ```javascript
   // Validate custom approved amounts
   const validateCustomAmount = (amount) => {
     const totalClaimed = parseFloat(getField('total_cost_display'));
     if (amount > totalClaimed) {
       showError('Approved amount cannot exceed claimed amount');
       return false;
     }
     return true;
   };
   ```

## Business Rules

### Policy Compliance Rules
1. **Transportation**: Maximum RM800 per trip
2. **Accommodation**: Maximum RM300 per night
3. **Meals**: Maximum RM100 per day
4. **Total Trip Limit**: RM2000 per trip
5. **Receipt Requirement**: All expenses > RM50 require receipts

### Approval Authority
1. **Under Policy Limit**: Automatic approval, direct to finance
2. **Over Policy Limit**: Requires manager approval
3. **Over RM5000**: Requires department head approval
4. **International Travel**: Additional CEO approval required

### Notification Rules
1. **Employee**: Notified at submission, approval, and payment stages
2. **Manager**: Notified when approval required and decision made
3. **Finance**: Notified for all approved claims requiring payment
4. **HR**: Notified for audit trail and policy compliance tracking

## Integration Points

### API Endpoints
1. **Policy Validation**: `/api/travel/validate-policy`
2. **Finance Processing**: `/api/finance/process-reimbursement`
3. **Employee Directory**: `/api/employees/lookup`
4. **Notification Service**: `/api/notifications/send`

### External Systems
1. **HR Management System**: Employee data synchronization
2. **Finance ERP**: Payment processing integration
3. **Document Management**: Receipt storage and retrieval
4. **Email Service**: Automated notification delivery

## Usage Instructions

### For Employees
1. Navigate to the Travel Reimbursement workflow
2. Fill out the employee travel reimbursement form
3. Upload receipts for expenses over RM50
4. Review calculated totals and policy compliance
5. Submit the form for processing
6. Monitor approval status via notifications

### For Managers
1. Receive notification when approval is required
2. Review employee claim details and supporting documents
3. Make approval decision based on policy and business needs
4. Provide justification comments for decisions
5. Submit approval decision

### For Finance Team
1. Receive approved claims for payment processing
2. Verify all required documentation is present
3. Process payment through ERP system
4. Update payment status in the workflow
5. Send final confirmation to employee

## Monitoring and Analytics

### Process Metrics
- Average processing time per claim
- Approval rates by manager and department
- Policy compliance statistics
- Cost analysis and trending

### Performance Indicators
- Claims processed per month
- Average claim value
- Rejection rates and reasons
- Processing bottlenecks identification

## Troubleshooting

### Common Issues
1. **Form Validation Errors**: Check required fields and data formats
2. **File Upload Problems**: Ensure receipts are in supported formats (PDF, JPG, PNG)
3. **Calculation Errors**: Verify numeric input formats and policy limits
4. **Approval Delays**: Check manager notification settings and availability

### Error Handling
- Form validation provides real-time feedback
- API failures trigger retry mechanisms
- Email delivery failures logged for manual follow-up
- Process timeouts escalate to supervisors

## Future Enhancements

### Planned Features
1. **Mobile App Integration**: Native mobile form submission
2. **OCR Receipt Processing**: Automatic expense extraction from receipts
3. **Multi-currency Support**: International travel expense handling
4. **Advanced Analytics**: Predictive spending analysis
5. **Integration Expansion**: Additional ERP and HR system connectors

This comprehensive travel reimbursement workflow demonstrates the full capabilities of the Corrad ProcessMaker platform, providing a real-world example of how complex business processes can be automated, managed, and optimized through digital workflow solutions.