Panduan Lengkap Membuat Custom Module Report dengan QWeb di Odoo 18

ERP Odoo adalah sistem ERP (Enterprise Resource Planning) terkemuka yang digunakan oleh berbagai perusahaan di seluruh dunia untuk mengelola berbagai aspek bisnis secara terintegrasi, mulai dari penjualan, pembelian, inventori, produksi, hingga akuntansi dan pelaporan. Dengan arsitektur modular yang fleksibel dan antarmuka yang user-friendly, Odoo memungkinkan perusahaan untuk menyesuaikan sistem sesuai kebutuhan bisnisnya.

Report (Laporan) adalah bagian penting dari sistem ERP  Odoo. Salah satu cara paling fleksibel untuk membuat laporan PDF adalah dengan menggunakan QWeb, sebuah templating engine berbasis XML yang powerful. Artikel ini membahas langkah-langkah membuat Custom Module Report menggunakan QWeb di ERP Odoo versi 18 dengan studi kasus: invoice untuk bisnis dimsum.

1. Dasar-Dasar QWeb Reporting Engine

QWeb adalah engine template utama di ERP Odoo untuk menghasilkan laporan HTML dan PDF. Berikut beberapa poin penting:

  • Berbasis XML: QWeb menggunakan XML sebagai struktur dokumen yang memudahkan integrasi dengan sistem Odoo.

  • Data dari Python: Data diteruskan dari backend Python (via report action) ke template QWeb.

  • Direktif Template: Menggunakan direktif seperti t-esc, t-foreach, dan t-if untuk memanipulasi data.

  • ​Pemicu Laporan: Digunakan bersama report.report_action untuk menghasilkan laporan PDF/HTML.

2. Struktur File untuk Custom Report 

Struktur direktori modul custom yang direkomendasikan:

        dimsum/
├── __init__.py 			# File inisialisasi root modul
├── __manifest__.py		# Manifest/deskripsi modul
├── reports/
│   ├── __init__.py		# Inisialisasi submodule reports
│   ├── invoice_report.py	# Logic Python untuk report
│   └── invoice_template.xml	# Template QWeb

3. Isi dari Manifest

    {
    'name': 'Invoice Report Dimsum',
   'version': '1.0',
   'summary': 'Custom Invoice Report for Minji Dimxum using QWeb',
   'description': 'Modul untuk membuat laporan invoice PDF khusus dengan QWeb untuk bisnis Minji Dimxum.',
   'category': 'Accounting',
   'author': 'Naufal Nabila',
   'website': 'https://minji-dimxum.odoo.com/',
   'depends': ['account'], 			# Dependency pada modul account
   'data': [
       'reports/invoice_template.xml', 	# File template yang akan diload
   ],
   'installable': True,
   'application': False,
   'auto_install': False,
   'license': 'LGPL-3',
}

4. File Inisialisasi

Root__init__.py/:

from . import invoice_report

reports.__init__.py/:

from . import invoice_report

5. Mendesain Template Report dengan QWeb

Template QWeb memiliki struktur dasar yang perlu diikuti agar berfungsi dengan baik di Odoo:

File reports/invoice_template.xml

    
    <odoo>
  <!-- Definisi Template QWeb -->
  <template id="report_invoice_dimsum">
    <t t-call="web.html_container">
      <t t-foreach="docs" t-as="doc">
        <t t-call="web.external_layout">
          <div class="page">
            <!-- CSS Styling -->
            <style>
              .page h2 {
                color: #B22222;
                text-transform: uppercase;
                font-weight: bold;
              }
              .table-sm td {
                font-size: 12px;
              }
              footer {
                text-align: center;
                margin-top: 50px;
                font-style: italic;
                font-size: 11px;
              }
            </style>
            
            <!-- Header Invoice -->
            <h2>Invoice Dimsum</h2>
            <p>Nomor: <t t-esc="doc.name" /></p>
            <p>Tanggal: <t t-esc="doc.invoice_date" /></p>
            
            <!-- Tabel Item Invoice -->
            <table class="table table-sm">
              <thead>
                <tr>
                  <th>Produk</th>
                  <th>Jumlah</th>
                  <th>Harga</th>
                </tr>
              </thead>
              <tbody>
                <tr t-foreach="doc.invoice_line_ids" t-as="line">
                  <td>
                    <t t-esc="line.product_id.name" />
                </td>
                <td>
                    <t t-esc="line.quantity" />
                </td>
                <td>
                    <t t-esc="line.price_unit" />
                </td>
                </tr>
              </tbody>
            </table>
            
            <!-- Total -->
            <h4>Total: <t t-esc="doc.amount_total" /></h4>
          </div>
          </t>
          </t>
          </t>
      </template>
  
  <!-- Definisi Report Action -->
  <record id="action_report_invoice_dimsum" model="ir.actions.report">
    <field name="name">Invoice Dimsum</field>
    <field name="model">account.move</field>
    <field name="report_type">qweb-pdf</field>  <!-- Ubah ke qweb-pdf untuk PDF -->
    <field name="report_name">dimsum.report_invoice_dimsum</field>
    <field name="report_file">dimsum.report_invoice_dimsum</field>
    <field name="print_report_name">'Invoice - %s' % (object.name)</field>
    <field name="binding_model_id" ref="account.model_account_move" />
    <field name="binding_type">report</field>
  </record>
