admin.suherdy/survey_custom_certificate_template

Fork 0

admin.suherdy 39ab27c7b7 first commit

2025-11-29 08:46:04 +07:00

24 KiB

Raw Blame History

Survey Custom Certificate Template - Troubleshooting Guide

File Upload Issues
Placeholder Issues
Mapping Configuration Issues
Preview Generation Issues
Certificate Generation Issues
PDF Conversion Issues
Formatting Issues
Performance Issues
Error Messages Reference
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:

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

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

Remove embedded objects:
- Remove unnecessary embedded files
- Remove hidden data: File → Info → Check for Issues → Inspect Document
- Remove all items found
Simplify the template:
- Use fewer images
- Reduce image resolution before inserting
- Remove complex graphics
- Simplify table structures
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:

Repair the document:
- Open in Microsoft Word
- Word may prompt to repair the file automatically
- If repaired, save as a new file and upload
Create a new template:
- Copy content from the corrupted file
- Paste into a new blank Word document
- Save as .docx and upload
Check for corruption:
- Try opening the file in Word
- If it doesn't open, the file is corrupted
- Restore from backup if available
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:

Check browser:
- Try a different browser (Chrome, Firefox, Edge)
- Clear browser cache and cookies
- Disable browser extensions temporarily
Check file permissions:
- Ensure you have read access to the file
- Try copying the file to your desktop first
Check Odoo session:
- Refresh the page
- Log out and log back in
- Check if your session has timed out
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:

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

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

Check each placeholder individually:

Correct:   {key.name}
Incorrect: {key.name }  (space before })
Incorrect: {key. name}  (space after .)
Incorrect: {key.name-1} (hyphen not allowed)

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

Check for hidden characters:
- Copy the placeholder to a text editor
- Look for invisible characters
- Re-type if necessary
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:

Check for accidental placeholders:
- Search the template for {key.
- Remove any unintended text matching the pattern
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}
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:

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

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

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

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:

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
Use more specific placeholder names:
- Instead of {key.name}, use {key.participant_name} or {key.instructor_name}
- This helps the system suggest better mappings
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:

Upload and parse template first:
- Ensure you've uploaded a template
- Click "Parse Template" button
- Wait for placeholders to appear
Configure at least one mapping:
- The preview requires at least one placeholder
- Ensure the mapping table is not empty
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:

LibreOffice not available:
```
Error: PDF conversion failed: LibreOffice not found
```
Solution: Contact your system administrator to install LibreOffice
Template file corrupted:
```
Error: Failed to read template file
```
Solution: Re-upload the template file
Invalid mapping configuration:
```
Error: Invalid field name in mapping
```
Solution: Review and correct placeholder mappings
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:

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
Verify field names:
- Field names are case-sensitive
- Use exact names: partner_name not Partner_Name
Check for typos:
- In the template: {key.name} not {key.nam}
- In the field mapping: partner_name not partnername
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:

Use standard fonts:
- Stick to common fonts: Arial, Times New Roman, Calibri
- Avoid custom or decorative fonts
Simplify template:
- Remove complex formatting
- Avoid nested tables
- Use simple layouts
Check images:
- Ensure images are embedded (not linked)
- Use common formats: JPG, PNG
- Compress large images
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:

Check certificate configuration:
- Open the survey
- Verify "Custom Template" is selected
- Ensure "Has Custom Certificate" is checked
- Verify template is uploaded and configured
Check survey settings:
- Ensure certification is enabled for the survey
- Check that the survey is published
Check logs:
- Ask administrator to check Odoo logs
- Look for certificate generation errors
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:

Check participant data:
- Ensure participant has a name and email
- Verify survey response is complete
Check field mappings:
- Review placeholder mappings
- Ensure correct fields are selected
- Verify field names are correct
Check data availability:
- Some fields may not be available for all surveys
- Use Custom Text for fields that aren't available
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:

Contact your system administrator
Provide the error message
Wait for administrator to install LibreOffice

For Administrators:

Install LibreOffice:

# Ubuntu/Debian
sudo apt-get install libreoffice

# CentOS/RHEL
sudo yum install libreoffice

Verify installation:

