survey_custom_certificate_template/docs/ADMIN_GUIDE.md

Survey Custom Certificate Template - Administrator Guide

Table of Contents

1. Installation
2. System Requirements
3. Configuration
4. Security
5. Monitoring
6. Troubleshooting
7. 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

# 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

sudo apt-get update
sudo apt-get install libreoffice

CentOS/RHEL

sudo yum install libreoffice

macOS

brew install --cask libreoffice

Verify Installation

libreoffice --version

You should see output like: LibreOffice 7.x.x.x

Installing the Module

1. Copy the module to your Odoo addons directory:

   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):

http {
    client_max_body_size 10M;
}

Odoo Configuration (odoo.conf):

[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:

# 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

which libreoffice
libreoffice --version

Monitor Certificate Generation

# 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

# 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:

# 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:

   sudo systemctl restart odoo
   

---

Issue: PDF Conversion Timeout

Symptoms:

• Error: "PDF conversion timed out"
• Long processing times
• Certificates not generated

Diagnosis:

# 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:

   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:

# 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:

   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:

# 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:

   sudo chmod 1777 /tmp
   

2. Ensure Odoo user can execute LibreOffice:

   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:

# 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:

   SELECT * FROM pg_locks WHERE NOT granted;
   

4. Restart database if necessary

---

Diagnostic Commands

Generate Diagnostic Report

#!/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:

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:

# 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

# 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

# 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

# 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:

-- 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

-- Vacuum and analyze certificate-related tables
VACUUM ANALYZE survey_survey;
VACUUM ANALYZE survey_user_input;
VACUUM ANALYZE ir_attachment;

Index Optimization

-- 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:

# 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

# 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