admin.suherdy/survey_custom_certificate_template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a1bf69ab6e
survey_custom_certificate_t.../docs/USER_GUIDE.md
admin.suherdy 39ab27c7b7 first commit
2025-11-29 08:46:04 +07:00

19 KiB
Raw Blame History

Survey Custom Certificate Template - User Guide

Table of Contents

  1. Introduction
  2. Getting Started
  3. Creating Your Certificate Template
  4. Uploading and Configuring Templates
  5. Placeholder Syntax
  6. Mapping Configuration
  7. Previewing Certificates
  8. Managing Templates
  9. Troubleshooting
  10. 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