Report Designer

Kapan Dipakai

• Saat laporan baru perlu dibuat dari data aplikasi, misalnya laporan penjualan, stok, piutang, jurnal, atau laporan custom.
• Saat filter laporan perlu ditambah, dikunci berdasarkan role, dibuat wajib, atau diubah jenis inputnya.
• Saat hasil laporan salah karena query SQL, placeholder filter, atau struktur child query perlu diperbaiki.
• Saat tampilan laporan perlu dirapikan: judul, tabel, subtotal, grand total, chart, teks, atau layout cetak.
• Saat report perlu diuji dengan preview sebelum dipakai user, lalu disimpan ke server, diekspor JSON, diimpor, diduplikasi, atau dihapus.

Konsep Dasar

• Report File adalah file laporan yang dipilih dari server. Setelah file dipilih, halaman memuat nama laporan, deskripsi, report path, filter, SQL, template, dan pengaturan cetaknya.
• Report Path adalah kode laporan. Kode ini dipakai oleh menu, preview, dan proses pembukaan laporan. Jangan mengganti Report Path pada laporan yang sudah dipakai menu tanpa mengecek menu terkait.
• SQL Code adalah sumber data laporan. Isinya berupa JSON yang berisi mainsql dan bisa memiliki childrensql. Hasil SQL inilah yang nanti menjadi variabel data di template HTML/EJS.
• Filter Definition menentukan input yang dilihat user sebelum menjalankan laporan, seperti tanggal, divisi, customer, produk, text search, angka, toggle, select, dan autocomplete.
• HTML/EJS menentukan tampilan laporan. HTML membuat struktur tampilan, sedangkan EJS mengambil data, mengulang baris, menghitung subtotal, menyusun grand total, atau menampilkan bagian tertentu berdasarkan kondisi.
• Preview menjalankan laporan yang sedang diedit. Dari sini implementor bisa melihat filter, hasil render, dan sample data yang dikembalikan SQL.
• Allow Print dan Allow Export menentukan apakah user boleh mencetak atau mengekspor laporan dari layar report.
• Default Page Setup mengatur ukuran kertas, orientasi, dan margin yang dipakai saat laporan dicetak.

Alur Penggunaan

1. Buka menu Umum / Report Designer. Sistem mengambil daftar report file dari server.
2. Pilih report yang akan diedit. Halaman akan memuat Name, Description, Report Path, Report Type, SQL Code, Filter Definition, HTML/EJS, dan Default Page Setup.
3. Sebelum mengubah laporan penting, klik Duplicate atau Save as JSON. Dengan begitu versi lama masih bisa dikembalikan bila query atau template rusak.
4. Periksa identitas laporan. Name adalah nama yang dilihat user, Description muncul sebagai keterangan, Report Path adalah kode teknis yang dipakai menu dan route.
5. Susun Filter Definition. Pastikan fieldname filter sama dengan placeholder yang dipakai di SQL Code.
6. Edit SQL Code. Gunakan placeholder filter agar query mengikuti input user, bukan angka atau tanggal yang ditulis permanen.
7. Edit HTML/EJS. Pakai variabel data untuk hasil query, filter atau filterdata untuk informasi filter, dan company untuk identitas perusahaan.
8. Buka tab Preview, isi filter, lalu jalankan laporan. Periksa apakah data keluar, filter bekerja, tampilan rapi, dan sample data sesuai dengan struktur yang diharapkan template.
9. Klik Save untuk menyimpan laporan ke server. Gunakan Export JSON bila perlu backup atau migrasi ke server lain.

Filter Definition

• Field Name adalah nama filter teknis. Nama ini dipakai pada placeholder SQL seperti <--salesdate-->, <--customerid.value-->, atau <--customerid.operand-->.
• Label adalah teks yang dilihat user pada layar filter. Label bisa memakai key bahasa, misalnya customer, division, atau salesdate.
• Filter Type menentukan bentuk input: text, select, autocomplete, toggle, date, time, datetime, decimal, atau integer.
• Default Value mengisi nilai awal filter. Nilai ini bisa membantu user agar tidak selalu mengisi filter yang sama.
• Operands menentukan operator yang boleh dipilih user, misalnya =, like, atau between. Untuk date dan angka, between akan menampilkan nilai dari dan sampai.
• Options JSON dipakai oleh select, autocomplete, decimal, dan integer. Untuk select biasanya berisi daftar pilihan. Untuk decimal/integer berisi batas digit, min, dan max.
• Sub Query dipakai bila filter membutuhkan SQL tambahan. Hasil subquery bisa dipakai untuk mengganti placeholder filter tertentu di SQL utama.
• Required membuat filter wajib diisi sebelum laporan dijalankan.
• Lock Filter membuat filter readonly berdasarkan ekspresi tertentu, misalnya role user yang mengunci divisi atau customer.
• Filter Having berarti filter ditempatkan ke bagian HAVING, bukan WHERE. Ini dipakai untuk kondisi pada hasil agregasi, seperti total, saldo, atau jumlah yang dihitung dari GROUP BY.
• Urutan filter bisa diubah dengan tombol naik/turun. Urutan ini memengaruhi kenyamanan user saat mengisi filter laporan.

