# Survey Custom Certificate Template - User Guide

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Creating Your Certificate Template](#creating-your-certificate-template)
4. [Uploading and Configuring Templates](#uploading-and-configuring-templates)
5. [Placeholder Syntax](#placeholder-syntax)
6. [Mapping Configuration](#mapping-configuration)
7. [Previewing Certificates](#previewing-certificates)
8. [Managing Templates](#managing-templates)
9. [Troubleshooting](#troubleshooting)
10. [Best Practices](#best-practices)

---

## Introduction

The Survey Custom Certificate Template module allows you to create personalized certificates for survey participants using your own Microsoft Word (.docx) templates. Instead of being limited to Odoo's default certificate layouts, you can design certificates that match your organization's branding and include dynamic data that's automatically filled in for each participant.

### Key Features

- **Custom Design**: Use your own DOCX templates with full control over layout, fonts, colors, and branding
- **Dynamic Placeholders**: Insert placeholders that are automatically replaced with participant and survey data
- **Automatic Mapping**: The system intelligently suggests data mappings for common placeholder names
- **Live Preview**: Generate preview certificates with sample data before going live
- **Multi-Survey Support**: Each survey can have its own unique certificate template
- **Easy Updates**: Update templates while preserving existing placeholder mappings

---

## Getting Started

### Prerequisites

- Odoo 19 with the Survey module installed
- Survey Manager access rights
- Microsoft Word, LibreOffice, or compatible word processor for creating templates
- LibreOffice installed on the server (for PDF conversion)

### Quick Start

1. Navigate to **Surveys** in Odoo
2. Open or create a survey
3. Go to the **Options** tab
4. In the **Certification** section, select **Custom Template** from the dropdown
5. Click **Upload Custom Certificate** button
6. Upload your DOCX template
7. Configure placeholder mappings
8. Generate a preview to verify
9. Click **Save**

---

## Creating Your Certificate Template

### Template Design Guidelines

Your certificate template should be created in Microsoft Word (.docx format) and can include:

- **Text**: Any static text, headings, or descriptions
- **Images**: Your organization's logo, borders, decorative elements
- **Formatting**: Fonts, colors, text alignment, spacing
- **Tables**: For structured layouts
- **Shapes and Graphics**: Borders, backgrounds, watermarks

### File Requirements

- **Format**: Microsoft Word (.docx) only
- **Maximum Size**: 10 MB
- **Compatibility**: Created in Microsoft Word 2007 or later, or LibreOffice Writer

### Adding Placeholders

Placeholders are special text patterns that get replaced with actual data when certificates are generated. They must follow this exact format:

```
{key.field_name}
```

**Important Rules:**
- Must start with `{key.`
- Must end with `}`
- Field name can only contain letters, numbers, and underscores
- No spaces allowed inside the placeholder
- Case-sensitive

### Example Template

Here's a simple certificate template example:

```
═══════════════════════════════════════════════════
              CERTIFICATE OF COMPLETION
═══════════════════════════════════════════════════

This is to certify that

{key.name}

has successfully completed the course

{key.course_name}

on {key.date} with a score of {key.score}%

═══════════════════════════════════════════════════
```

---

## Uploading and Configuring Templates

### Step-by-Step Upload Process

#### Step 1: Access the Configuration Wizard

1. Open your survey in Odoo
2. Navigate to the **Options** tab
3. In the **Certification** section, select **Custom Template** from the **Certification Template** dropdown
4. Click the **Upload Custom Certificate** button

#### Step 2: Upload Your Template

1. In the wizard dialog, click **Choose File** under "Upload Certificate Template"
2. Select your .docx file from your computer
3. Click **Parse Template** button

The system will:
- Validate that the file is a valid DOCX document
- Check the file size (must be under 10 MB)
- Extract all placeholders from the template
- Automatically suggest mappings for recognized placeholder names

#### Step 3: Review Detected Placeholders

After parsing, you'll see a table showing all placeholders found in your template:

| Source | Value | Field | Text |
|--------|-------|-------|------|
| {key.name} | Participant Field | partner_name | |
| {key.course_name} | Survey Field | survey_title | |
| {key.date} | Participant Field | completion_date | |

The **Source** column shows the placeholder text from your template (read-only).

---

## Placeholder Syntax

### Standard Placeholder Format

All placeholders must follow this pattern:
```
{key.field_name}
```

### Recognized Placeholder Names

The system automatically recognizes and maps these common placeholder names:

#### Survey Data Placeholders

| Placeholder | Maps To | Description |
|-------------|---------|-------------|
| `{key.title}` | survey_title | Survey title |
| `{key.survey_title}` | survey_title | Survey title |
| `{key.course_name}` | survey_title | Survey title (alias) |
| `{key.course}` | survey_title | Survey title (alias) |
| `{key.description}` | survey_description | Survey description |
| `{key.survey_description}` | survey_description | Survey description |

#### Participant Data Placeholders

| Placeholder | Maps To | Description |
|-------------|---------|-------------|
| `{key.name}` | partner_name | Participant's full name |
| `{key.participant_name}` | partner_name | Participant's full name |
| `{key.partner_name}` | partner_name | Participant's full name |
| `{key.student_name}` | partner_name | Participant's full name (alias) |
| `{key.email}` | partner_email | Participant's email address |
| `{key.participant_email}` | partner_email | Participant's email address |
| `{key.date}` | completion_date | Survey completion date |
| `{key.completion_date}` | completion_date | Survey completion date |
| `{key.finish_date}` | completion_date | Survey completion date (alias) |
| `{key.score}` | scoring_percentage | Participant's score percentage |
| `{key.percentage}` | scoring_percentage | Participant's score percentage |
| `{key.grade}` | scoring_percentage | Participant's score percentage (alias) |
| `{key.total_score}` | scoring_total | Total points scored |
| `{key.points}` | scoring_total | Total points scored (alias) |

### Custom Placeholder Names

You can use any placeholder name you want. If the system doesn't recognize it, you'll need to manually configure the mapping.

Examples of custom placeholders:
- `{key.instructor_name}`
- `{key.certificate_number}`
- `{key.expiry_date}`
- `{key.organization_name}`

---

## Mapping Configuration

### Understanding Value Types

For each placeholder, you must choose how it should be filled:

#### 1. Survey Field
Use data from the survey itself.

**Available Fields:**
- `survey_title` - The title of the survey
- `survey_description` - The survey's description

**When to use:** For information about the course/survey itself that's the same for all participants.

**Example:** `{key.course_name}` → Survey Field → `survey_title`

#### 2. Participant Field
Use data from the participant who completed the survey.

**Available Fields:**
- `partner_name` - Participant's full name
- `partner_email` - Participant's email address
- `completion_date` - Date the survey was completed
- `create_date` - Date the survey was started
- `scoring_percentage` - Score as a percentage (e.g., "95.5")
- `scoring_total` - Total points scored

**When to use:** For personalized information that's different for each participant.

**Example:** `{key.name}` → Participant Field → `partner_name`

#### 3. Custom Text
Use static text that's the same for all certificates.

**When to use:** For fixed information like:
- Organization name
- Certificate numbers
- Instructor names
- Fixed dates
- Standard disclaimers

**Example:** `{key.organization}` → Custom Text → "Acme Training Institute"

### Configuring Mappings

#### Automatic Mappings

When you upload a template, the system automatically suggests mappings for recognized placeholder names. Review these suggestions and adjust if needed.

#### Manual Configuration

To manually configure a placeholder:

1. Click on the row in the placeholder table
2. In the **Value** column, select the appropriate type:
   - Survey Field
   - Participant Field
   - Custom Text
3. If you selected Survey Field or Participant Field:
   - Enter the field name in the **Field** column
   - Use one of the available field names listed above
4. If you selected Custom Text:
   - Enter your text in the **Text** column
   - Maximum 1000 characters

#### Example Configuration

**Scenario:** You want to add a fixed instructor name to all certificates.

1. In your template, add: `{key.instructor}`
2. After parsing, find this placeholder in the table
3. Set **Value** to "Custom Text"
4. Set **Text** to "Dr. Jane Smith"
5. Save the configuration

Now all certificates will show "Dr. Jane Smith" where `{key.instructor}` appears.

---

## Previewing Certificates

### Generating a Preview

Before saving your configuration, it's highly recommended to generate a preview:

1. After configuring all placeholder mappings, click **Generate Preview**
2. Wait a few seconds for the preview to generate
3. The preview PDF will appear at the bottom of the wizard

### What to Check in the Preview

✓ **All placeholders replaced**: No `{key.xxx}` text should remain  
✓ **Formatting preserved**: Fonts, colors, and layout should match your template  
✓ **Data makes sense**: Sample data should be appropriate for each field  
✓ **No overlapping text**: Text should fit within designated areas  
✓ **Images intact**: Logos and graphics should display correctly  

### Preview Sample Data

The preview uses these sample values:

- **Name**: John Doe
- **Email**: john.doe@example.com
- **Course**: Your actual survey title
- **Date**: Current date
- **Score**: 95.5%
- **Total Score**: 100

### Troubleshooting Preview Issues

**Problem:** Preview button is disabled  
**Solution:** Ensure you have uploaded a template and configured at least one placeholder mapping.

**Problem:** Preview generation fails with "LibreOffice error"  
**Solution:** Contact your system administrator. LibreOffice must be installed on the server for PDF conversion.

**Problem:** Placeholders not replaced in preview  
**Solution:** Check that your placeholder syntax is correct (`{key.field_name}`) and that you've configured mappings for all placeholders.

---

## Managing Templates

### Updating an Existing Template

To update a template while preserving existing mappings:

1. Open the survey with the custom certificate
2. Click **Upload Custom Certificate** button
3. Upload the new template file
4. Click **Parse Template**

**What happens:**
- The system detects this is an update
- Placeholders that exist in both old and new templates keep their mappings
- New placeholders are added with automatic mapping suggestions
- Removed placeholders are deleted from the configuration

**Best Practice:** Try to keep placeholder names consistent between template versions to preserve mappings.

### Deleting a Template

To remove a custom certificate template:

1. Open the survey
2. In the **Options** tab, find the **Certification** section
3. Click **Delete Custom Certificate** button
4. Confirm the deletion

**Warning:** This action cannot be undone. The template file and all placeholder mappings will be permanently deleted.

After deletion:
- The survey reverts to default certificate options
- Previously generated certificates are not affected
- You can upload a new template at any time

### Switching Between Surveys

Each survey has its own independent certificate template:

- Templates are stored per survey
- Changing one survey's template doesn't affect others
- You can reuse the same DOCX file for multiple surveys
- Each survey needs its own mapping configuration

---

## Troubleshooting

### Common Issues and Solutions

#### Issue: "Invalid file format" error

**Cause:** The uploaded file is not a valid DOCX document.

**Solutions:**
1. Ensure the file has a `.docx` extension
2. Open the file in Microsoft Word or LibreOffice
3. Save it as a new DOCX file (File → Save As → Word Document .docx)
4. Try uploading the newly saved file

**Note:** DOC (older Word format) is not supported. Convert to DOCX first.

---

#### Issue: "File size exceeds maximum" error

**Cause:** The template file is larger than 10 MB.

**Solutions:**
1. Compress images in the document:
   - In Word: Select image → Picture Format → Compress Pictures
   - Choose "Email (96 ppi)" or "Web (150 ppi)"
2. Remove unnecessary embedded objects
3. Simplify complex graphics
4. Remove hidden data: File → Info → Check for Issues → Inspect Document

---

#### Issue: "No placeholders found" warning

**Cause:** The template doesn't contain any text matching the `{key.xxx}` pattern.

**Solutions:**
1. Check your placeholder syntax - must be exactly `{key.field_name}`
2. Common mistakes:
   - Using `{{key.name}}` (double braces) ❌
   - Using `{name}` (missing "key.") ❌
   - Using `{ key.name }` (spaces inside) ❌
   - Using `[key.name]` (wrong brackets) ❌
3. Correct format: `{key.name}` ✓

---

#### Issue: Placeholders not replaced in generated certificates

**Cause:** Mapping configuration is incomplete or incorrect.

**Solutions:**
1. Open the certificate configuration wizard
2. Verify all placeholders have a Value type selected
3. For Survey Field and Participant Field types, ensure the Field name is correct
4. Generate a preview to test
5. Check the field names match exactly (case-sensitive):
   - Correct: `partner_name` ✓
   - Incorrect: `Partner_Name` ❌
   - Incorrect: `partnername` ❌

---

#### Issue: "PDF conversion failed" error

**Cause:** LibreOffice is not installed or not accessible on the server.

**Solutions:**
1. Contact your system administrator
2. Administrator needs to install LibreOffice:
   - Ubuntu/Debian: `sudo apt-get install libreoffice`
   - CentOS/RHEL: `sudo yum install libreoffice`
   - macOS: `brew install --cask libreoffice`
3. After installation, restart the Odoo service

---

#### Issue: Certificate formatting looks different from template

**Cause:** Complex formatting may not be fully preserved during PDF conversion.

**Solutions:**
1. Simplify the template design
2. Avoid advanced Word features:
   - Complex text boxes
   - Nested tables
   - Advanced text effects
   - Custom fonts (use standard fonts)
3. Test with a preview before going live
4. Use images for complex graphics instead of Word shapes

---

#### Issue: Special characters appear incorrectly

**Cause:** Encoding issues with non-ASCII characters.

**Solutions:**
1. Ensure your template is saved with UTF-8 encoding
2. In Word: File → Options → Advanced → Web Options → Encoding → UTF-8
3. Test with a preview to verify special characters display correctly
4. Supported: é, ñ, ü, 中文, العربية, etc.

---

#### Issue: "Validation failed" error when saving

**Cause:** Invalid data in placeholder mappings.

**Solutions:**
1. Check for:
   - Field names longer than 200 characters
   - Custom text longer than 1000 characters
   - Special characters in field names (only letters, numbers, underscores, and dots allowed)
2. Review the error message for specific details
3. Correct the invalid data and try saving again

---

### Getting Help

If you encounter issues not covered in this guide:

1. **Check the Odoo logs**: Your administrator can review server logs for detailed error messages
2. **Contact your administrator**: For server-related issues (LibreOffice, file permissions, etc.)
3. **Review requirements**: Ensure all prerequisites are met
4. **Test with a simple template**: Create a minimal template with one placeholder to isolate the issue

---

## Best Practices

### Template Design

✓ **Keep it simple**: Simpler templates are more reliable and easier to maintain  
✓ **Use standard fonts**: Arial, Times New Roman, Calibri work best  
✓ **Test early**: Generate previews frequently during configuration  
✓ **Use consistent naming**: Keep placeholder names consistent across template versions  
✓ **Document your placeholders**: Keep a list of what each placeholder represents  

### Placeholder Naming

✓ **Be descriptive**: Use clear names like `{key.participant_name}` not `{key.pn}`  
✓ **Use underscores**: Separate words with underscores: `{key.completion_date}`  
✓ **Follow conventions**: Use the standard placeholder names when possible  
✓ **Avoid special characters**: Stick to letters, numbers, and underscores  

### Configuration

✓ **Review automatic mappings**: The system's suggestions are usually correct, but always verify  
✓ **Generate previews**: Always preview before saving  
✓ **Test with real data**: After saving, complete a test survey to verify certificates generate correctly  
✓ **Keep backups**: Save copies of your template files outside of Odoo  

### Maintenance

✓ **Version your templates**: Keep track of template versions (e.g., Certificate_v1.docx, Certificate_v2.docx)  
✓ **Document changes**: Note what changed between template versions  
✓ **Test updates**: When updating a template, generate a preview to ensure mappings still work  
✓ **Communicate changes**: Inform users when certificate designs change  

### Security

✓ **Limit access**: Only Survey Managers should configure certificate templates  
✓ **Validate data**: The system automatically sanitizes data to prevent security issues  
✓ **Review custom text**: Ensure custom text doesn't contain sensitive information  
✓ **Monitor generation**: Check logs periodically for generation errors  

---

## Appendix: Quick Reference

### Placeholder Syntax Cheat Sheet

```
Correct Format:
{key.field_name}

Examples:
{key.name}
{key.course_name}
{key.completion_date}
{key.score}

Common Mistakes:
{{key.name}}        ❌ Double braces
{name}              ❌ Missing "key."
{ key.name }        ❌ Spaces inside
[key.name]          ❌ Wrong brackets
{key.Name}          ❌ Inconsistent casing
```

### Available Field Names

**Survey Fields:**
- `survey_title`
- `survey_description`

**Participant Fields:**
- `partner_name`
- `partner_email`
- `completion_date`
- `create_date`
- `scoring_percentage`
- `scoring_total`

### File Requirements

- **Format**: .docx only
- **Max Size**: 10 MB
- **Encoding**: UTF-8
- **Compatibility**: Word 2007+ or LibreOffice

### Workflow Summary

1. Create template in Word with placeholders
2. Upload template in Odoo
3. Parse template to extract placeholders
4. Configure placeholder mappings
5. Generate preview
6. Save configuration
7. Test with real survey completion

---

## Support

For technical support or questions about this module:

- **Documentation**: Refer to this user guide
- **System Administrator**: Contact for server-related issues
- **Odoo Community**: Search for similar issues in community forums
- **Module Developer**: Contact for bug reports or feature requests

---

**Version**: 1.0  
**Last Updated**: 2024  
**Module**: survey_custom_certificate_template  
**Odoo Version**: 19.0