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: Complete guide for creating and configuring certificate templates
• Administrator Guide: Installation, configuration, and troubleshooting for system administrators
• Troubleshooting Guide: 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

sudo apt-get update
sudo apt-get install libreoffice

CentOS/RHEL

sudo yum install libreoffice

2. Install Python Dependencies

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

# 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 and Admin Guide
2. Issues: Review the Troubleshooting Guide
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.