Odoo Report

Odoo Email Templates & QWeb Reports Skill (v2.1)

A skill for creating, managing, debugging, and migrating Odoo email templates and QWeb reports across versions 14-19.

Workflows

This skill handles all template and report workflows via natural language:

| What you want | What to say | |---------------|-------------| | Create email template | "Create an email template for sale.order quotation" | | Create QWeb PDF report | "Create a QWeb PDF report for purchase.order" | | Migrate templates | "Migrate this template from Odoo 14 to 17" | | Analyze template | "Analyze this template for issues" | | Debug rendering | "Debug why my email shows plain text" | | Fix template | "Fix the broken QWeb expressions" | | Validate before deploy | "Validate this template before deployment" | | List templates | "List all templates for sale.order" | | Preview output | "Preview this email template" |

Configuration

• Supported Versions: Odoo 14, 15, 16, 17, 18, 19
• Core Model: mail.template
• Rendering Engines: inlinetemplate (Jinja2-like) for headers, QWeb for bodyhtml

User overrides: Check for odoo-report.local.md in the project .claude/ directory. If found, use its YAML frontmatter settings (defaultversion, author, defaultlayout) as defaults.

---

Template Architecture

mail.template
├── Inherits: mail.render.mixin (rendering engine)
├── Inherits: template.reset.mixin (reset - Odoo 16+)
│
├── Header Fields (inline_template engine):
│   subject, email_from, email_to, email_cc, reply_to, partner_to
│
├── Content Fields (QWeb engine):
│   body_html
│
├── Attachment Fields:
│   attachment_ids (static)
│   report_template (Odoo 14-16) / report_template_ids (Odoo 17+)
│   report_name (dynamic filename)
│
└── Configuration:
    email_layout_xmlid, auto_delete, mail_server_id,
    use_default_to, scheduled_date, template_category (16+)

Rendering Flow

mail.template.send_mail_batch(res_ids)
  ├─► _generate_template(res_ids, render_fields)
  │     ├─► _classify_per_lang()
  │     ├─► _render_field() per field (inline_template or qweb)
  │     ├─► _generate_template_recipients()
  │     ├─► _generate_template_attachments() (static + PDF report)
  │     └─► Return rendered values dict
  ├─► Create mail.mail records
  ├─► Apply email_layout_xmlid (if set)
  └─► Send via mail_server_id or default

---

Two Rendering Engines

1. Inline Template (Jinja2-like)

Used for: subject, emailfrom, emailto, emailcc, replyto, partnerto, lang, scheduleddate

{{ object.name }}
{{ object.partner_id.name }}
{{ (object.user_id.email_formatted or user.email_formatted) }}
{{ object.state == 'draft' and 'Quotation' or 'Order' }}
{{ ctx.get('proforma') and 'Proforma' or '' }}

2. QWeb Engine

Used for: body_html

Draft
Sent
Confirmed

    

View

---

Version Decision Matrix

| Feature | 14 | 15 | 16 | 17 | 18 | 19 | |---------|:--:|:--:|:--:|:--:|:--:|:--:| | Output tag | t-esc | t-out | t-out | t-out | t-out | t-out | | report_template (M2O) | Y | Y | Y | - | - | - | | report_template_ids (M2M) | - | - | - | Y | Y | Y | | template_category | - | - | Y | Y | Y | Y | | Company branding colors | - | - | - | - | - | Y | | format_datetime() | - | Y | Y | Y | Y | Y | | is_html_empty() | - | - | Y | Y | Y | Y |

Version Detection Priority

1. User-specified --version flag
2. Directory path (odoo14, odoo17, etc.)
3. __manifest__.py version string (e.g., '17.0.1.0.0')
4. Ask user if ambiguous

---

Email Layout Templates

| Layout | Width | Use Case | |--------|-------|----------| | mail.mail_notification_layout | 900px | Full notifications with header/footer | | mail.mail_notification_light | 590px | Simple notifications | | mail.mail_notification_layout_with_responsible_signature | 900px | Uses record's user_id signature (16+) |

---

Best Practices

1. Always Use Fallbacks

2. Use Format Helpers

3. Use Layouts for Consistency

mail.mail_notification_layout

4. Handle Empty HTML (16+)

5. Version-Appropriate Output

6. Report Attachment by Version

7. Email Tables for Compatibility

    Content

8. Safe Dynamic Filenames

{{ (object.name or 'Document').replace('/', '-') }}

---

wkhtmltopdf (Required for PDF Reports)

Installation

# Windows
winget install wkhtmltopdf.wkhtmltox

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# macOS
brew install wkhtmltopdf