which libreoffice
libreoffice --version

Restart Odoo:
```
sudo systemctl restart odoo
```
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:

Simplify template:
- Reduce file size
- Remove complex graphics
- Simplify formatting
Try again:
- Server may have been temporarily busy
- Wait a few minutes and retry
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:

Use standard fonts:
- Arial
- Times New Roman
- Calibri
- Helvetica
- Courier New
Install fonts on server:
- Ask administrator to install custom fonts on the server
- Fonts must be available to LibreOffice
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:

Embed images properly:
- Copy and paste images directly into Word
- Don't link to external files
Use supported formats:
- JPG and PNG work best
- Avoid BMP, TIFF, or other formats
Check image size:
- Large images may cause issues
- Resize images before inserting
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:

Simplify layout:
- Use simple tables instead of complex layouts
- Avoid text boxes
- Use standard paragraph formatting
Avoid advanced features:
- No SmartArt
- No complex shapes
- No advanced text effects
Test in LibreOffice:
- Open template in LibreOffice Writer
- If layout breaks there, simplify the template
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:

Reduce template size:
- Compress images
- Remove unnecessary content
- Simplify formatting
Generate during off-peak hours:
- Schedule batch generation for nights/weekends
- Avoid generating many certificates simultaneously
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:

Reduce template size
Generate fewer certificates at once
Contact administrator

For Administrators:

Increase server RAM
Limit concurrent certificate generations
Implement queue-based processing
Monitor memory usage:
```
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:

Open survey
Go to Options tab
Verify:
- Certification Template = "Custom Template"
- Has Custom Certificate = checked
- Template filename shown

Test with Simple Template:

Create minimal template:
```
Certificate for {key.name}
```
Upload and configure
Generate preview
If this works, issue is with complex template

Check Browser Console:

Press F12 in browser
Go to Console tab
Look for JavaScript errors
Report errors to administrator

For Administrators

Check LibreOffice:

# Verify installation
which libreoffice
libreoffice --version

# Test conversion manually
libreoffice --headless --convert-to pdf test.docx

Check Logs:

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

# Memory
free -h

# Disk space
df -h

# CPU usage
top

# LibreOffice processes
ps aux | grep soffice

Check Permissions:

# Temp directory
ls -la /tmp

# Odoo user
ps aux | grep odoo

# Test write access
sudo -u odoo touch /tmp/test_file

Generate Diagnostic Report:

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

Check the logs: Detailed error information is in the Odoo logs
Review documentation: See USER_GUIDE.md and ADMIN_GUIDE.md
Test with simple template: Isolate the issue
Contact administrator: For server-related issues
Community forums: Search for similar issues
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

24 KiB Raw Blame History

Survey Custom Certificate Template - Troubleshooting Guide

Table of Contents

File Upload Issues

Issue: "Invalid file format" Error

Issue: "File size exceeds maximum" Error

Issue: "The uploaded file is not a valid DOCX document" Error

Issue: Upload Button Disabled or Not Responding

Placeholder Issues

Issue: "No placeholders found" Warning

Issue: Placeholders Not Recognized

Issue: Too Many Placeholders Detected

Mapping Configuration Issues

Issue: Cannot Save Configuration

Issue: Automatic Mapping Incorrect

Issue: Don't Know Which Field to Use

Preview Generation Issues

Issue: Preview Button Disabled

Issue: Preview Generation Fails

Issue: Preview Shows Placeholders Not Replaced

Issue: Preview Formatting Looks Wrong

Certificate Generation Issues

Issue: Certificates Not Generated on Survey Completion

Issue: Certificate Data Missing or Incorrect

PDF Conversion Issues

Issue: "PDF conversion failed" Error

Issue: PDF Conversion Timeout

Formatting Issues

Issue: Fonts Look Different in Generated Certificate

Issue: Images Missing or Distorted

Issue: Layout Broken in Generated Certificate

Performance Issues

Issue: Slow Certificate Generation

Issue: Server Runs Out of Memory

Error Messages Reference

User-Facing Errors

Administrator Errors

Diagnostic Tools

For Users

For Administrators

Getting Additional Help

24 KiB

Raw Blame History