SQL Code

• SQL Code ditulis sebagai JSON, bukan hanya satu teks SQL biasa. Bentuk umum berisi mainsql dan bisa memiliki childrensql untuk detail bertingkat.
• mainsql adalah query utama. Contoh sederhana: mengambil daftar invoice, daftar produk, atau saldo akun.
• childrensql dipakai bila laporan punya detail di bawah data utama, misalnya divisi berisi invoice, lalu invoice berisi produk.
• Placeholder <-customfilter-> akan diganti dengan gabungan filter WHERE dari input user.
• Placeholder <--namafilter--> akan diganti dengan SQL filter untuk field tersebut. Contoh: <--salesdate--> mengikuti tanggal yang user isi.
• Placeholder <--namafilter.value-->, <--namafilter.value1-->, dan <--namafilter.value2--> mengambil nilai filter langsung. Ini berguna untuk query yang butuh nilai filter secara eksplisit.
• Placeholder <---fieldname---> mengambil nilai dari baris parent SQL. Ini dipakai pada child query, misalnya detail invoice memakai salesid dari query header.
• Placeholder <-customhaving-> dan format <----namafilter----> dipakai untuk filter HAVING.
• Saat laporan dijalankan, sistem mengganti placeholder menjadi SQL final sesuai filter yang diisi user, lalu mengambil data laporan.

HTML/EJS dan Preview

• Template HTML/EJS menerima data dari proses laporan. Variabel yang umum dipakai adalah data, form, company, users, filter, filterdata, langs, functions, langId, server, dan userroles.
• data adalah hasil SQL. Kalau SQL memiliki child query, struktur data juga bertingkat dan harus dibaca sesuai nama child-nya.
• filter berisi daftar filter yang ditampilkan user. filterdata berisi nilai filter yang dipilih user saat laporan dijalankan.
• langs dipakai agar label di laporan mengikuti bahasa aktif. Untuk angka dan tanggal, template bisa memakai helper yang sudah disediakan aplikasi.
• Report Type HTML digunakan untuk laporan visual dengan tabel, teks, dan chart. Report Type TEXT digunakan untuk output teks yang lebih sederhana.
• Tab WYSIWYG membantu merapikan tampilan, tetapi laporan yang banyak loop, subtotal, atau kondisi lebih aman diedit dari tab Code.
• Tab Preview menjalankan laporan yang sedang dipilih dengan exact-filename. Setelah data dimuat, bagian Sample Data menampilkan JSON hasil query untuk membantu mencocokkan field dengan template.

Hal yang Perlu Diperhatikan

• Report Designer sebaiknya dipakai oleh implementor atau admin yang memahami data, karena salah query dapat membuat laporan kosong, lambat, atau menampilkan angka keliru.
• Sebelum mengubah laporan aktif, duplicate atau export JSON dulu. Ini penting karena satu report path bisa dipakai oleh menu yang dilihat banyak user.
• Jika preview kosong, cek berurutan: filter wajib, placeholder SQL, nama field, child query, lalu HTML/EJS.
• Jika filter tidak bekerja, pastikan Field Name di Filter Definition sama dengan placeholder yang ditulis di SQL Code.
• Jika hasil print/export berbeda dari preview, cek Allow Print, Allow Export, Report Type, Export Filename, dan Default Page Setup.
• Export Filename dapat memakai placeholder seperti {{datetime}}, {{report.xxx}}, {{company.xxx}}, {{username}}, {{filter.xxx}}, dan {{filterdata.xxx}}.
• Gunakan Save untuk menyimpan ke server, Export JSON untuk backup, Import untuk memindahkan laporan dari file lain, dan Delete hanya untuk laporan yang sudah tidak dipakai.

Lokasi Menu

• Umum / Report Designer
  /reportdesigner