</odoo>

Penjelasan Komponen Utama Template:

Berikut adalah penjelasan komponen utama template dengan tambahan poin tentang ERP Odoo konsep desain :

  • t-call="web.html_container": Container utama untuk semua laporan HTML/PDF, memastikan struktur dokumen sesuai dengan standar Odoo.

  • t-foreach="docs" t-as="doc": Loop untuk setiap dokumen (invoice) yang dipilih, memungkinkan laporan menangani beberapa dokumen sekaligus.

  • t-call="web.external_layout": Memanggil layout standar Odoo (header, footer, logo perusahaan, dll.) yang dikonfigurasi di pengaturan perusahaan.

  • t-esc: Menampilkan nilai variabel atau ekspresi secara aman (escaped) untuk mencegah masalah keamanan seperti injeksi HTML.

  • CSS Styling: Mengatur tampilan laporan dengan gaya khusus, seperti warna teks, ukuran font, atau margin.

  • Konsep Desain (Header dan Table Detail Invoice):
    Desain laporan harus jelas, terstruktur, dan profesional.

    • Header: Berisi informasi utama seperti judul ("Invoice Dimsum"), nomor invoice, tanggal, dan informasi perusahaan/pelanggan. Header biasanya diletakkan di bagian atas dengan gaya menonjol (misalnya, warna merah dan teks tebal seperti di contoh CSS). Contoh: <h2>Invoice Dimsum</h2> diikuti oleh nomor dan tanggal invoice.

Table Detail Invoice: Menampilkan daftar item (produk, jumlah, harga) dalam format tabel untuk memudahkan pembacaan. Tabel menggunakan direktif t-foreach untuk mengulang setiap baris (invoice_line_ids) dan t-esc untuk menampilkan data seperti nama produk dan harga. Contoh: 

    
<table class="table table-sm">
  <thead>
    <tr>
      <th>Produk</th>
      <th>Jumlah</th>
      <th>Harga</th>
    </tr>
  </thead>
  <tbody>
    <tr t-foreach="doc.invoice_line_ids" t-as="line">
      <td><t t-esc="line.product_id.name" /></td>
      <td><t t-esc="line.quantity" /></td>
      <td><t t-esc="line.price_unit" /></td>
    </tr>
  </tbody>
</table>

Desain ini memastikan laporan mudah dibaca, dengan header memberikan konteks dan tabel memberikan rincian transaksi secara terorganisir.

Fungsi ir.actions.report dan Kaitannya dengan Report

Fungsi ir.actions.report:

ir.actions.report adalah definisi aksi laporan di ERP Odoo yang menghubungkan model data (misalnya, account.move) dengan template QWeb dan menentukan bagaimana laporan dihasilkan (misalnya, sebagai PDF atau HTML). Ini adalah komponen kunci yang memberi tahu Odoo kapan dan bagaimana menampilkan laporan di antarmuka pengguna.

Isi dan Penjelasan Field dalam ir.actions.report:

    
<record id="action_report_invoice_dimsum" model="ir.actions.report">
  <field name="name">Invoice Dimsum</field> <!-- Nama laporan yang muncul di UI -->
  <field name="model">account.move</field> <!-- Model data yang terkait -->
  <field name="report_type">qweb-pdf</field> <!-- Jenis laporan (PDF/HTML) -->
  <field name="report_name">dimsum.report_invoice_dimsum</field> <!-- Nama unik laporan, sesuai dengan AbstractModel -->
  <field name="report_file">dimsum.report_invoice_dimsum</field> <!-- Nama file output -->
  <field name="print_report_name">'Invoice - %s' % (object.name)</field> <!-- Nama file saat diunduh -->
  <field name="binding_model_id" ref="account.model_account_move" /> <!-- Model untuk tombol print -->
  <field name="binding_type">report</field> <!-- Tipe binding (report/action) -->
