Câu hỏi thường gặp — Custom Variables

Sử dụng chung

Custom Variables khác gì Environment Variables?

Tiêu chí	Custom Variables	Environment Variables
Quản lý	Qua giao diện, lưu database	File .env trên server
Kiểu giá trị	Aggregation (count, sum, avg...)	String tĩnh
Giá trị	Tính toán động từ dữ liệu	Cố định cho đến khi restart
Sử dụng	Variable picker trong UI, workflow	Cấu hình hệ thống (DB, port...)
Phân quyền	Qua ACL	Quyền truy cập file server

Có thể dùng biến trong biểu thức filter không?

Gián tiếp — có. Filter của biến aggregation hỗ trợ tham chiếu đến biến hệ thống ($currentUser, $date...) và các biến khác. Plugin sẽ resolve các biến trong filter trước khi thực thi query.

Tuy nhiên, trên giao diện filter UI thông thường (không phải trong cấu hình biến), Custom Variables xuất hiện trong variable picker và có thể được chọn.

Biến có tự động cập nhật không?

Có. Plugin lắng nghe sự kiện create, update, destroy trên collection nguồn. Khi dữ liệu thay đổi, biến tự động được tính lại. Cơ chế này sử dụng eventBus của ứng dụng — không cần refresh trang.

Có hỗ trợ biến dạng key-value đơn giản không?

Hiện tại plugin tập trung vào biến dạng aggregation (tính toán từ collection). Nếu cần biến key-value đơn giản (tên công ty, địa chỉ...), bạn có thể:

• Tạo collection riêng để lưu cấu hình
• Sử dụng Environment Variables cho giá trị tĩnh
• Hoặc tạo biến aggregation count trên collection một dòng

Biến có hỗ trợ đa ngôn ngữ không?

Trường label có translation: true, nghĩa là nhãn hiển thị của biến hỗ trợ đa ngôn ngữ. Tuy nhiên, giá trị tính toán (value) không phụ thuộc ngôn ngữ.

Cấu hình

Các aggregator được hỗ trợ là gì?

Aggregator	Mô tả	Ví dụ
count	Đếm số bản ghi	Số đơn hàng
sum	Tổng giá trị trường	Tổng doanh thu
avg	Giá trị trung bình	Trung bình đơn hàng
min	Giá trị nhỏ nhất	Đơn hàng nhỏ nhất
max	Giá trị lớn nhất	Đơn hàng lớn nhất

Có thể lọc trùng lặp (distinct) không?

Có. Đặt "distinct": true trong options để loại bỏ giá trị trùng lặp trước khi aggregation. Ví dụ: đếm số khách hàng duy nhất (distinct customer_id).

Precision là gì?

precision xác định số chữ số thập phân cho kết quả. Mặc định là 2. Hữu ích nhất cho avg (trung bình). Ví dụ: precision: 0 cho số nguyên, precision: 2 cho 2 chữ số thập phân.

Làm sao dùng biến làm badge trên menu?

1. Tạo biến aggregation (ví dụ: đếm số task chờ xử lý)
2. Vào cấu hình menu item → Menu Settings → Badge
3. Chọn biến Custom Variable
4. Badge sẽ hiển thị giá trị biến trên menu item

Plugin đăng ký EditBadge component vào menuSettings:menuItem và PageTabSettings cho tính năng này.

Lỗi thường gặp

Lỗi "Custom variable X not found. It may have been deleted."

Nguyên nhân: Biến đang được tham chiếu nhưng đã bị xóa khỏi database.

Cách xử lý:

1. Kiểm tra danh sách biến — nếu biến đã bị xóa, tạo lại với cùng tên
2. Hoặc cập nhật nơi tham chiếu biến (workflow, template...) để dùng biến khác

Biến không xuất hiện trong variable picker

Nguyên nhân có thể:

1. Plugin chưa được kích hoạt
2. Biến đang loading (kiểm tra kết nối mạng)

Cách xử lý:

1. Đảm bảo plugin-custom-variables đã bật trong Plugin Manager
2. Refresh trang
3. Kiểm tra console log xem có lỗi API không

Giá trị biến không cập nhật sau khi thay đổi dữ liệu

Nguyên nhân có thể:

1. Event listener chưa được đăng ký cho collection đó
2. Thay đổi dữ liệu qua SQL trực tiếp (không qua API) — event không được trigger

Cách xử lý:

1. Đảm bảo thay đổi dữ liệu qua API Digiforce (không qua SQL trực tiếp)
2. Refresh trang để force re-resolve biến

Biến aggregation trả về giá trị không đúng

Nguyên nhân có thể:

1. Filter trong options không đúng cú pháp
2. Tên collection hoặc field sai
3. Biến lồng nhau trong filter chưa được resolve

Cách xử lý:

1. Kiểm tra cấu hình options (collection, field, aggregator, filter)
2. Thử query trực tiếp trên database để verify kết quả
3. Đảm bảo các biến trong filter ($currentUser...) có giá trị hợp lệ