Odoo Configuration (MANDATORY)

[options]
bin_path = C:\Program Files\wkhtmltopdf\bin   # Windows
# bin_path = /usr/local/bin                    # Linux

Key Limitation: OFFLINE Mode

wkhtmltopdf runs WITHOUT network access:

• Google Fonts CDN will NOT load
• External images will NOT render
• Use web.external_layout for fonts
• Use system fonts: 'DejaVu Sans', 'Arial', sans-serif

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | Unable to find Wkhtmltopdf | binpath not configured | Add binpath to odoo.conf | | PDF generation timeout | External resources requested | Remove CDN URLs | | Blank PDF generated | CSS/SCSS errors | Validate SCSS syntax | | Exit with code 1 | HTML syntax error | Validate QWeb XML |

---

Arabic/RTL Support

MANDATORY Template Wrapper for Non-Latin Text

Without web.html_container, Arabic text displays as Ùاتورة (UTF-8 bytes read as Latin-1).

Bilingual Labels

    Date | التاريخ

RTL Alignment

    يرجى إرسال حوالاتكم على الحساب المذكور أعلاه

---

Report SCSS Styling

Asset Bundle

'assets': {
    'web.report_assets_common': [
        'module/static/src/scss/report_styles.scss',
    ],
},

Google Fonts Pitfall

// BROKEN - Semicolons in URL break SCSS parsing
@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&display=swap');

// FIXED - Use weight range syntax
@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300..700&display=swap');

// BEST - Don't use Google Fonts (wkhtmltopdf is offline!)

Recommended Font Stack

$report-font-family: 'DejaVu Sans', 'Arial', 'Helvetica', sans-serif;

---

Paper Format Configuration

    Custom A4
    A4
    Portrait
    20
    20
    15
    15
    
    90

Link to report: ``

| Format | Dimensions | Use Case | |--------|------------|----------| | A4 | 210 x 297 mm | Standard international | | Letter | 216 x 279 mm | US standard | | Legal | 216 x 356 mm | Legal documents | | Landscape | Any + Landscape | Wide tables, charts |

---

Debug Workflow

When diagnosing report or template issues, follow this order:

1. Infrastructure: wkhtmltopdf installed? bin_path in odoo.conf? Server restarted?
2. Template structure: web.htmlcontainer → web.externallayout → div.page?
3. Report action: reportname matches template id? bindingmodel_id correct?
4. Shell test: env.ref('module.report_action')._render_qweb_pdf([record_id])
5. Browser cache: Clear cache (Ctrl+Shift+R)

---

Reference Files

When working on specific tasks, read these files from the plugin directory for deeper context:

For template creation

• Pattern selection by purpose/model: memories/template_patterns.md
• Starter email XML: templates/email/basic_notification.xml, templates/email/document_email.xml
• Starter report XML: templates/qweb/basic_report.xml, templates/qweb/table_report.xml
• Field definitions: data/template_fields.json
• Context variables by version: data/context_variables.json
• Layout options: data/layouts.json

For version decisions

• Version routing rules and migration paths: memories/version_routing.md
• Version detection logic and feature map: helpers/version_helper.md

For validation

• Pre-flight validation checklist: validators/template_validator.md

For QWeb quality

• Safety, performance, email/report guidelines: memories/qweb_best_practices.md

For module-specific templates

• Known Odoo template IDs by module: data/module_templates.md

---

Migration Reference

Automatic Transformations

| From → To | Transformation | |-----------|---------------| | 14 → 15+ | t-esc → t-out, t-raw → t-out | | 14-16 → 17+ | report_template → report_template_ids with eval="[(4, ref(...))]" | | Any → 16+ | Add template_category field | | Any → 19 | Add company branding: company.email_secondary_color, company.email_primary_color |

Migration Workflow

1. Detect source version (syntax heuristics or directory name)
2. Create backup: {file}.bak
3. Apply transformations in order
4. Validate migrated XML
5. Show diff summary

For full migration matrix and rules, read memories/version_routing.md.

---

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | AttributeError: 'NoneType' has no attribute 'name' | Null field access | Use object.field.name or '' | | QWebException: t-esc is deprecated | Old syntax in 15+ | Replace t-esc with t-out | | KeyError: 'format_amount' | Missing context helper | Ensure mail.render.mixin inherited | | ValidationError: Invalid XML | Malformed QWeb | Check tag closure | | Arabic text as Ùاتورة | Missing web.htmlcontainer | Add UTF-8 wrapper | | Blank PDF | wkhtmltopdf not found or CSS error | Check binpath, validate SCSS |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahmed-lakosha
• Source: ahmed-lakosha/odoo-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.