</record>

Kaitan dengan Report:

  1. Menghubungkan ke Template dan Python: Field report_name (dimsum.report_invoice_dimsum) merujuk ke nama laporan yang didefinisikan di file Python (report.dimsum.report_invoice_dimsum) dan template QWeb (report_invoice_dimsum). Ini memastikan ERP Odoo tahu template mana yang digunakan dan bagaimana data disediakan.

  2. Menentukan Konteks Penggunaan: Field model dan binding_model_id memastikan laporan tersedia untuk model account.move (invoice) dan muncul di menu "Print" atau "Download" di form invoice.

  3. Mengatur Output: Field report_type (qweb-pdf) menentukan bahwa laporan akan dihasilkan sebagai PDF, dan print_report_name menentukan nama file output (misalnya, "Invoice - INV/2025/0001").

  4. Integrasi ke UI: Field binding_type dan binding_model_id memungkinkan laporan muncul sebagai opsi di tombol "Download" atau "Print" pada form invoice, seperti dijelaskan pada langkah penggunaan.

Mengapa Penting dalam ERP Odoo?

Tanpa ir.actions.report, ERP Odoo tidak akan tahu bagaimana menghubungkan template QWeb dengan model data atau menampilkan laporan di antarmuka. Ini adalah "pintu masuk" yang mengintegrasikan laporan ke dalam sistem ERP Odoo, memastikan laporan dapat diakses oleh pengguna dengan cara yang intuitif.

Kesimpulan

Penambahan file Python pada laporan QWeb di ERP Odoo versi 18 sangat penting untuk menyediakan data dan menerapkan logika bisnis yang tidak dapat ditangani oleh template XML saja. Contoh seperti menghitung total diskon atau memformat tanggal menunjukkan bagaimana file Python memperkaya laporan. Selain itu, desain template yang terstruktur (header dan tabel) serta definisi ir.actions.report memastikan laporan terlihat profesional dan terintegrasi dengan baik ke dalam sistem ERP Odoo. Dengan pendekatan ini, Anda dapat membuat laporan yang fleksibel dan sesuai kebutuhan bisnis.

6. Manipulasi Data untuk Report di ERP Odoo Versi 18

Mengapa Perlu Custom File Python?

File Python (invoice_report.py) diperlukan untuk mengatur data yang akan dikirim ke template QWeb dan menerapkan logika bisnis tambahan yang tidak dapat ditangani langsung oleh template XML. QWeb hanya bertanggung jawab untuk rendering data, bukan untuk memproses atau memanipulasi data secara kompleks. File Python berfungsi sebagai jembatan antara model ERP Odoo (misalnya, account.move) dan template QWeb, memastikan data disiapkan dengan benar sebelum ditampilkan.

Apakah Report Bisa Berjalan Tanpa File Python Ini?

Tidak, report tidak dapat berjalan tanpa file Python jika Anda membuat custom report dengan QWeb di Odoo. ERP Odoo memerlukan kelas AbstractModel dengan metode _get_report_values untuk menyediakan data ke template. Tanpa file ini, Odoo tidak tahu bagaimana cara mengambil data dari model (misalnya, account.move) dan meneruskannya ke template QWeb. File Python ini wajib untuk mendefinisikan report handler yang terhubung dengan report_name di ir.actions.report.

Contoh Custom Logika di File Python

File Python memungkinkan kita menambahkan logika bisnis, seperti menghitung diskon, memformat data, atau menambahkan informasi tambahan yang tidak langsung tersedia di model. Berikut adalah contoh konkret:

File: reports/invoice_report.py 

    
from odoo import api, models
class InvoiceReport(models.AbstractModel):
    _name = 'report.dimsum.report_invoice_dimsum'
    _description = 'Custom Invoice Report for Dimsum'
   @api.model
    def _get_report_values(self, docids, data=None):
        """
        Menyediakan data untuk template QWeb
       Args:
            docids: ID dokumen yang dipilih
            data: Data tambahan (opsional)
       Returns:
            dict: Data untuk template
        """
        docs = self.env['account.move'].browse(docids)
       # Contoh custom logika:
        # 1. Menghitung total diskon dari semua baris invoice
        total_discount = sum(line.quantity * line.price_unit * (line.discount / 100)
                             for doc in docs for line in doc.invoice_line_ids)
       # 2. Menambahkan informasi tambahan, misalnya nama sales person
        sales_person = docs.mapped('user_id.name') or ['Tidak ada sales person']
       # 3. Memformat ulang tanggal untuk keperluan tampilan
        formatted_dates = [doc.invoice_date.strftime('%d %B %Y') for doc in docs]
       return {
            'doc_ids': docids,
            'doc_model': 'account.move',
            'docs': docs,
            'total_discount': total_discount,  # Data tambahan untuk template
            'sales_person': sales_person[0],   # Mengambil sales person pertama
            'formatted_dates': formatted_dates, # Tanggal yang sudah diformat
        }

