commit 39ab27c7b77dd330069d750970d5d1a5d5ec05fd Author: admin.suherdy Date: Sat Nov 29 08:46:04 2025 +0700 first commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2790db7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,120 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db diff --git a/README.md b/README.md new file mode 100644 index 0000000..87e80dd --- /dev/null +++ b/README.md @@ -0,0 +1,413 @@ +# Survey Custom Certificate Template + +## Overview + +The Survey Custom Certificate Template module extends Odoo 19's Survey application to support custom DOCX-based certificate templates with dynamic placeholders. This allows survey administrators to create personalized, branded certificates without requiring XML/QWeb development or coding knowledge. + +## Features + +- **Custom DOCX Templates**: Upload your own Microsoft Word certificate designs +- **Dynamic Placeholders**: Use `{key.field_name}` syntax for automatic data insertion +- **Intelligent Mapping**: Automatic field mapping for common placeholder names +- **Live Preview**: Generate sample certificates before going live +- **Multi-Survey Support**: Each survey can have its own unique template +- **Easy Updates**: Update templates while preserving existing mappings +- **Comprehensive Error Handling**: Graceful handling of missing data and conversion errors +- **Security**: Built-in validation and sanitization of all user inputs + +## Quick Start + +### For Users + +1. Navigate to **Surveys** in Odoo +2. Open or create a survey +3. Go to the **Options** tab +4. Select **Custom Template** from the Certification Template dropdown +5. Click **Upload Custom Certificate** +6. Upload your DOCX template with placeholders +7. Configure placeholder mappings +8. Generate a preview +9. Click **Save** + +### For Administrators + +1. Install LibreOffice on the server +2. Install python-docx: `pip install python-docx` +3. Install the module from Odoo Apps +4. Grant Survey Manager access to users who need to configure templates + +## Documentation + +- **[User Guide](docs/USER_GUIDE.md)**: Complete guide for creating and configuring certificate templates +- **[Administrator Guide](docs/ADMIN_GUIDE.md)**: Installation, configuration, and troubleshooting for system administrators +- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)**: Common issues and solutions + +## Requirements + +### System Requirements + +- Odoo 19.0 or later +- Python 3.8 or later +- LibreOffice 6.0 or later (for PDF conversion) + +### Python Dependencies + +- `python-docx >= 0.8.11` + +### Odoo Module Dependencies + +- `survey` (Odoo Survey module) +- `base` (Odoo Base module) +- `mail` (Odoo Mail module) + +## Installation + +### 1. Install System Dependencies + +#### Ubuntu/Debian +```bash +sudo apt-get update +sudo apt-get install libreoffice +``` + +#### CentOS/RHEL +```bash +sudo yum install libreoffice +``` + +### 2. Install Python Dependencies + +```bash +# Activate your Odoo virtual environment +source /path/to/odoo/venv/bin/activate + +# Install python-docx +pip install python-docx +``` + +### 3. Install the Module + +1. Copy the module to your Odoo addons directory +2. Update the apps list in Odoo +3. Search for "Survey Custom Certificate Template" +4. Click Install + +### 4. Verify Installation + +1. Open a survey in Odoo +2. Check that "Custom Template" appears in the Certification Template dropdown +3. Try uploading a test template + +## Usage + +### Creating a Certificate Template + +1. **Design your certificate** in Microsoft Word (.docx format) +2. **Add placeholders** where you want dynamic data: + ``` + {key.name} + {key.course_name} + {key.date} + {key.score} + ``` +3. **Save the file** as .docx format + +### Placeholder Syntax + +Placeholders must follow this exact format: +``` +{key.field_name} +``` + +**Examples:** +- `{key.name}` - Participant's name +- `{key.course_name}` - Survey title +- `{key.completion_date}` - Completion date +- `{key.score}` - Score percentage + +### Recognized Placeholder Names + +The system automatically maps these common placeholders: + +| Placeholder | Maps To | Description | +|-------------|---------|-------------| +| `{key.name}` | partner_name | Participant's full name | +| `{key.email}` | partner_email | Participant's email | +| `{key.course_name}` | survey_title | Survey title | +| `{key.date}` | completion_date | Completion date | +| `{key.score}` | scoring_percentage | Score percentage | + +See the [User Guide](docs/USER_GUIDE.md) for a complete list. + +### Configuring Mappings + +For each placeholder, choose how it should be filled: + +1. **Survey Field**: Data from the survey (title, description) +2. **Participant Field**: Data from the participant (name, email, date, score) +3. **Custom Text**: Static text that's the same for all certificates + +## Architecture + +### Components + +- **Template Parser**: Extracts placeholders from DOCX files using python-docx +- **Certificate Generator**: Replaces placeholders and converts to PDF using LibreOffice +- **Configuration Wizard**: User interface for uploading and configuring templates +- **Survey Model Extension**: Stores templates and mappings in the database + +### Data Flow + +1. Administrator uploads DOCX template +2. Parser extracts placeholders +3. Administrator configures mappings +4. Configuration saved to database +5. On survey completion, generator creates personalized certificate +6. LibreOffice converts DOCX to PDF +7. Certificate delivered to participant + +## Security + +### Access Control + +- Only users with **Survey Manager** role can upload and configure templates +- Template data is restricted to appropriate user groups +- All user inputs are validated and sanitized + +### Data Validation + +- File type validation (DOCX only) +- File size limits (10 MB maximum) +- Placeholder format validation +- Field name validation (alphanumeric only) +- Custom text length limits (1000 characters) + +### Sanitization + +- HTML escaping for all placeholder values +- Control character removal +- Special character filtering +- Length limits to prevent DoS attacks + +## Troubleshooting + +### Common Issues + +#### "Invalid file format" error +- Ensure file is .docx format (not .doc) +- Re-save the file in Microsoft Word or LibreOffice + +#### "No placeholders found" warning +- Check placeholder syntax: must be `{key.field_name}` +- Common mistakes: `{{key.name}}`, `{name}`, `{ key.name }` + +#### "PDF conversion failed" error +- Ensure LibreOffice is installed on the server +- Contact your system administrator + +#### Placeholders not replaced +- Verify mapping configuration is complete +- Check field names are correct (case-sensitive) +- Generate a preview to test + +See the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for more solutions. + +## Performance + +### Optimization Tips + +- **Template Size**: Keep templates under 5 MB for best performance +- **Image Compression**: Compress images in templates +- **Simple Formatting**: Avoid complex Word features +- **Batch Generation**: Generate certificates during off-peak hours for high volumes + +### Resource Usage + +- **Memory**: ~50-100 MB per certificate generation +- **CPU**: Moderate usage during PDF conversion +- **Disk**: Templates stored in database, certificates as attachments +- **Time**: 5-10 seconds per certificate (including PDF conversion) + +## Development + +### Module Structure + +``` +survey_custom_certificate_template/ +├── __init__.py +├── __manifest__.py +├── models/ +│ ├── __init__.py +│ ├── survey_survey.py +│ └── survey_user_input.py +├── wizards/ +│ ├── __init__.py +│ ├── survey_custom_certificate_wizard.py +│ └── survey_custom_certificate_wizard_views.xml +├── services/ +│ ├── __init__.py +│ ├── certificate_template_parser.py +│ ├── certificate_generator.py +│ ├── certificate_logger.py +│ └── admin_notifier.py +├── views/ +│ └── survey_survey_views.xml +├── security/ +│ └── ir.model.access.csv +├── tests/ +│ ├── __init__.py +│ ├── hypothesis_strategies.py +│ ├── test_property_*.py +│ └── test_*.py +└── docs/ + ├── README.md + ├── USER_GUIDE.md + ├── ADMIN_GUIDE.md + └── TROUBLESHOOTING.md +``` + +### Testing + +The module includes comprehensive tests: + +- **Unit Tests**: Test individual components +- **Property-Based Tests**: Test universal properties using Hypothesis +- **Integration Tests**: Test complete workflows + +Run tests: +```bash +# Run all tests +python -m pytest customaddons/survey_custom_certificate_template/tests/ + +# Run specific test file +python -m pytest customaddons/survey_custom_certificate_template/tests/test_property_placeholder_extraction_standalone.py + +# Run with coverage +python -m pytest --cov=customaddons/survey_custom_certificate_template +``` + +### Contributing + +When contributing to this module: + +1. Follow Odoo coding guidelines +2. Add tests for new features +3. Update documentation +4. Ensure all tests pass +5. Test with various template formats + +## License + +This module is licensed under LGPL-3. + +## Support + +For support: + +1. **Documentation**: Check the [User Guide](docs/USER_GUIDE.md) and [Admin Guide](docs/ADMIN_GUIDE.md) +2. **Issues**: Review the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) +3. **Logs**: Check Odoo server logs for detailed error messages +4. **Community**: Search Odoo community forums for similar issues + +## Changelog + +### Version 1.0.0 (2024) + +**Initial Release** + +- Custom DOCX template upload +- Dynamic placeholder system +- Automatic field mapping +- Live preview generation +- Multi-survey support +- Template update and deletion +- Comprehensive error handling +- Security validation and sanitization +- Property-based testing +- Complete documentation + +## Credits + +**Author**: Survey Custom Certificate Template Team +**Maintainer**: Your Organization +**Contributors**: See CONTRIBUTORS.md + +## Technical Details + +### Database Schema + +**survey.survey (Extended)** +- `custom_cert_template` (Binary): Template file +- `custom_cert_template_filename` (Char): Filename +- `custom_cert_mappings` (Text): JSON mappings +- `has_custom_certificate` (Boolean): Configuration flag + +**survey.custom.certificate.wizard (Transient)** +- Template upload and configuration wizard + +**survey.certificate.placeholder (Transient)** +- Placeholder mapping configuration + +### API + +#### Public Methods + +**survey.survey** +- `action_open_custom_certificate_wizard()`: Opens configuration wizard +- `_generate_custom_certificate(user_input_id)`: Generates certificate for participant +- `_get_certificate_data(user_input_id)`: Retrieves data for certificate +- `action_delete_custom_certificate()`: Deletes custom template + +**CertificateTemplateParser** +- `parse_template(docx_binary)`: Extracts placeholders +- `validate_template(docx_binary)`: Validates DOCX structure + +**CertificateGenerator** +- `generate_certificate(template_binary, mappings, data)`: Generates PDF certificate + +### Configuration + +No additional configuration required. The module works out of the box after installation. + +### Compatibility + +- **Odoo Version**: 19.0 +- **Python Version**: 3.8+ +- **Database**: PostgreSQL 12+ +- **Operating System**: Linux (Ubuntu, Debian, CentOS, RHEL) + +## FAQ + +**Q: Can I use .doc files instead of .docx?** +A: No, only .docx format is supported. Convert .doc files to .docx first. + +**Q: What's the maximum template file size?** +A: 10 MB. Compress images if your file exceeds this limit. + +**Q: Can I use custom fonts?** +A: Yes, but use standard fonts for best compatibility. Custom fonts may not render correctly in PDF. + +**Q: How do I add a logo to my certificate?** +A: Insert the logo as an image in your Word template. It will be preserved in generated certificates. + +**Q: Can I have different templates for different surveys?** +A: Yes, each survey can have its own unique template. + +**Q: What happens if a participant's data is missing?** +A: The system uses empty strings for missing data to prevent generation failures. + +**Q: Can I update a template after it's been configured?** +A: Yes, upload a new template and existing mappings will be preserved where placeholders match. + +**Q: Is there a limit to the number of placeholders?** +A: No hard limit, but keep it reasonable for performance (< 50 placeholders recommended). + +**Q: Can I use special characters in placeholders?** +A: Placeholder names can only contain letters, numbers, and underscores. + +**Q: How are certificates delivered to participants?** +A: Certificates can be emailed or made available for download through the participant portal. + +--- + +**For detailed information, please refer to the complete documentation in the `docs/` directory.** diff --git a/__init__.py b/__init__.py new file mode 100644 index 0000000..7d8186d --- /dev/null +++ b/__init__.py @@ -0,0 +1,43 @@ +# -*- coding: utf-8 -*- + +from . import models +from . import wizards +from . import services + + +def post_init_hook(env): + """ + Post-installation hook to check LibreOffice availability. + + This hook runs after the module is installed and checks if LibreOffice + is available on the system. If not, it logs a warning to notify + administrators that PDF conversion will not be available. + + Args: + env: Odoo environment + """ + import logging + from .services.certificate_generator import CertificateGenerator + + _logger = logging.getLogger(__name__) + + _logger.info('Checking LibreOffice availability for Survey Custom Certificate Template module...') + + # Check LibreOffice availability + is_available, error_message = CertificateGenerator.check_libreoffice_availability() + + if is_available: + _logger.info( + '✓ LibreOffice is available. PDF certificate generation is enabled.' + ) + else: + _logger.warning( + '✗ LibreOffice is not available. PDF certificate generation will not work.\n' + 'Error: %s\n' + 'To enable PDF conversion, please install LibreOffice:\n' + ' - Ubuntu/Debian: sudo apt-get install libreoffice\n' + ' - CentOS/RHEL: sudo yum install libreoffice\n' + ' - macOS: brew install --cask libreoffice\n' + 'After installation, restart the Odoo service.', + error_message + ) diff --git a/__manifest__.py b/__manifest__.py new file mode 100644 index 0000000..40bb61d --- /dev/null +++ b/__manifest__.py @@ -0,0 +1,45 @@ +# -*- coding: utf-8 -*- +{ + 'name': 'Survey Custom Certificate Template', + 'version': '19.0.1.0.0', + 'category': 'Marketing/Surveys', + 'summary': 'Upload custom DOCX certificate templates for surveys with dynamic placeholders', + 'description': """ + Survey Custom Certificate Template + =================================== + + This module extends Odoo's Survey application to support custom certification templates. + + Key Features: + * Upload custom DOCX certificate templates with dynamic placeholders + * Automatic placeholder detection and mapping to survey data + * Preview certificates before issuing + * Generate personalized PDF certificates for survey participants + * Support for custom text and dynamic field mapping + + The module eliminates the need for manual certificate creation or XML/code-based + template design by allowing administrators to upload pre-designed DOCX files with + placeholder syntax (e.g., {key.name}, {key.course_name}). + """, + 'author': 'Your Organization', + 'website': 'https://www.yourorganization.com', + 'depends': [ + 'survey', + 'base', + 'mail', + ], + 'external_dependencies': { + 'python': ['docx'], + }, + 'data': [ + 'security/survey_custom_certificate_security.xml', + 'security/ir.model.access.csv', + 'views/survey_survey_views.xml', + 'wizards/survey_custom_certificate_wizard_views.xml', + ], + 'post_init_hook': 'post_init_hook', + 'installable': True, + 'auto_install': False, + 'application': False, + 'license': 'LGPL-3', +} diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md new file mode 100644 index 0000000..847a8c5 --- /dev/null +++ b/docs/ADMIN_GUIDE.md @@ -0,0 +1,669 @@ +# Survey Custom Certificate Template - Administrator Guide + +## Table of Contents + +1. [Installation](#installation) +2. [System Requirements](#system-requirements) +3. [Configuration](#configuration) +4. [Security](#security) +5. [Monitoring](#monitoring) +6. [Troubleshooting](#troubleshooting) +7. [Maintenance](#maintenance) + +--- + +## Installation + +### Prerequisites + +Before installing this module, ensure the following are in place: + +1. **Odoo 19** installed and running +2. **Survey module** installed and activated +3. **Python dependencies**: + - `python-docx` (for DOCX parsing) +4. **System dependencies**: + - LibreOffice (for PDF conversion) + +### Installing Python Dependencies + +```bash +# Activate your Odoo virtual environment +source /path/to/odoo/venv/bin/activate + +# Install python-docx +pip install python-docx +``` + +### Installing LibreOffice + +LibreOffice is required for converting DOCX files to PDF format. + +#### Ubuntu/Debian +```bash +sudo apt-get update +sudo apt-get install libreoffice +``` + +#### CentOS/RHEL +```bash +sudo yum install libreoffice +``` + +#### macOS +```bash +brew install --cask libreoffice +``` + +#### Verify Installation +```bash +libreoffice --version +``` + +You should see output like: `LibreOffice 7.x.x.x` + +### Installing the Module + +1. Copy the module to your Odoo addons directory: + ```bash + cp -r survey_custom_certificate_template /path/to/odoo/addons/ + ``` + +2. Update the addons list: + - Navigate to **Apps** in Odoo + - Click **Update Apps List** + - Search for "Survey Custom Certificate Template" + +3. Install the module: + - Click **Install** on the module card + +4. Verify installation: + - Open a survey + - Check that "Custom Template" appears in the Certification Template dropdown + +--- + +## System Requirements + +### Minimum Requirements + +- **Odoo**: Version 19.0 or later +- **Python**: 3.8 or later +- **RAM**: 2 GB minimum (4 GB recommended) +- **Disk Space**: 500 MB for LibreOffice + space for certificate storage +- **CPU**: 2 cores minimum (for PDF conversion) + +### Software Dependencies + +| Component | Version | Purpose | +|-----------|---------|---------| +| python-docx | >= 0.8.11 | DOCX parsing and manipulation | +| LibreOffice | >= 6.0 | PDF conversion | +| Odoo Survey | 19.0 | Base survey functionality | + +### Server Configuration + +#### File Upload Limits + +Ensure your server allows file uploads up to 10 MB: + +**Nginx Configuration** (`/etc/nginx/nginx.conf`): +```nginx +http { + client_max_body_size 10M; +} +``` + +**Odoo Configuration** (`odoo.conf`): +```ini +[options] +limit_memory_hard = 2684354560 +limit_memory_soft = 2147483648 +limit_request = 8192 +limit_time_cpu = 600 +limit_time_real = 1200 +``` + +#### LibreOffice Configuration + +For production environments, consider: + +1. **Headless Mode**: LibreOffice runs in headless mode (no GUI) +2. **Process Limits**: Limit concurrent LibreOffice processes to prevent resource exhaustion +3. **Timeout Settings**: Configure appropriate timeouts for PDF conversion + +--- + +## Configuration + +### Module Configuration + +No additional configuration is required after installation. The module extends the existing Survey module automatically. + +### Access Rights + +The module uses Odoo's standard Survey access groups: + +| Group | Access Level | Permissions | +|-------|--------------|-------------| +| Survey User | Read | View certificates | +| Survey Manager | Full | Upload, configure, delete templates | + +To grant access: +1. Navigate to **Settings** → **Users & Companies** → **Users** +2. Select a user +3. In the **Access Rights** tab, assign **Survey / Manager** role + +### File Storage + +Certificate templates are stored in the database as binary fields. Generated certificates can be stored as: + +1. **Attachments**: Linked to survey.user_input records +2. **Temporary Files**: For preview generation (automatically cleaned up) + +**Storage Location**: Odoo filestore (`~/.local/share/Odoo/filestore/[database_name]/`) + +### Performance Tuning + +#### PDF Conversion Optimization + +For high-volume certificate generation: + +1. **Queue-Based Processing**: Consider implementing a job queue for certificate generation +2. **Caching**: Cache parsed templates to avoid repeated parsing +3. **Batch Processing**: Generate certificates in batches during off-peak hours + +#### Resource Limits + +Monitor and adjust these limits based on your usage: + +```python +# In certificate_generator.py +LIBREOFFICE_TIMEOUT = 60 # seconds +MAX_CONCURRENT_CONVERSIONS = 3 +TEMP_FILE_CLEANUP_INTERVAL = 3600 # seconds +``` + +--- + +## Security + +### Access Control + +The module implements several security measures: + +1. **Group-Based Access**: Only Survey Managers can upload and configure templates +2. **Field-Level Security**: Sensitive fields restricted to appropriate groups +3. **Validation**: All user inputs are validated and sanitized + +### Data Sanitization + +The module automatically sanitizes: + +- **Placeholder values**: HTML escaping, control character removal +- **Custom text**: Length limits, special character filtering +- **Field names**: Alphanumeric validation, injection prevention + +### File Validation + +Uploaded files are validated for: + +- **File type**: Must be valid DOCX format +- **File size**: Maximum 10 MB +- **Structure**: Valid DOCX structure using python-docx +- **Content**: No executable content or macros + +### Security Best Practices + +✓ **Limit upload access**: Only trusted users should have Survey Manager role +✓ **Monitor logs**: Regularly review certificate generation logs +✓ **Update dependencies**: Keep python-docx and LibreOffice updated +✓ **Backup templates**: Maintain backups of certificate templates +✓ **Audit trail**: Monitor who uploads and modifies templates + +--- + +## Monitoring + +### Logging + +The module logs all significant events: + +#### Log Levels + +- **INFO**: Successful operations (template upload, certificate generation) +- **WARNING**: Non-critical issues (missing data, sanitization applied) +- **ERROR**: Failed operations (LibreOffice errors, validation failures) + +#### Log Locations + +**Odoo Log File**: `/var/log/odoo/odoo-server.log` + +#### Key Log Messages + +``` +# Successful template upload +INFO: Saved custom certificate template for survey 123 with 5 placeholder mappings + +# Certificate generation +INFO: Successfully generated certificate for user_input 456 (size: 245678 bytes) + +# LibreOffice error +ERROR: Certificate generation runtime error for user_input 789: LibreOffice not found + +# Data retrieval +DEBUG: Retrieved certificate data for user_input 101: 8 fields populated +``` + +### Monitoring Commands + +#### Check LibreOffice Availability +```bash +which libreoffice +libreoffice --version +``` + +#### Monitor Certificate Generation +```bash +# View recent certificate generation logs +tail -f /var/log/odoo/odoo-server.log | grep "certificate" + +# Count successful generations today +grep "Successfully generated certificate" /var/log/odoo/odoo-server.log | grep "$(date +%Y-%m-%d)" | wc -l + +# Find failed generations +grep "Certificate generation.*error" /var/log/odoo/odoo-server.log +``` + +#### Check Disk Space +```bash +# Check filestore disk usage +du -sh ~/.local/share/Odoo/filestore/[database_name]/ + +# Check temp directory +du -sh /tmp/ +``` + +### Performance Metrics + +Monitor these metrics: + +1. **Certificate Generation Time**: Should be < 10 seconds per certificate +2. **PDF Conversion Success Rate**: Should be > 99% +3. **Template Upload Success Rate**: Should be > 95% +4. **Disk Space Usage**: Monitor filestore growth + +### Alerts + +Set up alerts for: + +- **LibreOffice Failures**: More than 5 failures per hour +- **Disk Space**: Filestore > 80% capacity +- **Generation Errors**: More than 10% failure rate +- **Long Processing Times**: Certificate generation > 30 seconds + +--- + +## Troubleshooting + +### Common Administrator Issues + +#### Issue: LibreOffice Not Found + +**Symptoms:** +- Error: "LibreOffice not found or not accessible" +- Certificate generation fails +- Preview generation fails + +**Diagnosis:** +```bash +# Check if LibreOffice is installed +which libreoffice + +# Check if it's executable +libreoffice --version + +# Check PATH +echo $PATH +``` + +**Solutions:** +1. Install LibreOffice (see Installation section) +2. Ensure LibreOffice is in system PATH +3. Restart Odoo service after installation: + ```bash + sudo systemctl restart odoo + ``` + +--- + +#### Issue: PDF Conversion Timeout + +**Symptoms:** +- Error: "PDF conversion timed out" +- Long processing times +- Certificates not generated + +**Diagnosis:** +```bash +# Check system load +top + +# Check LibreOffice processes +ps aux | grep soffice + +# Check for zombie processes +ps aux | grep defunct +``` + +**Solutions:** +1. Increase timeout in configuration +2. Kill stuck LibreOffice processes: + ```bash + pkill -9 soffice + ``` +3. Restart Odoo service +4. Consider increasing server resources + +--- + +#### Issue: High Memory Usage + +**Symptoms:** +- Server slowdown during certificate generation +- Out of memory errors +- Odoo crashes + +**Diagnosis:** +```bash +# Monitor memory usage +free -h +watch -n 1 free -h + +# Check Odoo memory usage +ps aux | grep odoo + +# Check LibreOffice memory usage +ps aux | grep soffice +``` + +**Solutions:** +1. Limit concurrent certificate generations +2. Increase server RAM +3. Implement queue-based processing +4. Clean up temporary files: + ```bash + find /tmp -name "cert_*" -mtime +1 -delete + ``` + +--- + +#### Issue: Permission Denied Errors + +**Symptoms:** +- Error: "Permission denied" when generating certificates +- Cannot write to temp directory +- Cannot execute LibreOffice + +**Diagnosis:** +```bash +# Check temp directory permissions +ls -la /tmp + +# Check Odoo user +ps aux | grep odoo + +# Check LibreOffice permissions +ls -la $(which libreoffice) +``` + +**Solutions:** +1. Ensure Odoo user has write access to /tmp: + ```bash + sudo chmod 1777 /tmp + ``` +2. Ensure Odoo user can execute LibreOffice: + ```bash + sudo chmod +x /usr/bin/libreoffice + ``` +3. Check SELinux/AppArmor policies (if applicable) + +--- + +#### Issue: Database Errors + +**Symptoms:** +- Error: "Unable to save template configuration" +- Database constraint violations +- Rollback errors + +**Diagnosis:** +```bash +# Check database logs +sudo tail -f /var/log/postgresql/postgresql-*.log + +# Check database connections +sudo -u postgres psql -c "SELECT * FROM pg_stat_activity WHERE datname='your_database';" +``` + +**Solutions:** +1. Check database disk space +2. Verify database user permissions +3. Check for database locks: + ```sql + SELECT * FROM pg_locks WHERE NOT granted; + ``` +4. Restart database if necessary + +--- + +### Diagnostic Commands + +#### Generate Diagnostic Report +```bash +#!/bin/bash +# Save as: check_certificate_module.sh + +echo "=== Certificate Module Diagnostic Report ===" +echo "Date: $(date)" +echo "" + +echo "=== LibreOffice Status ===" +which libreoffice +libreoffice --version +echo "" + +echo "=== Python Dependencies ===" +pip list | grep python-docx +echo "" + +echo "=== Disk Space ===" +df -h | grep -E "Filesystem|/tmp|filestore" +echo "" + +echo "=== Memory Usage ===" +free -h +echo "" + +echo "=== Recent Certificate Logs ===" +tail -20 /var/log/odoo/odoo-server.log | grep -i certificate +echo "" + +echo "=== LibreOffice Processes ===" +ps aux | grep soffice | grep -v grep +echo "" + +echo "=== Temp Files ===" +ls -lh /tmp/cert_* 2>/dev/null | wc -l +echo " certificate temp files found" +``` + +Run with: +```bash +chmod +x check_certificate_module.sh +./check_certificate_module.sh +``` + +--- + +## Maintenance + +### Regular Maintenance Tasks + +#### Daily +- Monitor certificate generation logs +- Check for failed generations +- Verify LibreOffice is running + +#### Weekly +- Review disk space usage +- Clean up old temporary files +- Check for stuck LibreOffice processes + +#### Monthly +- Update python-docx if new version available +- Review and archive old certificates +- Audit template configurations +- Review access logs + +### Backup Procedures + +#### Backup Certificate Templates + +Templates are stored in the database, so they're included in regular database backups. For additional safety: + +```bash +# Export templates from database +psql your_database -c "COPY (SELECT id, title, custom_cert_template_filename FROM survey_survey WHERE has_custom_certificate = true) TO '/backup/certificate_templates.csv' CSV HEADER;" +``` + +#### Backup Generated Certificates + +```bash +# Backup filestore +tar -czf certificate_backup_$(date +%Y%m%d).tar.gz ~/.local/share/Odoo/filestore/[database_name]/ +``` + +### Update Procedures + +#### Updating the Module + +1. **Backup**: Create database backup before updating +2. **Update code**: Replace module files with new version +3. **Update module**: In Odoo, go to Apps → Update +4. **Test**: Verify certificate generation still works +5. **Monitor**: Watch logs for any errors + +#### Updating Dependencies + +```bash +# Update python-docx +pip install --upgrade python-docx + +# Update LibreOffice (Ubuntu/Debian) +sudo apt-get update +sudo apt-get upgrade libreoffice + +# Restart Odoo +sudo systemctl restart odoo +``` + +### Cleanup Procedures + +#### Clean Temporary Files + +```bash +# Remove old certificate temp files (older than 1 day) +find /tmp -name "cert_*" -mtime +1 -delete + +# Remove old LibreOffice temp files +find /tmp -name "OSL_PIPE_*" -mtime +1 -delete +``` + +#### Clean Old Certificates + +If storing certificates as attachments, periodically archive or delete old ones: + +```sql +-- Find old certificate attachments (older than 1 year) +SELECT id, name, create_date +FROM ir_attachment +WHERE name LIKE '%certificate%' +AND create_date < NOW() - INTERVAL '1 year'; + +-- Archive to external storage before deleting +``` + +### Performance Optimization + +#### Database Optimization + +```sql +-- Vacuum and analyze certificate-related tables +VACUUM ANALYZE survey_survey; +VACUUM ANALYZE survey_user_input; +VACUUM ANALYZE ir_attachment; +``` + +#### Index Optimization + +```sql +-- Add index for faster certificate lookups +CREATE INDEX IF NOT EXISTS idx_survey_has_custom_cert +ON survey_survey(has_custom_certificate) +WHERE has_custom_certificate = true; +``` + +--- + +## Support and Resources + +### Log Analysis + +For detailed troubleshooting, enable debug logging: + +```ini +# In odoo.conf +[options] +log_level = debug +log_handler = :DEBUG,werkzeug:WARNING,odoo.addons.survey_custom_certificate_template:DEBUG +``` + +### Getting Help + +1. **Check logs**: Always review logs first +2. **Run diagnostics**: Use the diagnostic script provided +3. **Community forums**: Search Odoo community for similar issues +4. **Module documentation**: Refer to USER_GUIDE.md for user-facing issues + +### Useful Commands Reference + +```bash +# Restart Odoo +sudo systemctl restart odoo + +# View Odoo logs in real-time +tail -f /var/log/odoo/odoo-server.log + +# Check Odoo status +sudo systemctl status odoo + +# Kill stuck LibreOffice processes +pkill -9 soffice + +# Check disk space +df -h + +# Check memory usage +free -h + +# Check running processes +ps aux | grep -E "odoo|soffice" +``` + +--- + +**Version**: 1.0 +**Last Updated**: 2024 +**Module**: survey_custom_certificate_template +**Odoo Version**: 19.0 diff --git a/docs/AUTOMATIC_FIELD_MAPPING.md b/docs/AUTOMATIC_FIELD_MAPPING.md new file mode 100644 index 0000000..9b53525 --- /dev/null +++ b/docs/AUTOMATIC_FIELD_MAPPING.md @@ -0,0 +1,215 @@ +# Automatic Field Mapping + +## Overview + +The Survey Custom Certificate Template module includes an automatic field mapping feature that recognizes common placeholder patterns and automatically maps them to appropriate survey or participant data fields. This reduces manual configuration effort and makes the certificate setup process more intuitive. + +## How It Works + +When a DOCX template is uploaded, the system: + +1. Extracts all placeholders matching the `{key.*}` pattern +2. For each placeholder, attempts to automatically map it to a data source +3. Recognizes common field name patterns (e.g., "name", "email", "date") +4. Maps recognized patterns to appropriate survey or participant fields +5. Defaults to "Custom Text" for unrecognized placeholders + +## Supported Field Patterns + +### Survey Fields + +These placeholders map to data from the `survey.survey` model: + +| Placeholder Pattern | Maps To | Description | +|-------------------|---------|-------------| +| `{key.title}` | survey_title | Survey title | +| `{key.survey_title}` | survey_title | Survey title | +| `{key.course_name}` | survey_title | Survey title (course name alias) | +| `{key.course}` | survey_title | Survey title (course alias) | +| `{key.coursename}` | survey_title | Survey title (no underscore) | +| `{key.survey_name}` | survey_title | Survey title (survey name alias) | +| `{key.surveyname}` | survey_title | Survey title (no underscore) | +| `{key.description}` | survey_description | Survey description | +| `{key.survey_description}` | survey_description | Survey description | +| `{key.course_description}` | survey_description | Survey description (course alias) | +| `{key.coursedescription}` | survey_description | Survey description (no underscore) | + +### Participant Fields + +These placeholders map to data from the `survey.user_input` model or related partner: + +#### Name Fields + +| Placeholder Pattern | Maps To | Description | +|-------------------|---------|-------------| +| `{key.name}` | partner_name | Participant's full name | +| `{key.participant_name}` | partner_name | Participant's full name | +| `{key.participantname}` | partner_name | Participant's full name (no underscore) | +| `{key.partner_name}` | partner_name | Participant's full name | +| `{key.partnername}` | partner_name | Participant's full name (no underscore) | +| `{key.student_name}` | partner_name | Participant's full name (student alias) | +| `{key.studentname}` | partner_name | Participant's full name (no underscore) | +| `{key.user_name}` | partner_name | Participant's full name (user alias) | +| `{key.username}` | partner_name | Participant's full name (no underscore) | +| `{key.fullname}` | partner_name | Participant's full name | +| `{key.full_name}` | partner_name | Participant's full name | + +#### Email Fields + +| Placeholder Pattern | Maps To | Description | +|-------------------|---------|-------------| +| `{key.email}` | partner_email | Participant's email address | +| `{key.participant_email}` | partner_email | Participant's email address | +| `{key.participantemail}` | partner_email | Participant's email address (no underscore) | +| `{key.partner_email}` | partner_email | Participant's email address | +| `{key.partneremail}` | partner_email | Participant's email address (no underscore) | +| `{key.student_email}` | partner_email | Participant's email address (student alias) | +| `{key.studentemail}` | partner_email | Participant's email address (no underscore) | +| `{key.user_email}` | partner_email | Participant's email address (user alias) | +| `{key.useremail}` | partner_email | Participant's email address (no underscore) | + +#### Date Fields + +| Placeholder Pattern | Maps To | Description | +|-------------------|---------|-------------| +| `{key.date}` | completion_date | Survey completion date | +| `{key.completion_date}` | completion_date | Survey completion date | +| `{key.completiondate}` | completion_date | Survey completion date (no underscore) | +| `{key.finish_date}` | completion_date | Survey completion date (finish alias) | +| `{key.finishdate}` | completion_date | Survey completion date (no underscore) | +| `{key.completed_date}` | completion_date | Survey completion date (completed alias) | +| `{key.completeddate}` | completion_date | Survey completion date (no underscore) | +| `{key.create_date}` | create_date | Survey submission date | +| `{key.createdate}` | create_date | Survey submission date (no underscore) | +| `{key.submission_date}` | create_date | Survey submission date | +| `{key.submissiondate}` | create_date | Survey submission date (no underscore) | + +#### Score Fields + +| Placeholder Pattern | Maps To | Description | +|-------------------|---------|-------------| +| `{key.score}` | scoring_percentage | Score as percentage | +| `{key.scoring_percentage}` | scoring_percentage | Score as percentage | +| `{key.scoringpercentage}` | scoring_percentage | Score as percentage (no underscore) | +| `{key.percentage}` | scoring_percentage | Score as percentage | +| `{key.percent}` | scoring_percentage | Score as percentage | +| `{key.grade}` | scoring_percentage | Score as percentage (grade alias) | +| `{key.result}` | scoring_percentage | Score as percentage (result alias) | +| `{key.scoring_total}` | scoring_total | Total score points | +| `{key.scoringtotal}` | scoring_total | Total score points (no underscore) | +| `{key.total_score}` | scoring_total | Total score points | +| `{key.totalscore}` | scoring_total | Total score points (no underscore) | +| `{key.points}` | scoring_total | Total score points | + +## Unrecognized Placeholders + +If a placeholder doesn't match any of the recognized patterns, it will be automatically set to "Custom Text" type with an empty value. Users can then: + +1. Manually select a different data source from the dropdown +2. Enter custom text to replace the placeholder +3. Leave it empty (placeholder will be replaced with an empty string) + +## Case Insensitivity + +The automatic mapping is **case-insensitive**. All of the following will map correctly: + +- `{key.Name}` → partner_name +- `{key.NAME}` → partner_name +- `{key.name}` → partner_name +- `{key.NaMe}` → partner_name + +## Examples + +### Example 1: Basic Certificate + +Template placeholders: +``` +Certificate of Completion + +This certifies that {key.name} has successfully completed +{key.course_name} on {key.date}. + +Score: {key.score}% +``` + +Automatic mappings: +- `{key.name}` → Participant Field: partner_name +- `{key.course_name}` → Survey Field: survey_title +- `{key.date}` → Participant Field: completion_date +- `{key.score}` → Participant Field: scoring_percentage + +### Example 2: Detailed Certificate + +Template placeholders: +``` +{key.title} + +Awarded to: {key.participant_name} +Email: {key.email} +Completion Date: {key.completion_date} +Grade: {key.grade}% +Total Points: {key.points} + +Description: {key.description} +``` + +Automatic mappings: +- `{key.title}` → Survey Field: survey_title +- `{key.participant_name}` → Participant Field: partner_name +- `{key.email}` → Participant Field: partner_email +- `{key.completion_date}` → Participant Field: completion_date +- `{key.grade}` → Participant Field: scoring_percentage +- `{key.points}` → Participant Field: scoring_total +- `{key.description}` → Survey Field: survey_description + +### Example 3: Custom Placeholders + +Template placeholders: +``` +Certificate + +Student: {key.student_name} +Course: {key.coursename} +Institution: {key.institution} +Instructor: {key.instructor} +``` + +Automatic mappings: +- `{key.student_name}` → Participant Field: partner_name +- `{key.coursename}` → Survey Field: survey_title +- `{key.institution}` → Custom Text: (empty - user must configure) +- `{key.instructor}` → Custom Text: (empty - user must configure) + +## Benefits + +1. **Faster Setup**: Reduces manual configuration time +2. **Intuitive**: Uses common naming conventions +3. **Flexible**: Supports multiple variations of the same field +4. **Safe**: Defaults to custom text for unknown fields +5. **User-Friendly**: Users can still override automatic mappings + +## Technical Implementation + +The automatic mapping is implemented in the `_auto_map_placeholder()` method of the `survey.custom.certificate.wizard` model. This method: + +1. Extracts the field name from the placeholder +2. Converts it to lowercase for case-insensitive matching +3. Checks against survey field patterns +4. Checks against user field patterns +5. Returns the appropriate value_type and value_field +6. Defaults to 'custom_text' if no match is found + +The method is called automatically during template parsing in `_parse_template_placeholders()`, which creates placeholder records with the automatic mappings pre-configured. + +## Validation: Requirements 2.5 + +This feature validates **Requirement 2.5** from the requirements document: + +> **Acceptance Criteria 2.5**: WHEN the system recognizes standard fields THEN the Survey System SHALL automatically populate the Value column with appropriate data sources + +The implementation successfully: +- ✓ Recognizes standard field patterns +- ✓ Automatically populates the Value column +- ✓ Maps to appropriate data sources (survey.survey and survey.user_input) +- ✓ Supports a wide range of common naming conventions +- ✓ Provides sensible defaults for unrecognized fields diff --git a/docs/LOGGING_MONITORING_QUICK_REFERENCE.md b/docs/LOGGING_MONITORING_QUICK_REFERENCE.md new file mode 100644 index 0000000..e01ead1 --- /dev/null +++ b/docs/LOGGING_MONITORING_QUICK_REFERENCE.md @@ -0,0 +1,305 @@ +# Logging and Monitoring - Quick Reference Guide + +## Overview + +This guide provides a quick reference for the logging and monitoring features of the Survey Custom Certificate Template module. + +## Log Levels + +| Level | Usage | Example | +|-------|-------|---------| +| **DEBUG** | Detailed diagnostic information | Data retrieval details, placeholder counts | +| **INFO** | General informational messages | Certificate generation start/success, template operations | +| **WARNING** | Warning messages for non-critical issues | Missing data, validation warnings | +| **ERROR** | Error messages for failures | Certificate generation failures, conversion errors | +| **CRITICAL** | Critical system issues | LibreOffice unavailability | + +## Key Log Patterns + +### Certificate Generation Logs + +``` +# Generation Start +INFO: === CERTIFICATE GENERATION START === | survey_id=X | user_input_id=Y | ... + +# Generation Success +INFO: === CERTIFICATE GENERATION SUCCESS === | survey_id=X | pdf_size_bytes=Z | duration_ms=W + +# Generation Failure +ERROR: === CERTIFICATE GENERATION FAILURE === | survey_id=X | error_type=... | error_message=... +``` + +### LibreOffice Logs + +``` +# Conversion Start +INFO: >>> LibreOffice conversion START | docx_path=... | attempt=X + +# Conversion Success +INFO: >>> LibreOffice conversion SUCCESS | pdf_size_bytes=Z | duration_ms=W + +# Conversion Failure +ERROR: >>> LibreOffice conversion FAILURE | exit_code=X | stderr=... + +# LibreOffice Unavailable +CRITICAL: !!! LIBREOFFICE UNAVAILABLE !!! | error_message=... +``` + +## Administrator Notifications + +### LibreOffice Unavailable + +**Trigger**: LibreOffice cannot be found or fails to execute + +**Throttling**: Once per hour + +**Recipients**: Users in `base.group_system` (Settings access) + +**Content**: +- Error details +- Installation instructions (Ubuntu, CentOS, macOS) +- Action required +- Context information + +### Repeated Generation Failures + +**Trigger**: 3 consecutive certificate generation failures for a survey + +**Throttling**: Once per hour per survey + +**Recipients**: Users in `base.group_system` (Settings access) + +**Content**: +- Survey information +- Failure count +- Recent error messages (last 5) +- Possible causes +- Recommended actions + +## Monitoring Checklist + +### Daily Checks +- [ ] Review ERROR and CRITICAL logs +- [ ] Check for LibreOffice unavailability alerts +- [ ] Monitor certificate generation success rate + +### Weekly Checks +- [ ] Review WARNING logs for patterns +- [ ] Check average generation duration +- [ ] Verify notification throttling is working +- [ ] Review failure counts per survey + +### Monthly Checks +- [ ] Analyze performance trends +- [ ] Review log file sizes and rotation +- [ ] Update notification thresholds if needed +- [ ] Check for recurring error patterns + +## Troubleshooting Guide + +### Issue: LibreOffice Unavailable + +**Symptoms**: +- CRITICAL logs about LibreOffice +- Administrator notifications +- Certificate generation fails + +**Resolution**: +1. Install LibreOffice: + ```bash + # Ubuntu/Debian + sudo apt-get install libreoffice + + # CentOS/RHEL + sudo yum install libreoffice + + # macOS + brew install --cask libreoffice + ``` +2. Restart Odoo service +3. Verify with: `libreoffice --version` + +### Issue: Repeated Generation Failures + +**Symptoms**: +- Multiple ERROR logs for same survey +- Administrator notification after 3 failures + +**Resolution**: +1. Check Odoo logs for specific error messages +2. Verify template file is valid DOCX +3. Check placeholder mappings configuration +4. Verify server resources (disk space, memory) +5. Test certificate generation manually +6. Review LibreOffice subprocess logs + +### Issue: High Generation Duration + +**Symptoms**: +- `duration_ms` values consistently high in logs + +**Resolution**: +1. Check server CPU and memory usage +2. Verify LibreOffice is not running multiple instances +3. Check template file size +4. Consider optimizing template (compress images) +5. Review concurrent generation load + +## Configuration + +### Notification Throttling + +**File**: `services/admin_notifier.py` + +```python +# Change throttle period (default: 60 minutes) +AdminNotifier.THROTTLE_MINUTES = 120 # 2 hours +``` + +### Failure Threshold + +**File**: `services/admin_notifier.py` + +```python +# Change failure threshold (default: 3) +AdminNotifier.FAILURE_THRESHOLD = 5 # Notify after 5 failures +``` + +### Log Level + +**File**: `odoo.conf` + +```ini +[options] +log_level = info # debug, info, warning, error, critical +``` + +## Useful Log Queries + +### Find All Certificate Generation Failures +```bash +grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log +``` + +### Find LibreOffice Errors +```bash +grep "LibreOffice" /var/log/odoo/odoo.log | grep -E "ERROR|CRITICAL" +``` + +### Count Successful Generations Today +```bash +grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | grep "$(date +%Y-%m-%d)" | wc -l +``` + +### Find Slow Generations (>5 seconds) +```bash +grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | grep -E "duration_ms=[5-9][0-9]{3}|duration_ms=[1-9][0-9]{4}" +``` + +### Check Notification History +```bash +grep "Sent.*notification to.*administrators" /var/log/odoo/odoo.log +``` + +## Performance Metrics + +### Key Metrics to Track + +| Metric | Good | Warning | Critical | +|--------|------|---------|----------| +| Generation Duration | <3s | 3-10s | >10s | +| Success Rate | >95% | 90-95% | <90% | +| PDF Size | <500KB | 500KB-2MB | >2MB | +| LibreOffice Conversion | <2s | 2-5s | >5s | + +### Calculating Metrics + +**Success Rate**: +```bash +# Count successes +SUCCESS=$(grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | wc -l) + +# Count failures +FAILURES=$(grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log | wc -l) + +# Calculate rate +echo "scale=2; $SUCCESS / ($SUCCESS + $FAILURES) * 100" | bc +``` + +**Average Duration**: +```bash +grep "CERTIFICATE GENERATION SUCCESS" /var/log/odoo/odoo.log | \ + grep -oP "duration_ms=\K[0-9.]+" | \ + awk '{sum+=$1; count++} END {print sum/count}' +``` + +## Best Practices + +### For Developers +1. Always use CertificateLogger for certificate operations +2. Include relevant context in log calls +3. Use appropriate log levels +4. Log both start and end of operations +5. Include duration metrics for performance tracking + +### For Administrators +1. Monitor CRITICAL and ERROR logs daily +2. Set up log rotation to manage disk space +3. Configure external monitoring for CRITICAL logs +4. Review notification settings based on usage +5. Keep LibreOffice updated + +### For Production +1. Set log level to INFO (not DEBUG) +2. Configure log rotation (daily or weekly) +3. Set up external log aggregation +4. Monitor disk space for log files +5. Test notification delivery regularly + +## Support + +### Getting Help + +1. **Check Logs**: Review Odoo logs for detailed error messages +2. **Check Notifications**: Review administrator notifications for guidance +3. **Test Manually**: Try generating a certificate manually from survey form +4. **Verify LibreOffice**: Run `libreoffice --version` to verify installation +5. **Check Resources**: Verify server has adequate disk space and memory + +### Reporting Issues + +When reporting issues, include: +- Relevant log excerpts (with timestamps) +- Survey ID and title +- Error messages from notifications +- LibreOffice version (`libreoffice --version`) +- Odoo version +- Steps to reproduce + +## Quick Commands + +```bash +# View real-time logs +tail -f /var/log/odoo/odoo.log | grep -E "CERTIFICATE|LibreOffice" + +# Check LibreOffice installation +libreoffice --version + +# Test LibreOffice conversion +libreoffice --headless --convert-to pdf --outdir /tmp /path/to/test.docx + +# Count today's certificate generations +grep "CERTIFICATE GENERATION" /var/log/odoo/odoo.log | grep "$(date +%Y-%m-%d)" | wc -l + +# Find recent failures +grep "CERTIFICATE GENERATION FAILURE" /var/log/odoo/odoo.log | tail -20 + +# Check notification throttling +grep "Notification throttled" /var/log/odoo/odoo.log | tail -10 +``` + +--- + +**Last Updated**: 2024-01-15 + +**Module Version**: 19.0.1.0.0 diff --git a/docs/PERFORMANCE_OPTIMIZATION.md b/docs/PERFORMANCE_OPTIMIZATION.md new file mode 100644 index 0000000..e179012 --- /dev/null +++ b/docs/PERFORMANCE_OPTIMIZATION.md @@ -0,0 +1,248 @@ +# Performance Optimization Guide + +## Overview + +This document describes the performance optimizations implemented in the Survey Custom Certificate Template module to ensure efficient certificate generation at scale. + +## Implemented Optimizations + +### 1. Template Caching + +#### Certificate Generator Template Cache +- **Location**: `services/certificate_generator.py` +- **Cache Size**: 50 templates (LRU eviction) +- **Cache Key**: SHA256 hash of template binary content +- **Benefits**: + - Avoids repeated parsing of the same template + - Reduces memory allocation for frequently used templates + - Improves response time for bulk certificate generation + +**Usage**: +```python +generator = CertificateGenerator() + +# Use caching (default) +pdf = generator.generate_certificate(template_binary, mappings, data) + +# Disable caching if needed +pdf = generator.generate_certificate(template_binary, mappings, data, use_cache=False) + +# Clear cache manually +CertificateGenerator.clear_template_cache() +``` + +#### Template Parser Placeholder Cache +- **Location**: `services/certificate_template_parser.py` +- **Cache Size**: 100 templates (LRU eviction) +- **Cache Key**: SHA256 hash of template binary content +- **Benefits**: + - Eliminates redundant placeholder extraction + - Speeds up wizard template upload + - Reduces CPU usage during template configuration + +**Usage**: +```python +parser = CertificateTemplateParser() + +# Use caching (default) +placeholders = parser.parse_template(docx_binary) + +# Disable caching if needed +placeholders = parser.parse_template(docx_binary, use_cache=False) + +# Clear cache manually +CertificateTemplateParser.clear_cache() +``` + +### 2. LibreOffice Optimization + +#### Cached Availability Check +- **Location**: `services/certificate_generator.py` +- **Implementation**: Class-level cache for LibreOffice availability +- **Benefits**: + - Avoids repeated system calls to check LibreOffice + - Reduces overhead for each certificate generation + - Faster error detection when LibreOffice is unavailable + +**Reset Cache**: +```python +# Reset after installing LibreOffice +CertificateGenerator.reset_libreoffice_check() +``` + +#### Optimized Subprocess Calls +- **Retry Mechanism**: Exponential backoff (2^attempt seconds, max 5s) +- **Timeout Optimization**: + - First attempt: 45 seconds + - Retry attempts: 30 seconds +- **Additional Flags**: + - `--norestore`: Skip session restoration + - `--nofirststartwizard`: Skip first-start wizard +- **Benefits**: + - Faster failure detection + - Reduced resource consumption + - Better handling of transient failures + +### 3. File Cleanup Optimization + +#### Efficient Temporary File Management +- **Location**: `services/certificate_generator.py` +- **Implementation**: `_cleanup_temp_directory()` method +- **Features**: + - Single directory listing operation + - Selective file preservation + - Graceful error handling +- **Benefits**: + - Prevents disk space exhaustion + - Reduces I/O operations + - Minimizes cleanup overhead + +**Cleanup Behavior**: +```python +# Automatic cleanup in finally block +pdf = generator.convert_to_pdf(docx_path) + +# Cleanup with file preservation +pdf = generator.convert_to_pdf(docx_path, cleanup_on_error=False) +``` + +## Performance Metrics + +### Expected Improvements + +| Operation | Before Optimization | After Optimization | Improvement | +|-----------|-------------------|-------------------|-------------| +| Template parsing (cached) | ~200ms | ~5ms | 97.5% | +| LibreOffice check | ~100ms | ~1ms (cached) | 99% | +| Certificate generation (same template) | ~3s | ~2.5s | 16.7% | +| Bulk generation (100 certs) | ~300s | ~250s | 16.7% | + +*Note: Actual performance depends on hardware, template complexity, and LibreOffice version.* + +### Memory Usage + +- **Template Cache**: ~5-10 MB per template (50 templates = ~250-500 MB max) +- **Placeholder Cache**: ~1 KB per template (100 templates = ~100 KB max) +- **Total Cache Overhead**: ~250-500 MB (acceptable for production) + +## Cache Management + +### When to Clear Caches + +1. **Template Updates**: Clear caches when templates are modified +2. **Memory Pressure**: Clear caches if system memory is low +3. **Testing**: Clear caches between test runs for consistency + +### Manual Cache Clearing + +```python +# Clear all caches +from odoo.addons.survey_custom_certificate_template.services.certificate_generator import CertificateGenerator +from odoo.addons.survey_custom_certificate_template.services.certificate_template_parser import CertificateTemplateParser + +CertificateGenerator.clear_template_cache() +CertificateTemplateParser.clear_cache() +CertificateGenerator.reset_libreoffice_check() +``` + +### Automatic Cache Eviction + +Both caches implement LRU (Least Recently Used) eviction: +- When cache is full, oldest entry is removed +- Ensures bounded memory usage +- Maintains most frequently used templates + +## Best Practices + +### 1. Template Design +- Keep templates under 5 MB for optimal performance +- Minimize complex formatting and embedded objects +- Use simple placeholder patterns + +### 2. Bulk Generation +- Generate certificates in batches of 50-100 +- Use the same template for multiple certificates to leverage caching +- Monitor system resources during bulk operations + +### 3. Production Deployment +- Ensure LibreOffice is installed and accessible +- Allocate sufficient memory for caching (1-2 GB recommended) +- Monitor cache hit rates in logs + +### 4. Monitoring +- Check logs for cache hit/miss rates +- Monitor LibreOffice subprocess execution times +- Track temporary file cleanup success + +## Troubleshooting + +### High Memory Usage +**Symptom**: Server memory usage increases over time + +**Solutions**: +1. Reduce cache sizes in code: + ```python + CertificateGenerator._template_cache_max_size = 25 # Reduce from 50 + CertificateTemplateParser._placeholder_cache_max_size = 50 # Reduce from 100 + ``` +2. Clear caches periodically via cron job +3. Restart Odoo service to reset caches + +### Slow Certificate Generation +**Symptom**: Certificate generation takes longer than expected + +**Solutions**: +1. Check LibreOffice availability: `libreoffice --version` +2. Verify cache is being used (check logs for "cache hit" messages) +3. Reduce template complexity +4. Increase LibreOffice timeout if conversions are timing out + +### Cache Inconsistency +**Symptom**: Updated templates not reflecting changes + +**Solutions**: +1. Clear caches after template updates +2. Disable caching during development/testing +3. Use unique template filenames to force cache miss + +## Configuration + +### Environment Variables + +```bash +# Disable caching globally (for testing) +export SURVEY_CERT_DISABLE_CACHE=1 + +# Adjust cache sizes +export SURVEY_CERT_TEMPLATE_CACHE_SIZE=25 +export SURVEY_CERT_PLACEHOLDER_CACHE_SIZE=50 + +# Adjust LibreOffice timeout +export SURVEY_CERT_LIBREOFFICE_TIMEOUT=60 +``` + +*Note: These environment variables are examples and would need to be implemented in the code if required.* + +## Future Optimizations + +### Potential Improvements +1. **Distributed Caching**: Use Redis for multi-instance deployments +2. **Async Generation**: Queue-based certificate generation for large batches +3. **Template Precompilation**: Pre-process templates at upload time +4. **PDF Caching**: Cache generated PDFs for identical data +5. **Connection Pooling**: Maintain persistent LibreOffice processes + +### Performance Monitoring +Consider implementing: +- Prometheus metrics for cache hit rates +- APM integration for performance tracking +- Custom logging for performance analysis + +## Summary + +The implemented optimizations provide significant performance improvements for certificate generation: +- **Template caching** reduces parsing overhead +- **LibreOffice optimization** improves PDF conversion efficiency +- **File cleanup** prevents resource leaks + +These optimizations ensure the module can handle production workloads efficiently while maintaining code simplicity and maintainability. diff --git a/docs/QUICK_START_AUTO_MAPPING.md b/docs/QUICK_START_AUTO_MAPPING.md new file mode 100644 index 0000000..a16d285 --- /dev/null +++ b/docs/QUICK_START_AUTO_MAPPING.md @@ -0,0 +1,101 @@ +# Quick Start: Automatic Field Mapping + +## What is Automatic Field Mapping? + +When you upload a certificate template, the system automatically recognizes common placeholder names and maps them to the correct data fields. This saves you time and makes setup easier! + +## How to Use It + +### Step 1: Create Your Template + +In your DOCX template, use placeholders like: +``` +{key.name} +{key.email} +{key.course_name} +{key.date} +{key.score} +``` + +### Step 2: Upload the Template + +1. Go to your survey configuration +2. Select "Custom Template" for certification +3. Click "Configure Custom Certificate" +4. Upload your DOCX file + +### Step 3: Review Automatic Mappings + +The system will automatically map your placeholders: +- `{key.name}` → Participant Name +- `{key.email}` → Participant Email +- `{key.course_name}` → Survey Title +- `{key.date}` → Completion Date +- `{key.score}` → Score Percentage + +### Step 4: Adjust if Needed + +You can change any automatic mapping: +1. Click the dropdown in the "Value" column +2. Select a different data source +3. Or enter custom text + +### Step 5: Save and Generate + +Click "Save" and your certificates will use the configured mappings! + +## Common Placeholder Names + +### For Participant Information +- **Name**: `{key.name}`, `{key.participant_name}`, `{key.student_name}` +- **Email**: `{key.email}`, `{key.participant_email}` + +### For Course Information +- **Title**: `{key.title}`, `{key.course_name}`, `{key.course}` +- **Description**: `{key.description}`, `{key.course_description}` + +### For Dates +- **Completion**: `{key.date}`, `{key.completion_date}`, `{key.finish_date}` +- **Submission**: `{key.submission_date}`, `{key.create_date}` + +### For Scores +- **Percentage**: `{key.score}`, `{key.grade}`, `{key.percentage}` +- **Total Points**: `{key.points}`, `{key.total_score}` + +## Tips + +✅ **Use common names** - The system recognizes standard field names +✅ **Case doesn't matter** - `{key.Name}` and `{key.name}` work the same +✅ **Underscores optional** - `{key.coursename}` and `{key.course_name}` both work +✅ **Preview first** - Always preview your certificate before saving +✅ **Custom fields** - Unknown placeholders default to custom text (you can fill them in manually) + +## Example Template + +``` +Certificate of Completion + +This certifies that {key.name} has successfully completed +{key.course_name} on {key.date}. + +Email: {key.email} +Score: {key.score}% + +Congratulations! +``` + +**Automatic Mappings**: +- `{key.name}` → Participant Name ✅ +- `{key.course_name}` → Survey Title ✅ +- `{key.date}` → Completion Date ✅ +- `{key.email}` → Participant Email ✅ +- `{key.score}` → Score Percentage ✅ + +All done automatically! 🎉 + +## Need Help? + +See the full documentation in `AUTOMATIC_FIELD_MAPPING.md` for: +- Complete list of all supported field patterns +- Advanced usage examples +- Technical details diff --git a/docs/SECURITY_ARCHITECTURE.md b/docs/SECURITY_ARCHITECTURE.md new file mode 100644 index 0000000..c3c3ac6 --- /dev/null +++ b/docs/SECURITY_ARCHITECTURE.md @@ -0,0 +1,385 @@ +# Security Architecture + +## Overview + +This document provides a visual representation of the security architecture implemented in the Survey Custom Certificate Template module. + +## Security Layers + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ USER INTERFACE │ +│ - Form validation │ +│ - Field visibility based on groups │ +│ - Client-side input constraints │ +└────────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ ACCESS CONTROL LAYER │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Record Rules (ir.rule) │ │ +│ │ - Survey managers: Full access │ │ +│ │ - Survey users: Read-only, own records │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Model Access (ir.model.access) │ │ +│ │ - CRUD permissions per group │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Field-Level Security │ │ +│ │ - Sensitive fields restricted to managers │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ APPLICATION LAYER │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Input Validation │ │ +│ │ - _validate_placeholder_key() │ │ +│ │ - _validate_json_structure() │ │ +│ │ - _validate_and_sanitize_placeholders() │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Input Sanitization │ │ +│ │ - _sanitize_placeholder_value() │ │ +│ │ - _sanitize_certificate_value() │ │ +│ │ - HTML escaping, tag stripping │ │ +│ │ - Control character removal │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Business Logic Validation │ │ +│ │ - File format validation │ │ +│ │ - File size limits │ │ +│ │ - Template structure validation │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ DATABASE LAYER │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Database Constraints (@api.constrains) │ │ +│ │ - _check_source_key() │ │ +│ │ - _check_value_field() │ │ +│ │ - _check_custom_text() │ │ +│ │ - _check_custom_cert_mappings() │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Data Integrity │ │ +│ │ - Foreign key constraints │ │ +│ │ - Required field enforcement │ │ +│ │ - Data type validation │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Data Flow with Security Checks + +``` +User Input + │ + ▼ +┌─────────────────────┐ +│ UI Validation │ ← Field constraints, required fields +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Access Control │ ← Check user permissions +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Input Validation │ ← Validate format, length, pattern +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Input Sanitization │ ← Escape HTML, remove control chars +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Business Logic │ ← Apply business rules +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Database Constraint │ ← Final validation at DB level +└──────┬──────────────┘ + │ + ▼ + Database +``` + +## Attack Surface and Mitigations + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ ATTACK VECTORS │ +└──────────────────────────────────────────────────────────────────┘ + +1. XSS (Cross-Site Scripting) + Input: + ↓ + Mitigation: HTML escaping + tag stripping + ↓ + Output: <script>alert('XSS')</script> → (stripped) + +2. SQL Injection + Input: field'; DROP TABLE users-- + ↓ + Mitigation: Character whitelisting (alphanumeric, _, .) + ↓ + Result: REJECTED (invalid characters) + +3. Command Injection + Input: field; rm -rf / + ↓ + Mitigation: Pattern validation + character whitelisting + ↓ + Result: REJECTED (invalid format) + +4. Path Traversal + Input: ../../etc/passwd + ↓ + Mitigation: No path separators allowed in field names + ↓ + Result: REJECTED (invalid characters) + +5. DoS (Denial of Service) + Input: 100MB file or 1,000,000 character text + ↓ + Mitigation: File size limit (10MB) + text length limit (1000 chars) + ↓ + Result: REJECTED (exceeds limits) + +6. Data Corruption + Input: Malformed JSON structure + ↓ + Mitigation: JSON validation + structure validation + ↓ + Result: REJECTED (invalid structure) +``` + +## Access Control Matrix + +``` +┌────────────────────────────────────────────────────────────────┐ +│ PERMISSION MATRIX │ +├────────────────┬───────────┬───────────┬──────────┬────────────┤ +│ Resource │ Manager │ User │ Portal │ Public │ +├────────────────┼───────────┼───────────┼──────────┼────────────┤ +│ Wizard │ CRUD │ R (own) │ None │ None │ +│ Placeholder │ CRUD │ R (own) │ None │ None │ +│ Survey (cert) │ CRUD │ R (own) │ None │ None │ +│ Template File │ RW │ None │ None │ None │ +│ Mappings │ RW │ None │ None │ None │ +│ Has Cert Flag │ RW │ R │ None │ None │ +└────────────────┴───────────┴───────────┴──────────┴────────────┘ + +Legend: + C = Create, R = Read, U = Update, D = Delete, W = Write + (own) = Only records created by the user +``` + +## Validation Pipeline + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ VALIDATION PIPELINE │ +└─────────────────────────────────────────────────────────────────┘ + +Placeholder Key: {key.field_name} + │ + ├─► Length Check (max 200 chars) ──────────► PASS/FAIL + │ + ├─► Pattern Match (regex) ─────────────────► PASS/FAIL + │ Pattern: ^\{key\.[a-zA-Z0-9_]+\}$ + │ + └─► Character Whitelist ───────────────────► PASS/FAIL + Allowed: letters, numbers, _, {, }, . + +Value Field: partner_id.name + │ + ├─► Length Check (max 200 chars) ──────────► PASS/FAIL + │ + ├─► Character Whitelist ───────────────────► PASS/FAIL + │ Allowed: letters, numbers, _, . + │ + └─► No Special Chars ──────────────────────► PASS/FAIL + Rejected: -, ', ", ;, <, >, etc. + +Custom Text: "Sample text" + │ + ├─► Length Check (max 1000 chars) ─────────► PASS/FAIL + │ + ├─► HTML Escape ───────────────────────────► SANITIZED + │ < → <, > → >, etc. + │ + ├─► Control Char Removal ──────────────────► SANITIZED + │ Remove: \x00-\x08, \x0B-\x0C, etc. + │ + └─► Tag Stripping ─────────────────────────► SANITIZED + Remove: ` + - `` + +2. **Test with SQL injection**: + - `field'; DROP TABLE users--` + - `1' OR '1'='1` + +3. **Test with path traversal**: + - `../../etc/passwd` + - `..\..\..\windows\system32` + +4. **Test with long inputs**: + - 1001+ character custom text + - 201+ character field names + +5. **Test with malformed JSON**: + - Missing braces + - Invalid structure + - Wrong data types + +### Automated Security Tests + +Run the security test suite: + +```bash +odoo-bin -c odoo.conf -d database_name -i survey_custom_certificate_template --test-enable --stop-after-init +``` + +Or run specific test: + +```bash +odoo-bin -c odoo.conf -d database_name --test-tags survey_custom_certificate_template.test_security_validation +``` + +## Security Checklist + +Before deploying to production: + +- [ ] All users have appropriate access levels +- [ ] Field-level security is configured +- [ ] Input validation is working +- [ ] Sanitization is applied to all user inputs +- [ ] JSON validation is enforced +- [ ] Database constraints are active +- [ ] Security tests pass +- [ ] Logs are monitored +- [ ] File size limits are enforced +- [ ] Error messages don't leak sensitive information + +## Support + +For security issues or questions: + +1. Check this guide first +2. Review the implementation documentation +3. Run security tests +4. Contact system administrator +5. Report security vulnerabilities privately + +## Version + +Document Version: 1.0 +Last Updated: 2024 +Module Version: 19.0.1.0.0 diff --git a/docs/TEMPLATE_DELETION_GUIDE.md b/docs/TEMPLATE_DELETION_GUIDE.md new file mode 100644 index 0000000..4fc80e6 --- /dev/null +++ b/docs/TEMPLATE_DELETION_GUIDE.md @@ -0,0 +1,182 @@ +# Template Deletion Guide + +## Quick Reference: Deleting Custom Certificate Templates + +### Overview +This guide explains how to delete custom certificate templates from surveys and revert to default template options. + +## When to Delete a Template + +You might want to delete a custom certificate template when: +- You no longer need custom certificates for a survey +- You want to switch back to Odoo's default certificate templates +- You need to start fresh with a new template design +- The template is outdated or incorrect + +## How to Delete a Template + +### Step-by-Step Instructions + +1. **Navigate to Survey** + - Go to Surveys app + - Open the survey with the custom certificate template + +2. **Locate Delete Button** + - Scroll to the "Certification" section + - Find the "Delete Custom Certificate" button + - The button appears only when: + - Certification Report Layout = "Custom Template" + - A custom template is configured + +3. **Delete Template** + - Click "Delete Custom Certificate" button + - Confirm deletion in the dialog box + - Wait for success notification + +4. **Verify Deletion** + - Custom certificate fields are cleared + - Certification Report Layout is reset + - You can now select default templates + +## What Gets Deleted + +When you delete a custom certificate template, the following data is removed: + +### Cleared Fields +- ✓ Custom certificate template file (DOCX) +- ✓ Template filename +- ✓ Placeholder mappings (JSON) +- ✓ Custom certificate flag +- ✓ Certification report layout selection + +### Preserved Data +- ✓ Survey configuration +- ✓ Survey questions and answers +- ✓ Participant responses +- ✓ Previously generated certificates (as attachments) + +## Important Notes + +### Confirmation Required +- Deletion requires confirmation +- Action cannot be undone +- Previously generated certificates remain available + +### Survey-Specific +- Deleting a template from one survey doesn't affect other surveys +- Each survey maintains its own custom template independently + +### Default Reversion +- After deletion, certification_report_layout is reset to "no selection" +- You can then choose from Odoo's default certificate templates +- Or upload a new custom template + +## Error Scenarios + +### No Template to Delete +**Error:** "No custom certificate template to delete." + +**Cause:** Survey doesn't have a custom certificate configured + +**Solution:** Verify the survey has a custom template before attempting deletion + +### Button Not Visible +**Cause:** One of the following conditions: +- Certification Report Layout is not set to "Custom Template" +- No custom template is configured (has_custom_certificate = False) + +**Solution:** Check survey configuration and ensure custom template exists + +## After Deletion + +### Next Steps +After deleting a custom certificate template, you can: + +1. **Use Default Templates** + - Select from Odoo's built-in certificate templates + - Configure using standard Odoo options + +2. **Upload New Template** + - Click "Upload Custom Certificate" button + - Follow the template configuration wizard + - Configure new placeholder mappings + +3. **Disable Certification** + - Leave certification_report_layout empty + - Survey will not generate certificates + +## Technical Details + +### Database Changes +```python +# Fields set to False after deletion +{ + 'custom_cert_template': False, + 'custom_cert_template_filename': False, + 'custom_cert_mappings': False, + 'has_custom_certificate': False, + 'certification_report_layout': False, +} +``` + +### Logging +Deletion actions are logged with: +- Survey ID +- Timestamp +- Action type (deletion) + +### Notification +Success notification displays: +- Title: "Template Deleted" +- Message: "Custom certificate template has been deleted successfully." +- Type: Success (green) + +## Best Practices + +### Before Deletion +1. **Backup Template**: Download the template file if you might need it later +2. **Document Mappings**: Note the placeholder mappings for reference +3. **Check Dependencies**: Verify no active processes depend on the template +4. **Inform Users**: Notify stakeholders about the change + +### After Deletion +1. **Verify State**: Confirm all custom certificate fields are cleared +2. **Test Workflow**: Ensure survey still functions correctly +3. **Update Documentation**: Update any documentation referencing the custom template +4. **Monitor**: Check that certificate generation works with new settings + +## Troubleshooting + +### Problem: Delete button not working +**Solution:** +1. Check browser console for errors +2. Verify user has appropriate permissions +3. Refresh the page and try again +4. Check Odoo logs for error messages + +### Problem: Template still appears after deletion +**Solution:** +1. Refresh the browser page +2. Clear browser cache +3. Check database directly to verify deletion +4. Contact system administrator + +### Problem: Cannot select default templates after deletion +**Solution:** +1. Verify certification_report_layout field is cleared +2. Check if default templates are available in your Odoo installation +3. Restart Odoo server if necessary + +## Support + +For additional help: +- Check Odoo logs: `/var/log/odoo/odoo.log` +- Review module documentation +- Contact system administrator +- Refer to Odoo Survey documentation + +## Related Documentation + +- [Template Update Guide](TEMPLATE_UPDATE_DELETE_GUIDE.md) +- [Custom Certificate Configuration](TASK_13_IMPLEMENTATION.md) +- [Multi-Survey Template Management](TASK_12_1_SUMMARY.md) diff --git a/docs/TEMPLATE_UPDATE_DELETE_GUIDE.md b/docs/TEMPLATE_UPDATE_DELETE_GUIDE.md new file mode 100644 index 0000000..b979258 --- /dev/null +++ b/docs/TEMPLATE_UPDATE_DELETE_GUIDE.md @@ -0,0 +1,250 @@ +# Template Update and Deletion - User Guide + +## Quick Reference + +### Updating a Custom Certificate Template + +**When to Update:** +- You want to change the design of your certificate +- You need to add or remove placeholders +- You're fixing formatting issues in the template + +**Steps:** +1. Navigate to your survey configuration +2. Ensure "Custom Template" is selected in Certification Template +3. Click "Upload Custom Certificate" button +4. You'll see a blue notification: "You are updating an existing template" +5. Upload your new DOCX template +6. Click "Parse Template" +7. Review the placeholder mappings: + - Existing placeholders keep their configured mappings + - New placeholders are automatically mapped +8. Adjust any mappings as needed +9. Click "Generate Preview" to verify +10. Click "Save" to apply changes + +**What Gets Preserved:** +- ✅ Mappings for placeholders that exist in both old and new templates +- ✅ Custom text values you configured +- ✅ Field selections (survey fields, participant fields) + +**What Changes:** +- ❌ Placeholders removed from new template (mappings discarded) +- ➕ New placeholders get automatic mapping (you can adjust) + +### Deleting a Custom Certificate Template + +**When to Delete:** +- You want to switch back to Odoo's default certificate templates +- You no longer need custom certificates for this survey +- You want to start fresh with a new template + +**Steps:** +1. Navigate to your survey configuration +2. Ensure "Custom Template" is selected in Certification Template +3. Click "Delete Custom Certificate" button (trash icon) +4. Confirm deletion in the dialog +5. Template is deleted and survey reverts to default + +**What Gets Deleted:** +- ❌ Custom template file +- ❌ All placeholder mappings +- ❌ Custom certificate configuration + +**What Happens After:** +- Survey reverts to no template selection +- You can choose a different template option +- Other surveys are not affected + +## Detailed Examples + +### Example 1: Adding a New Field to Your Certificate + +**Scenario:** You want to add the participant's email address to your certificate. + +**Current Template:** Contains `{key.name}` and `{key.course_name}` + +**Steps:** +1. Edit your DOCX template to add `{key.email}` +2. Open the wizard (it will show "updating" notification) +3. Upload the modified template +4. Click "Parse Template" +5. Observe: + - `{key.name}` still mapped to "partner_name" ✅ + - `{key.course_name}` still mapped to "survey_title" ✅ + - `{key.email}` automatically mapped to "partner_email" ➕ +6. Save the configuration + +**Result:** Your existing mappings are preserved, and the new email field is ready to use. + +### Example 2: Changing Certificate Design + +**Scenario:** You want to use a new design with different colors and layout, but same data fields. + +**Current Template:** Professional blue design with `{key.name}`, `{key.course_name}`, `{key.date}` + +**New Template:** Modern green design with same placeholders + +**Steps:** +1. Create new DOCX with same placeholders but new design +2. Open the wizard +3. Upload the new template +4. Click "Parse Template" +5. All mappings are automatically preserved ✅ +6. Click "Generate Preview" to see new design +7. Save if satisfied + +**Result:** New design applied with zero reconfiguration needed. + +### Example 3: Simplifying Your Certificate + +**Scenario:** You want to remove some fields to make the certificate simpler. + +**Current Template:** Contains `{key.name}`, `{key.course_name}`, `{key.date}`, `{key.score}`, `{key.email}` + +**New Template:** Contains only `{key.name}` and `{key.course_name}` + +**Steps:** +1. Edit your DOCX to remove unwanted placeholders +2. Open the wizard +3. Upload the simplified template +4. Click "Parse Template" +5. Observe: + - `{key.name}` mapping preserved ✅ + - `{key.course_name}` mapping preserved ✅ + - Other mappings automatically removed (placeholders gone) +6. Save the configuration + +**Result:** Simpler certificate with only essential information. + +### Example 4: Starting Over with a New Template + +**Scenario:** You want to completely redesign your certificate with different placeholders. + +**Option A: Update** +1. Upload new template +2. Reconfigure any mappings that changed +3. Save + +**Option B: Delete and Recreate** +1. Click "Delete Custom Certificate" +2. Confirm deletion +3. Click "Upload Custom Certificate" again +4. Upload new template +5. Configure all mappings fresh +6. Save + +**When to use each:** +- **Update**: When some placeholders remain the same +- **Delete & Recreate**: When starting completely fresh + +## Tips and Best Practices + +### Before Updating + +✅ **Do:** +- Test your new template in Word/LibreOffice first +- Keep placeholder names consistent if you want mappings preserved +- Document your current mappings (take a screenshot) +- Generate a preview before saving + +❌ **Don't:** +- Change placeholder names unnecessarily (breaks mapping preservation) +- Upload templates with syntax errors +- Skip the preview step + +### Placeholder Naming Strategy + +For best mapping preservation: + +**Good Practice:** +``` +{key.name} → Always maps to participant name +{key.course_name} → Always maps to survey title +{key.date} → Always maps to completion date +{key.email} → Always maps to participant email +``` + +**Avoid:** +``` +{key.participant} → Ambiguous, might not auto-map correctly +{key.field1} → Not descriptive, hard to remember +{key.xyz} → Meaningless, requires manual mapping +``` + +### When to Delete vs Update + +**Update When:** +- Making design changes +- Adding/removing a few fields +- Fixing formatting issues +- Want to preserve existing mappings + +**Delete When:** +- Completely changing certificate structure +- Switching to default templates +- Template is corrupted beyond repair +- Want a clean slate + +## Troubleshooting + +### Issue: Mappings Not Preserved + +**Cause:** Placeholder names changed between templates + +**Solution:** +- Keep placeholder names consistent +- Or manually reconfigure changed mappings + +### Issue: Can't Delete Template + +**Error:** "No custom certificate template to delete" + +**Cause:** Survey doesn't have a custom template configured + +**Solution:** +- Verify "Custom Template" is selected +- Check if template was already deleted + +### Issue: Update Notification Not Showing + +**Cause:** Survey doesn't have existing custom certificate + +**Solution:** +- This is normal for first-time template upload +- Notification only shows when updating existing template + +## FAQ + +**Q: Will updating my template affect certificates already issued?** +A: No, previously generated certificates are not affected. Only new certificates will use the updated template. + +**Q: Can I undo a template deletion?** +A: No, deletion is permanent. You'll need to re-upload and reconfigure the template. + +**Q: Does deleting a template from one survey affect other surveys?** +A: No, each survey has its own independent template. Deleting from one survey doesn't affect others. + +**Q: What happens if I upload a template with no placeholders?** +A: The system will accept it, but you'll get a warning. The certificate will be static (same for all participants). + +**Q: Can I update just the mappings without changing the template?** +A: Yes, open the wizard and adjust mappings without uploading a new file, then save. + +**Q: How do I know which mappings were preserved?** +A: Check the wizard after parsing - preserved mappings will show your previous configuration, new ones will show automatic mapping. + +## Support + +For additional help: +- Check the main module documentation +- Review the automatic field mapping guide +- Test changes in a development environment first +- Contact your system administrator for assistance + +--- + +**Related Documentation:** +- [Automatic Field Mapping Guide](AUTOMATIC_FIELD_MAPPING.md) +- [Preview Functionality Guide](PREVIEW_FUNCTIONALITY.md) +- [Quick Start Guide](QUICK_START_AUTO_MAPPING.md) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..d49db90 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,1018 @@ +# Survey Custom Certificate Template - Troubleshooting Guide + +## Table of Contents + +1. [File Upload Issues](#file-upload-issues) +2. [Placeholder Issues](#placeholder-issues) +3. [Mapping Configuration Issues](#mapping-configuration-issues) +4. [Preview Generation Issues](#preview-generation-issues) +5. [Certificate Generation Issues](#certificate-generation-issues) +6. [PDF Conversion Issues](#pdf-conversion-issues) +7. [Formatting Issues](#formatting-issues) +8. [Performance Issues](#performance-issues) +9. [Error Messages Reference](#error-messages-reference) +10. [Diagnostic Tools](#diagnostic-tools) + +--- + +## File Upload Issues + +### Issue: "Invalid file format" Error + +**Error Message:** +``` +Invalid file format. Only DOCX files are supported. +Uploaded file: template.doc +Please upload a file with .docx extension. +``` + +**Cause:** The uploaded file is not in DOCX format. + +**Solutions:** + +1. **Convert DOC to DOCX:** + - Open the file in Microsoft Word + - Click **File** → **Save As** + - Choose **Word Document (.docx)** from the format dropdown + - Save and upload the new file + +2. **Check file extension:** + - Ensure the file ends with `.docx` (not `.doc`, `.docm`, or other formats) + - Right-click the file → Properties to verify the file type + +3. **Re-save from LibreOffice:** + - Open in LibreOffice Writer + - File → Save As → Microsoft Word 2007-365 (.docx) + +**Prevention:** +- Always create templates in Word 2007 or later +- Use "Save As" instead of "Save" when creating new templates +- Verify file extension before uploading + +--- + +### Issue: "File size exceeds maximum" Error + +**Error Message:** +``` +File size exceeds the maximum allowed limit. +Uploaded file size: 12.45 MB +Maximum allowed: 10 MB + +Please reduce the file size by: +- Compressing images in the document +- Removing unnecessary content +- Simplifying formatting +``` + +**Cause:** The template file is larger than 10 MB. + +**Solutions:** + +1. **Compress images in Word:** + ``` + - Select an image in the document + - Click Picture Format tab + - Click Compress Pictures + - Choose "Email (96 ppi)" or "Web (150 ppi)" + - Check "Apply to all pictures in this file" + - Click OK + ``` + +2. **Remove embedded objects:** + - Remove unnecessary embedded files + - Remove hidden data: File → Info → Check for Issues → Inspect Document + - Remove all items found + +3. **Simplify the template:** + - Use fewer images + - Reduce image resolution before inserting + - Remove complex graphics + - Simplify table structures + +4. **Split complex designs:** + - Use a simpler base template + - Add logos as smaller, compressed images + +**Prevention:** +- Compress images before inserting into Word +- Use web-optimized images (72-150 dpi) +- Keep templates under 5 MB for best performance + +--- + +### Issue: "The uploaded file is not a valid DOCX document" Error + +**Error Message:** +``` +The uploaded file is not a valid DOCX document. +Error: [specific error details] + +Please ensure you are uploading a valid Microsoft Word (.docx) file. +``` + +**Cause:** The file is corrupted or has an invalid DOCX structure. + +**Solutions:** + +1. **Repair the document:** + - Open in Microsoft Word + - Word may prompt to repair the file automatically + - If repaired, save as a new file and upload + +2. **Create a new template:** + - Copy content from the corrupted file + - Paste into a new blank Word document + - Save as .docx and upload + +3. **Check for corruption:** + - Try opening the file in Word + - If it doesn't open, the file is corrupted + - Restore from backup if available + +4. **Convert from another format:** + - If the file was converted from PDF or other format, recreate it in Word + +**Prevention:** +- Always save templates properly (don't force-close Word) +- Keep backup copies of templates +- Test templates by opening them before uploading + +--- + +### Issue: Upload Button Disabled or Not Responding + +**Symptoms:** +- Cannot click the upload button +- File selection dialog doesn't open +- Upload appears to do nothing + +**Solutions:** + +1. **Check browser:** + - Try a different browser (Chrome, Firefox, Edge) + - Clear browser cache and cookies + - Disable browser extensions temporarily + +2. **Check file permissions:** + - Ensure you have read access to the file + - Try copying the file to your desktop first + +3. **Check Odoo session:** + - Refresh the page + - Log out and log back in + - Check if your session has timed out + +4. **Check access rights:** + - Ensure you have Survey Manager role + - Contact your administrator if you don't have access + +**Prevention:** +- Use supported browsers (Chrome, Firefox, Edge) +- Keep browser updated +- Maintain active Odoo session + +--- + +## Placeholder Issues + +### Issue: "No placeholders found" Warning + +**Warning Message:** +``` +No placeholders found in template. Certificate will be static. +``` + +**Cause:** The template doesn't contain any text matching the `{key.xxx}` pattern. + +**Solutions:** + +1. **Check placeholder syntax:** + + **Correct format:** + ``` + {key.name} + {key.course_name} + {key.date} + ``` + + **Common mistakes:** + ``` + {{key.name}} ❌ Double braces + {name} ❌ Missing "key." + { key.name } ❌ Spaces inside + [key.name] ❌ Wrong brackets + {key.Name} ⚠️ Case matters (use lowercase) + {KEY.name} ❌ "key" must be lowercase + ``` + +2. **Verify placeholders are in the document:** + - Open the template in Word + - Use Find (Ctrl+F) to search for `{key.` + - Ensure placeholders are visible (not hidden or in headers/footers) + +3. **Check for special characters:** + - Placeholders must be plain text + - No special formatting (bold, italic is OK, but no text boxes or shapes) + - Not in text boxes or shapes (use regular text) + +4. **Re-type placeholders:** + - Sometimes copy-paste introduces invisible characters + - Delete and manually type the placeholder + +**Prevention:** +- Use the correct format from the start: `{key.field_name}` +- Test with a simple placeholder first: `{key.test}` +- Keep a reference list of your placeholders + +--- + +### Issue: Placeholders Not Recognized + +**Symptoms:** +- Some placeholders are detected, others are not +- Placeholders appear in the template but not in the mapping table + +**Solutions:** + +1. **Check each placeholder individually:** + ``` + Correct: {key.name} + Incorrect: {key.name } (space before }) + Incorrect: {key. name} (space after .) + Incorrect: {key.name-1} (hyphen not allowed) + ``` + +2. **Field name rules:** + - Only letters, numbers, and underscores allowed + - Must start with a letter + - No spaces, hyphens, or special characters + + **Valid:** + ``` + {key.name} + {key.first_name} + {key.completion_date} + {key.score_percentage} + ``` + + **Invalid:** + ``` + {key.first-name} ❌ Hyphen + {key.first name} ❌ Space + {key.1st_name} ❌ Starts with number + {key.name!} ❌ Special character + ``` + +3. **Check for hidden characters:** + - Copy the placeholder to a text editor + - Look for invisible characters + - Re-type if necessary + +4. **Verify placeholder location:** + - Placeholders in headers/footers are supported + - Placeholders in text boxes may not be detected + - Placeholders in tables are supported + +**Prevention:** +- Use only letters, numbers, and underscores in field names +- Follow naming conventions: `{key.field_name}` +- Test placeholders after adding them + +--- + +### Issue: Too Many Placeholders Detected + +**Symptoms:** +- Mapping table shows unexpected placeholders +- Placeholders you didn't intend are detected + +**Solutions:** + +1. **Check for accidental placeholders:** + - Search the template for `{key.` + - Remove any unintended text matching the pattern + +2. **Use different syntax for non-placeholder text:** + - If you need to show `{key.something}` as literal text, use: + - `{{key.something}}` (will not be detected) + - Or remove the "key." part: `{something}` + +3. **Review the template:** + - Open in Word and search for all instances of `{key.` + - Verify each one is intentional + +**Prevention:** +- Be careful when typing curly braces +- Use a consistent naming scheme for placeholders +- Document your placeholders + +--- + +## Mapping Configuration Issues + +### Issue: Cannot Save Configuration + +**Error Message:** +``` +Validation failed: +[specific validation error] + +Please correct the issues and try again. +``` + +**Common Causes and Solutions:** + +1. **Field name too long:** + ``` + Error: Value field name too long: very_long_field_name_that_exceeds_limit + Maximum length: 200 characters + ``` + **Solution:** Use shorter field names + +2. **Custom text too long:** + ``` + Error: Custom text too long for placeholder {key.description} + Maximum length: 1000 characters + Current length: 1250 characters + ``` + **Solution:** Reduce custom text length or split into multiple placeholders + +3. **Invalid characters in field name:** + ``` + Error: Invalid characters in field name: partner-name + Field names can only contain letters, numbers, underscores, and dots. + ``` + **Solution:** Use `partner_name` instead of `partner-name` + +4. **Missing required field:** + ``` + Error: Field name is required when value type is "Survey Field" + ``` + **Solution:** Enter a field name or change value type to "Custom Text" + +**Prevention:** +- Keep field names short and simple +- Use only allowed characters +- Fill in all required fields before saving + +--- + +### Issue: Automatic Mapping Incorrect + +**Symptoms:** +- System suggests wrong field for a placeholder +- Mapping doesn't match your intention + +**Solutions:** + +1. **Manually correct the mapping:** + - Click on the row in the mapping table + - Change the **Value** type if needed + - Update the **Field** name to the correct one + +2. **Use more specific placeholder names:** + - Instead of `{key.name}`, use `{key.participant_name}` or `{key.instructor_name}` + - This helps the system suggest better mappings + +3. **Check available fields:** + - Survey fields: `survey_title`, `survey_description` + - Participant fields: `partner_name`, `partner_email`, `completion_date`, `scoring_percentage`, `scoring_total` + +**Prevention:** +- Use standard placeholder names when possible +- Review automatic mappings before saving +- Generate a preview to verify mappings + +--- + +### Issue: Don't Know Which Field to Use + +**Problem:** Unsure which field name to enter for a placeholder. + +**Solution - Available Fields Reference:** + +**Survey Fields** (data about the survey itself): +``` +survey_title - The survey's title +survey_description - The survey's description +``` + +**Participant Fields** (data about the person who completed the survey): +``` +partner_name - Full name +partner_email - Email address +completion_date - Date completed (YYYY-MM-DD format) +create_date - Date started (YYYY-MM-DD format) +scoring_percentage - Score as percentage (e.g., "95.5") +scoring_total - Total points scored +``` + +**Examples:** +- For participant's name: Use `partner_name` +- For course name: Use `survey_title` +- For completion date: Use `completion_date` +- For score: Use `scoring_percentage` + +**If the field you need isn't available:** +- Use **Custom Text** value type +- Enter the static text you want to appear + +--- + +## Preview Generation Issues + +### Issue: Preview Button Disabled + +**Symptoms:** +- "Generate Preview" button is grayed out +- Cannot click the preview button + +**Solutions:** + +1. **Upload and parse template first:** + - Ensure you've uploaded a template + - Click "Parse Template" button + - Wait for placeholders to appear + +2. **Configure at least one mapping:** + - The preview requires at least one placeholder + - Ensure the mapping table is not empty + +3. **Check for errors:** + - Look for error messages in the wizard + - Correct any validation errors + +**Prevention:** +- Follow the workflow: Upload → Parse → Configure → Preview → Save + +--- + +### Issue: Preview Generation Fails + +**Error Message:** +``` +Failed to generate preview: [error details] +``` + +**Common Causes and Solutions:** + +1. **LibreOffice not available:** + ``` + Error: PDF conversion failed: LibreOffice not found + ``` + **Solution:** Contact your system administrator to install LibreOffice + +2. **Template file corrupted:** + ``` + Error: Failed to read template file + ``` + **Solution:** Re-upload the template file + +3. **Invalid mapping configuration:** + ``` + Error: Invalid field name in mapping + ``` + **Solution:** Review and correct placeholder mappings + +4. **Server timeout:** + ``` + Error: Request timeout + ``` + **Solution:** Try again, or contact administrator if problem persists + +**Prevention:** +- Ensure LibreOffice is installed (administrator task) +- Use valid, uncorrupted template files +- Keep templates reasonably sized (< 5 MB) + +--- + +### Issue: Preview Shows Placeholders Not Replaced + +**Symptoms:** +- Preview PDF still shows `{key.xxx}` text +- Some placeholders replaced, others not + +**Solutions:** + +1. **Check mapping configuration:** + - Ensure all placeholders have a value type selected + - For Survey/Participant fields, verify field name is correct + - For Custom Text, ensure text is entered + +2. **Verify field names:** + - Field names are case-sensitive + - Use exact names: `partner_name` not `Partner_Name` + +3. **Check for typos:** + - In the template: `{key.name}` not `{key.nam}` + - In the field mapping: `partner_name` not `partnername` + +4. **Re-parse template:** + - Click "Parse Template" again + - Reconfigure mappings + - Generate preview again + +**Prevention:** +- Double-check all mappings before generating preview +- Use standard field names +- Test with a simple template first + +--- + +### Issue: Preview Formatting Looks Wrong + +**Symptoms:** +- Fonts changed in preview +- Layout different from template +- Images missing or distorted + +**Solutions:** + +1. **Use standard fonts:** + - Stick to common fonts: Arial, Times New Roman, Calibri + - Avoid custom or decorative fonts + +2. **Simplify template:** + - Remove complex formatting + - Avoid nested tables + - Use simple layouts + +3. **Check images:** + - Ensure images are embedded (not linked) + - Use common formats: JPG, PNG + - Compress large images + +4. **Test in LibreOffice:** + - Open your template in LibreOffice Writer + - Check if it displays correctly there + - If not, simplify the template + +**Prevention:** +- Design templates with simplicity in mind +- Test templates in both Word and LibreOffice +- Use standard fonts and simple layouts + +--- + +## Certificate Generation Issues + +### Issue: Certificates Not Generated on Survey Completion + +**Symptoms:** +- Survey completed but no certificate created +- No certificate available for download + +**Solutions:** + +1. **Check certificate configuration:** + - Open the survey + - Verify "Custom Template" is selected + - Ensure "Has Custom Certificate" is checked + - Verify template is uploaded and configured + +2. **Check survey settings:** + - Ensure certification is enabled for the survey + - Check that the survey is published + +3. **Check logs:** + - Ask administrator to check Odoo logs + - Look for certificate generation errors + +4. **Test manually:** + - Complete a test survey + - Check if certificate is generated + - Review any error messages + +**Prevention:** +- Always test certificate generation with a test survey +- Verify configuration before going live +- Monitor logs for errors + +--- + +### Issue: Certificate Data Missing or Incorrect + +**Symptoms:** +- Certificate shows empty fields +- Wrong data appears in certificate +- Participant name is blank + +**Solutions:** + +1. **Check participant data:** + - Ensure participant has a name and email + - Verify survey response is complete + +2. **Check field mappings:** + - Review placeholder mappings + - Ensure correct fields are selected + - Verify field names are correct + +3. **Check data availability:** + - Some fields may not be available for all surveys + - Use Custom Text for fields that aren't available + +4. **Review data retrieval:** + - Ask administrator to check logs + - Look for "Failed to get [field]" warnings + +**Prevention:** +- Require participant information in survey settings +- Test with complete participant data +- Use fallback values (Custom Text) for optional fields + +--- + +## PDF Conversion Issues + +### Issue: "PDF conversion failed" Error + +**Error Message:** +``` +PDF conversion failed: LibreOffice not found or not accessible + +System administrators have been notified. +Please contact your administrator for assistance. +``` + +**Cause:** LibreOffice is not installed or not accessible on the server. + +**Solutions:** + +**For Users:** +1. Contact your system administrator +2. Provide the error message +3. Wait for administrator to install LibreOffice + +**For Administrators:** +1. Install LibreOffice: + ```bash + # Ubuntu/Debian + sudo apt-get install libreoffice + + # CentOS/RHEL + sudo yum install libreoffice + ``` + +2. Verify installation: + ```bash + which libreoffice + libreoffice --version + ``` + +3. Restart Odoo: + ```bash + sudo systemctl restart odoo + ``` + +4. Test certificate generation again + +**Prevention:** +- Ensure LibreOffice is installed before deploying the module +- Include LibreOffice in server setup documentation +- Monitor LibreOffice availability + +--- + +### Issue: PDF Conversion Timeout + +**Error Message:** +``` +PDF conversion timed out after 60 seconds +``` + +**Cause:** Template is too complex or server is overloaded. + +**Solutions:** + +1. **Simplify template:** + - Reduce file size + - Remove complex graphics + - Simplify formatting + +2. **Try again:** + - Server may have been temporarily busy + - Wait a few minutes and retry + +3. **Contact administrator:** + - May need to increase timeout settings + - May need to upgrade server resources + +**For Administrators:** +- Increase timeout in configuration +- Monitor server load +- Consider queue-based processing for high volumes + +**Prevention:** +- Keep templates simple and small +- Test during off-peak hours +- Monitor server performance + +--- + +## Formatting Issues + +### Issue: Fonts Look Different in Generated Certificate + +**Cause:** Font substitution during PDF conversion. + +**Solutions:** + +1. **Use standard fonts:** + - Arial + - Times New Roman + - Calibri + - Helvetica + - Courier New + +2. **Install fonts on server:** + - Ask administrator to install custom fonts on the server + - Fonts must be available to LibreOffice + +3. **Embed fonts in template:** + - In Word: File → Options → Save → Embed fonts in the file + - Note: This increases file size + +**Prevention:** +- Stick to standard fonts +- Test certificate generation before going live +- Verify fonts in preview + +--- + +### Issue: Images Missing or Distorted + +**Cause:** Image embedding or format issues. + +**Solutions:** + +1. **Embed images properly:** + - Copy and paste images directly into Word + - Don't link to external files + +2. **Use supported formats:** + - JPG and PNG work best + - Avoid BMP, TIFF, or other formats + +3. **Check image size:** + - Large images may cause issues + - Resize images before inserting + +4. **Compress images:** + - Select image → Picture Format → Compress Pictures + - Choose appropriate resolution + +**Prevention:** +- Use JPG or PNG images +- Embed images (don't link) +- Compress images before inserting + +--- + +### Issue: Layout Broken in Generated Certificate + +**Cause:** Complex Word features not fully supported. + +**Solutions:** + +1. **Simplify layout:** + - Use simple tables instead of complex layouts + - Avoid text boxes + - Use standard paragraph formatting + +2. **Avoid advanced features:** + - No SmartArt + - No complex shapes + - No advanced text effects + +3. **Test in LibreOffice:** + - Open template in LibreOffice Writer + - If layout breaks there, simplify the template + +4. **Use images for complex designs:** + - Create complex graphics in a design tool + - Insert as images in the template + +**Prevention:** +- Design with simplicity in mind +- Test templates in LibreOffice before uploading +- Use standard Word features only + +--- + +## Performance Issues + +### Issue: Slow Certificate Generation + +**Symptoms:** +- Certificate generation takes more than 30 seconds +- System becomes slow during generation + +**Solutions:** + +1. **Reduce template size:** + - Compress images + - Remove unnecessary content + - Simplify formatting + +2. **Generate during off-peak hours:** + - Schedule batch generation for nights/weekends + - Avoid generating many certificates simultaneously + +3. **Contact administrator:** + - May need server upgrades + - May need to optimize configuration + +**For Administrators:** +- Monitor server resources +- Consider queue-based processing +- Optimize LibreOffice settings +- Increase server resources if needed + +**Prevention:** +- Keep templates under 5 MB +- Test performance with expected load +- Plan for peak usage times + +--- + +### Issue: Server Runs Out of Memory + +**Symptoms:** +- Odoo crashes during certificate generation +- "Out of memory" errors in logs + +**Solutions:** + +**For Users:** +1. Reduce template size +2. Generate fewer certificates at once +3. Contact administrator + +**For Administrators:** +1. Increase server RAM +2. Limit concurrent certificate generations +3. Implement queue-based processing +4. Monitor memory usage: + ```bash + free -h + watch -n 1 free -h + ``` + +**Prevention:** +- Adequate server resources +- Monitor memory usage +- Implement resource limits + +--- + +## Error Messages Reference + +### User-Facing Errors + +| Error Message | Cause | Solution | +|---------------|-------|----------| +| "Invalid file format" | Wrong file type | Upload .docx file | +| "File size exceeds maximum" | File too large | Compress images, reduce size | +| "No placeholders found" | Wrong syntax | Use `{key.field_name}` format | +| "PDF conversion failed" | LibreOffice issue | Contact administrator | +| "Validation failed" | Invalid configuration | Review and correct mappings | +| "Template parsing failed" | Corrupted file | Re-save and re-upload template | + +### Administrator Errors + +| Error Message | Cause | Solution | +|---------------|-------|----------| +| "LibreOffice not found" | Not installed | Install LibreOffice | +| "Permission denied" | File permissions | Fix permissions on /tmp | +| "Database error" | DB issue | Check database logs | +| "Timeout" | Process too slow | Increase timeout, optimize | + +--- + +## Diagnostic Tools + +### For Users + +**Check Configuration:** +1. Open survey +2. Go to Options tab +3. Verify: + - Certification Template = "Custom Template" + - Has Custom Certificate = checked + - Template filename shown + +**Test with Simple Template:** +1. Create minimal template: + ``` + Certificate for {key.name} + ``` +2. Upload and configure +3. Generate preview +4. If this works, issue is with complex template + +**Check Browser Console:** +1. Press F12 in browser +2. Go to Console tab +3. Look for JavaScript errors +4. Report errors to administrator + +### For Administrators + +**Check LibreOffice:** +```bash +# Verify installation +which libreoffice +libreoffice --version + +# Test conversion manually +libreoffice --headless --convert-to pdf test.docx +``` + +**Check Logs:** +```bash +# View recent certificate logs +tail -f /var/log/odoo/odoo-server.log | grep certificate + +# Count errors +grep "certificate.*error" /var/log/odoo/odoo-server.log | wc -l + +# Find specific error +grep "PDF conversion failed" /var/log/odoo/odoo-server.log +``` + +**Check System Resources:** +```bash +# Memory +free -h + +# Disk space +df -h + +# CPU usage +top + +# LibreOffice processes +ps aux | grep soffice +``` + +**Check Permissions:** +```bash +# Temp directory +ls -la /tmp + +# Odoo user +ps aux | grep odoo + +# Test write access +sudo -u odoo touch /tmp/test_file +``` + +**Generate Diagnostic Report:** +```bash +#!/bin/bash +echo "=== Certificate Module Diagnostics ===" +echo "Date: $(date)" +echo "" +echo "LibreOffice: $(which libreoffice)" +libreoffice --version +echo "" +echo "Python packages:" +pip list | grep python-docx +echo "" +echo "Disk space:" +df -h | grep -E "Filesystem|/tmp" +echo "" +echo "Memory:" +free -h +echo "" +echo "Recent errors:" +grep "certificate.*error" /var/log/odoo/odoo-server.log | tail -10 +``` + +--- + +## Getting Additional Help + +If your issue is not covered in this guide: + +1. **Check the logs**: Detailed error information is in the Odoo logs +2. **Review documentation**: See USER_GUIDE.md and ADMIN_GUIDE.md +3. **Test with simple template**: Isolate the issue +4. **Contact administrator**: For server-related issues +5. **Community forums**: Search for similar issues +6. **Bug report**: If you've found a bug, report it with: + - Odoo version + - Module version + - Steps to reproduce + - Error messages + - Log excerpts + +--- + +**Version**: 1.0 +**Last Updated**: 2024 +**Module**: survey_custom_certificate_template +**Odoo Version**: 19.0 diff --git a/docs/UI_UX_IMPROVEMENTS.md b/docs/UI_UX_IMPROVEMENTS.md new file mode 100644 index 0000000..8a36953 --- /dev/null +++ b/docs/UI_UX_IMPROVEMENTS.md @@ -0,0 +1,422 @@ +# UI/UX Improvements Documentation + +## Overview + +This document describes the user interface and user experience improvements implemented in the Survey Custom Certificate Template module to enhance usability and provide better feedback to users. + +## Implemented Improvements + +### 1. Progress Indicators + +#### Visual Progress Bar +**Location**: Wizard header (form view) + +**Features**: +- Three-stage progress indicator showing: + 1. ✓ Template Uploaded + 2. ✓ Placeholders Detected + 3. ✓ Preview Generated +- Color-coded badges: + - Green (✓): Completed steps + - Gray (○): Pending steps +- Always visible once template is uploaded +- Provides clear visual feedback on workflow progress + +**Benefits**: +- Users know exactly where they are in the configuration process +- Reduces confusion about next steps +- Provides sense of accomplishment as steps complete + +### 2. Enhanced Error Messages + +#### Clear, Actionable Error Messages +All error messages follow a consistent pattern: + +**Structure**: +``` +[What went wrong] + +[Why it happened] + +[What to do next] +``` + +**Examples**: + +1. **File Upload Errors**: + ``` + The uploaded file is not a valid DOCX file or is corrupted. + + Please ensure you are uploading a Microsoft Word (.docx) file. + You can create DOCX files using Microsoft Word or LibreOffice Writer. + ``` + +2. **LibreOffice Errors**: + ``` + PDF conversion failed: LibreOffice is not installed. + + LibreOffice is required to convert certificates to PDF format. + System administrators have been notified. + + Please contact your system administrator to install LibreOffice. + ``` + +3. **Validation Errors**: + ``` + Template file exceeds the maximum allowed limit of 10MB. + + Large files can cause performance issues and slow down certificate generation. + + Please reduce the file size by: + • Compressing embedded images + • Removing unnecessary formatting + • Simplifying the template design + ``` + +#### Error Message Categories + +| Category | Color | Icon | Example | +|----------|-------|------|---------| +| Validation Error | Red | ⚠️ | Invalid file format | +| System Error | Orange | 🔧 | LibreOffice unavailable | +| User Error | Yellow | ℹ️ | Missing required field | +| Success | Green | ✓ | Template saved successfully | + +### 3. Loading Indicators + +#### Button Confirmation Dialogs +**Implementation**: `confirm` attribute on action buttons + +**Features**: +- Confirmation dialog before long-running operations +- Clear description of what will happen +- Prevents accidental clicks +- Sets user expectations for wait time + +**Examples**: +```xml +