survey_custom_certificate_template/README.md

# 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.**