Penjelasan Contoh Logika:

  • Total Diskon: Menghitung total diskon dari semua baris invoice untuk ditampilkan di laporan, yang tidak tersedia langsung di model account.move.

  • Sales Person: Mengambil nama sales person dari field user_id untuk ditampilkan di header laporan.

  • Format Tanggal: Memformat tanggal invoice agar lebih mudah dibaca (misalnya, "13 Mei 2025" alih-alih format default).

Manfaat Custom Logika

Dengan file Python, kita bisa:

  • Menghitung nilai baru (seperti diskon atau pajak tambahan).

  • Mengambil data dari model lain (misalnya, informasi pelanggan atau cabang).

  • Memformat data agar sesuai dengan kebutuhan tampilan.

  • Menambahkan logika kondisional (misalnya, menampilkan pesan khusus jika invoice overdue).

Tanpa file Python, kita hanya bisa menampilkan data mentah dari model, yang sering kali tidak cukup untuk laporan yang kompleks atau memiliki kebutuhan bisnis spesifik.

7. Instalasi dan Penggunaan

Setelah modul dibuat, ikuti langkah-langkah berikut untuk menginstal dan menggunakannya:

  1. Letakkan Modul: Tempatkan folder modul dimsum di direktori addons Odoo.

  2. Update Daftar Aplikasi: Pergi ke Apps > Update Apps List (dalam mode developer).


  3. Instal Modul: Cari dan instal modul "Invoice Report Dimsum"


  4. Gunakan Laporan:

      • Pergi ke menu Accounting > Customers > Invoices

      • Pilih invoice yang ingin dicetak, jika belum ada bisa klik New


      • Pastikan sudah terisi fieldsnya


      • Klik tombol Setting di samping tulisan Draft Invoice -> Download -> Invoice Dimsum


      • Cek hasilnya



    8. Tips dan Troubleshooting

    Masalah Umum dan Solusinya:

    1. Report Tidak Muncul di Menu Print:

    • Periksa binding_model_id dan binding_type di definisi report

    • Pastikan modul sudah diupdate setelah perubahan XML

    2. Error "KeyError: 'doc'":

    • Periksa struktur template, pastikan variabel docs tersedia

    • Pastikan loop t-foreach berada di tempat yang tepat

    3. Perubahan Tidak Terlihat:

    • Update modul setelah modifikasi (Technical > Modules > Update module)

    • Bersihkan cache browser dan server Odoo

    4. Field Tidak Ditemukan:

    • Sesuaikan nama field dengan versi Odoo yang digunakan

    • di Odoo 18, date_invoice sudah menjadi invoice_date 

    9. Pengembangan Lanjutan

    Untuk pengembangan lebih lanjut, Anda dapat:

    1. Menambahkan Barcode/QR Code: Gunakan t-att-data-barcode-value untuk menghasilkan barcode.

    2. Custom Paper Size: Sesuaikan ukuran kertas dengan menambahkan css margin dan sizing.

    3. Multi-Language Support: Gunakan t-lang untuk laporan multi-bahasa.

    4. Conditional Styling: Gunakan t-if untuk menerapkan gaya berbeda berdasarkan kondisi data. 

    10. Kesimpulan

    Dengan mengikuti panduan ini, Anda dapat membuat custom report profesional untuk bisnis menggunakan QWeb di ERP Odoo versi 18. Teknik ini dapat digunakan untuk membuat berbagai jenis laporan seperti invoice, kwitansi, surat jalan, laporan analitik, dan dokumen bisnis lainnya.

    Laporan QWeb memberikan fleksibilitas tinggi dan memungkinkan penyesuaian mendalam sesuai kebutuhan bisnis Anda, sambil tetap terintegrasi dengan baik ke dalam ekosistem ERP Odoo.

    ​Ingin pahami Odoo lebih dalam atau butuh bantuan teknis? Arkana siap membantu!

    Odoo Training

    Support Odoo​​​​

      Writer

    Naufal Nabila
    Software Engineer



    Share this post
    Tags
    Development ERP Odoo 18
    Our blogs
    Mengenal Modul Inventory ERP Odoo untuk Kebutuhan Bisnis