Cài đặt và sử dụng — Custom Variables

Tổng quan

Plugin Custom Variables cho phép định nghĩa các biến tùy chỉnh có thể sử dụng trong workflow, template, UI config và các nơi cần giá trị động. Biến được quản lý qua giao diện, lưu trong database và có thể tham chiếu qua cú pháp $customVariables.tenBien.

Loại biến hỗ trợ

Plugin chủ yếu hỗ trợ biến dạng aggregation — tính toán giá trị từ dữ liệu collection (count, sum, avg, min, max). Mỗi biến bao gồm:

Trường	Kiểu	Mô tả
`name`	`string` (Primary Key)	Tên biến, duy nhất, ví dụ: `total_orders`
`label`	`string`	Nhãn hiển thị, hỗ trợ đa ngôn ngữ (translation)
`type`	`string`	Loại biến, mặc định `aggregation`
`declaredAt`	`uid`	Nơi biến được khai báo
`options`	`json`	Cấu hình chi tiết cho biến

Cấu trúc `options` cho biến aggregation

json

{
  "collection": "orders",
  "field": "total",
  "aggregator": "sum",
  "filter": { "status": "completed" },
  "distinct": false,
  "precision": 2,
  "params": {
    "filter": { "status": { "$eq": "completed" } }
  }
}

Option	Mô tả
`collection`	Tên collection nguồn dữ liệu
`field`	Tên trường cần aggregation
`aggregator`	Phương thức: `count`, `sum`, `avg`, `min`, `max`
`filter`	Điều kiện lọc (tùy chọn)
`distinct`	Loại trùng lặp (mặc định `false`)
`precision`	Số chữ số thập phân (mặc định 2, dùng cho `avg`)

Bước 1: Kích hoạt Plugin

Vào Settings → Plugin Manager
Tìm plugin-custom-variables
Bật toggle để kích hoạt

Bước 2: Tạo biến tùy chỉnh

Trong giao diện variable picker (khi cấu hình workflow, template...), nhấn nút Add Variable
Hoặc truy cập trực tiếp qua API customVariables:create
Điền thông tin biến:
- Variable Name: Tên biến (unique, không khoảng trắng)
- Label: Nhãn hiển thị
- Options: Cấu hình aggregation (collection, field, aggregator, filter)

Bước 3: Sử dụng biến

Trong Variable Picker

Plugin đăng ký biến $customVariables vào hệ thống variable. Khi bạn mở variable picker (trong workflow, filter, default value...), sẽ thấy nhóm "Custom Variables" với danh sách biến đã tạo.

Chọn biến từ danh sách → hệ thống tự chèn tham chiếu dạng $customVariables.total_orders.

Cơ chế resolve biến

Khi biến được sử dụng, plugin thực hiện:

Tự động làm mới (Auto-refresh)

Plugin tự động lắng nghe sự kiện trên collection nguồn. Khi dữ liệu trong collection thay đổi (create, update, destroy), biến sẽ tự động được tính lại:

collection:{name}:create — Khi thêm bản ghi mới
collection:{name}:update — Khi cập nhật bản ghi
collection:{name}:destroy — Khi xóa bản ghi

Điều này đảm bảo biến luôn phản ánh giá trị mới nhất mà không cần refresh thủ công.

Plugin cho phép hiển thị giá trị biến làm badge (huy hiệu đếm) trên menu item hoặc tab. Ví dụ: hiển thị số đơn hàng chờ xử lý trên menu "Orders".

Cấu hình trong Menu Settings hoặc Page Tab Settings → chọn Badge → chọn biến Custom Variable.

Biến lồng nhau trong Filter

Filter của biến aggregation có thể chứa tham chiếu đến biến khác. Plugin sử dụng hàm parseFilter() để thay thế các biến trong filter trước khi thực thi query:

typescript

// Ví dụ filter chứa biến
{
  "status": "$currentUser.department"
}
// Sau khi parse:
{
  "status": "Sales"
}

Ví dụ thực tế

Đếm đơn hàng chờ xử lý

json

{
  "name": "pending_orders_count",
  "label": "Đơn hàng chờ xử lý",
  "type": "aggregation",
  "options": {
    "collection": "orders",
    "field": "id",
    "aggregator": "count",
    "params": {
      "filter": { "status": { "$eq": "pending" } }
    }
  }
}

Tính tổng doanh thu tháng

json

{
  "name": "monthly_revenue",
  "label": "Doanh thu tháng",
  "type": "aggregation",
  "options": {
    "collection": "orders",
    "field": "total",
    "aggregator": "sum",
    "precision": 0,
    "params": {
      "filter": {
        "createdAt": { "$dateOn": "thisMonth" },
        "status": { "$eq": "completed" }
      }
    }
  }
}

Lưu ý

Biến thay đổi có hiệu lực ngay, không cần khởi động lại
Collection customVariables có shared: true — dữ liệu được chia sẻ giữa các data source
Mỗi lần resolve biến đều query database — tránh tạo quá nhiều biến aggregation trên bảng lớn
Filter trong biến hỗ trợ tham chiếu đến biến hệ thống ($currentUser, $date...)