Standard Operating Procedure: Odoo Invoice Template Customization

Standard Operating Procedure: Odoo Invoice Template Customization & Deployment

1. Executive Summary & Purpose

This document mandates the standardized procedure for designing, configuring, and deploying custom QWeb invoice templates within the Odoo ERP environment. The objective is to ensure brand consistency, financial compliance, and technical stability across all automated invoicing workflows.

2. Scope & Prerequisites

• Scope: Applies to all Odoo instances (On-Premise and Odoo.sh) managing customer invoicing.
• Software Requirements: Odoo Studio (optional) or QWeb XML editor; Python 3.x; Odoo 15.0+; access to base_report_layout.
• Access Requirements: Administrator/Technical settings access to the Odoo backend.
• PPE: N/A (Digital-only environment).

3. Roles & Responsibilities (RACI Matrix)

4. Step-by-Step Procedure

Phase 1: Environment Preparation

• Establish a staging instance or sandbox environment to mirror production.
• Enable 'Developer Mode' (Debug Mode) via Settings.
• Create a backup of the current account.report_invoice_document view.

Phase 2: Template Customization

• Navigate to Settings > Technical > User Interface > Views.
• Search for account.report_invoice_document (or the specific inherited view).
• Create an "Inherited View" to prevent overwriting core Odoo files (best practice for update stability).
• Inject custom CSS/Bootstrap classes into the <xpath> elements for styling.
• Utilize QWeb logic (<t t-if>, <t t-foreach>) to handle dynamic data injection (e.g., custom tax fields or banking details).

Phase 3: Validation & Testing

• Generate a test invoice in the staging environment.
• Execute Print > Invoice and verify pixel-perfect rendering in PDF output.
• Validate legal mandatory fields: Tax ID (TIN), Registered Address, Invoice Sequence Number, and Payment Terms.

Phase 4: Production Deployment

• Commit XML changes to the production repository (if using Odoo.sh).
• Run Update Apps List and perform a module upgrade to push changes.
• Verify template against production-live invoice data.

5. Quality Assurance & Pro-Tips

• Pro-Tip (Avoid Hardcoding): Never hardcode bank details or company info directly into XML. Use the res.company record dynamic variables so the template remains functional if business details change.
• Performance Metric: Rendering time for PDF generation must remain under 1.5 seconds. If rendering exceeds 3s, remove bloated image assets (e.g., logos > 500KB).
• Common Pitfall: Forgetting to define the paperformat record. If margins are clipped, you must define a custom report.paperformat record linked to your specific invoice report.

6. Frequently Asked Questions

Q: My images are not appearing in the rendered PDF. Why? A: This is usually a cross-origin permission error or a missing absolute path in the src attribute. Use t-att-src="'data:image/png;base64,' + company.logo.decode('utf-8')" to ensure proper encoding.

Q: How do I revert to the default template if my custom version breaks? A: If you used the "Inherited View" method, simply deactivate the view record in Technical > User Interface > Views. If you overwrote core code, restore your backup from Phase 1.

Q: Is it possible to use different templates for different customers? A: Yes, implement an if/else condition in the QWeb template based on o.partner_id.property_payment_term_id or a custom boolean field on the customer record.

Signed, Julian Vance Chief Architect, Template Registry