survey_custom_certificate_template/docs/TROUBLESHOOTING.md

# 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