#Troubleshooting Guide

Common issues and solutions for Custom Excel Template Import.

#Template Configuration Issues

#Template Creation Problems

#Excel File Not Uploading

Symptoms: Upload fails or file not recognized Solutions:

• Ensure file is in .xlsx format (not .xls or .csv)
• Check file size (large files may timeout)
• Verify file is not corrupted or password-protected
• Remove any macros or VBA code from the file

#Columns Not Detected

Symptoms: Expected columns don't appear in mapping interface Solutions:

• Verify column headers are in the first row
• Remove merged cells in header row
• Check for hidden columns or sheets
• Ensure column headers have text (not formulas)

#Sheet Not Found

Symptoms: Expected sheets don't appear in configuration Solutions:

• Check sheet names for special characters
• Ensure sheets contain data (empty sheets may be ignored)
• Verify sheet visibility (unhide if necessary)
• Remove completely empty sheets

#Column Mapping Issues

#Required Field Validation Errors

Symptoms: Template validation fails due to missing required fields Solutions:

• Map all fields marked with red "Required" badges
• Use the System Fields reference to find correct field names
• Check that mapped columns contain actual data
• Verify field compatibility (dates to date fields, numbers to amount fields)

#System Field Not Available

Symptoms: Expected field doesn't appear in dropdown Solutions:

• Use the search function in field dropdowns
• Check correct field category (header vs line)
• Verify sheet type is set correctly
• Some fields may only be available for specific import modes

#Mapping Not Saved

Symptoms: Mappings reset after configuration Solutions:

• Click "Save" button after making changes
• Ensure stable internet connection during save
• Check browser console for JavaScript errors
• Try refreshing page and reconfiguring

#Import Processing Issues

#Data Import Failures

#Invoice Creation Errors

Symptoms: Import process fails with validation errors Solutions:

• Check LHDN field requirements are met
• Verify tax calculations are correct
• Ensure required customer information is complete
• Review date formats (use proper Excel date formatting)

#Calculation Errors

Symptoms: Totals don't match or are incorrect Solutions:

• Verify Excel formulas are calculated before import
• Check for circular references in Excel file
• Ensure number formatting is consistent
• Review tax rate applications and defaults

#Linking Issues (Standard Mode)

Symptoms: Header and line data not properly linked Solutions:

• Verify Invoice ID field exists in both sheets
• Check Invoice ID values match exactly (case-sensitive)
• Remove extra spaces or formatting from Invoice IDs
• Ensure Invoice ID column is mapped in both sheets

#Code Mapping Problems

#Values Not Transformed

Symptoms: Excel values appear unchanged in final invoices Solutions:

• Verify exact spelling in code mappings (case-sensitive)
• Check for extra spaces or hidden characters
• Ensure code mapping is saved correctly
• Test with simplified values first

#Invalid Code Errors

Symptoms: Transformed codes cause validation errors Solutions:

• Verify system values match LHDN requirements exactly
• Check code format specifications in LHDN documentation
• Use standard codes from LHDN reference lists
• Test codes with LHDN validation tools

#Missing Code Mappings

Symptoms: Some Excel values don't have corresponding mappings Solutions:

• Review import logs to identify unmapped values
• Add mappings for all possible Excel values
• Consider using conditional defaults for edge cases
• Implement data cleaning in Excel before import

#Default Value Issues

#Defaults Not Applied

Symptoms: Expected default values don't appear in imported invoices Solutions:

• Check condition syntax and field names
• Verify target field selection is correct
• Test conditions with actual Excel data
• Ensure default value format matches field requirements

#Conditional Logic Errors

Symptoms: Wrong defaults applied or conditions not matching Solutions:

• Review condition order (first match wins)
• Check operator selection (equals vs contains)
• Verify case sensitivity in text comparisons
• Test with simplified conditions first

#Performance Issues with Defaults

Symptoms: Import process very slow with many defaults Solutions:

• Simplify complex text matching conditions
• Use exact matches instead of contains when possible
• Reduce number of conditional rules where feasible
• Consider data pre-processing in Excel

#Performance and Scale Issues

#Large File Processing

#Timeout Errors

Symptoms: Import process times out for large files Solutions:

• Split large files into smaller batches
• Remove unnecessary columns and rows
• Optimize Excel file (remove unused formatting)
• Process during off-peak hours

#Memory Errors

Symptoms: System runs out of memory during processing Solutions:

• Reduce file size by removing unused data
• Process files in smaller chunks
• Close other applications during import
• Contact support for system resource limits

#Slow Processing

Symptoms: Import takes very long time to complete Solutions:

• Optimize Excel file structure
• Reduce complex conditional logic
• Remove excessive formatting from Excel
• Use simpler import modes when possible

#Data Quality Issues

#Validation Failures

#LHDN Compliance Errors

Symptoms: Final invoices fail LHDN validation Solutions:

• Review LHDN field requirements carefully
• Use strict validation mode during testing
• Verify all required fields are populated
• Check tax calculations and classifications

#Business Rule Violations

Symptoms: Data violates business logic rules Solutions:

• Review template validation messages
• Check field value ranges and formats
• Verify customer and product data integrity
• Ensure date logic is consistent

#Currency and Tax Issues

Symptoms: Currency or tax calculations are incorrect Solutions:

• Verify exchange rate mappings and defaults
• Check tax code mappings against LHDN standards
• Ensure consistent currency codes throughout
• Review tax-exempt and zero-rate scenarios

#User Interface Issues

#Display Problems

#Dark Mode Issues

Symptoms: Interface elements not visible in dark mode Solutions:

• Switch to light mode temporarily
• Clear browser cache and refresh
• Update browser to latest version
• Report UI issues for fixing

#Mobile/Responsive Issues

Symptoms: Interface doesn't work properly on mobile devices Solutions:

• Use desktop browser for template configuration
• Rotate device to landscape orientation
• Zoom out to see more interface elements
• Switch to desktop for complex operations

#Performance Issues in Browser

Symptoms: Interface is slow or unresponsive Solutions:

• Close other browser tabs and applications
• Clear browser cache and cookies
• Disable browser extensions temporarily
• Try different browser (Chrome, Firefox, Safari)

#Getting Help

#Self-Service Resources

1. Template Validation: Use built-in validation to identify issues
2. Sample Data: Test with small, known-good data sets
3. Documentation: Review relevant sections of this guide
4. Error Messages: Read error messages carefully for specific guidance

#Escalation Process

1. Gather Information: Collect error messages, template settings, and sample data
2. Document Steps: Note exact steps that led to the issue
3. Test Isolation: Try to reproduce with minimal data
4. Contact Support: Provide detailed information for faster resolution

#Information to Provide

• Template name and configuration
• Excel file structure and sample data
• Error messages (exact text)
• Browser and operating system details
• Steps to reproduce the issue

#Prevention Best Practices

#Template Design

• Start with simple configurations and add complexity gradually
• Test thoroughly with sample data before production use
• Document template logic and business rules
• Regular review and maintenance of templates

#Data Preparation

• Standardize Excel file formats across your organization
• Implement data validation in source systems
• Clean data before export to Excel
• Maintain consistent naming conventions

#Process Management

• Establish testing procedures for new templates
• Train users on proper Excel file preparation
• Monitor import success rates and error patterns
• Regular backup of working template configurations

#Ongoing Maintenance

• Review and update code mappings regularly
• Monitor for new Excel data patterns
• Update default values as business rules change
• Performance monitoring and optimization