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

Tổng quan

Plugin workflow engine cho phép tự động hoá quy trình nghiệp vụ bằng cách tạo các luồng xử lý (flow) với trigger và nodes. Hỗ trợ extensible triggers, instructions, và custom functions.

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

Vào Settings → Plugin Manager, tìm plugin-workflow và bật.

Hoặc kích hoạt qua dòng lệnh:

bash

yarn pm enable plugin-workflow

Bước 2: Tạo Workflow

Vào Settings → Workflow
Nhấn Create Workflow
Đặt tên, chọn trigger type
Cấu hình trigger
Thêm các nodes (bước xử lý)
Bật Enabled khi sẵn sàng

Bước 3: Cấu hình Trigger

Collection Event Trigger

Kích hoạt khi có sự kiện trên collection:

Sự kiện	Mô tả	Ví dụ
`afterCreate`	Sau khi tạo bản ghi	Đơn hàng mới → gửi email xác nhận
`afterUpdate`	Sau khi cập nhật	Trạng thái đổi → thông báo
`afterDestroy`	Sau khi xóa	Xóa user → cleanup dữ liệu liên quan

Schedule Trigger

Chạy theo lịch cron:

Cron	Mô tả
`0 8 * * *`	Mỗi ngày 8h sáng
`0 0 * * 1`	Mỗi thứ Hai 0h
`/30 * * *`	Mỗi 30 phút

Bước 4: Thêm Nodes

Calculation Node

Tính toán giá trị hoặc gán biến:

javascript

// Ví dụ: tính tổng đơn hàng
return $context.data.price * $context.data.quantity;

Condition Node

Rẽ nhánh theo điều kiện:

CRUD Nodes

Node	Chức năng	Ví dụ
Create	Tạo bản ghi mới	Tạo log entry
Update	Cập nhật bản ghi	Đổi trạng thái đơn hàng
Destroy	Xóa bản ghi	Xóa bản ghi tạm
Query	Truy vấn dữ liệu	Tìm user theo điều kiện

Bước 5: Xem Execution Logs

Mỗi lần workflow chạy tạo 1 execution với các jobs (mỗi node = 1 job):

Trạng thái	Ý nghĩa
`created`	Execution mới tạo, chưa xử lý
`started`	Đang xử lý
`resolved`	Hoàn thành thành công
`rejected`	Thất bại (có lỗi)
`canceled`	Bị hủy

Vào Settings → Workflow → [Workflow Name] → Executions để xem lịch sử.

Extensibility — Mở rộng plugin

Đăng ký Trigger tùy chỉnh

typescript

class MyPlugin extends Plugin {
  async load() {
    const workflowPlugin = this.app.pm.get('workflow') as PluginWorkflowServer;
    workflowPlugin.registerTrigger('my-trigger', MyCustomTrigger);
  }
}

Đăng ký Instruction tùy chỉnh

typescript

workflowPlugin.registerInstruction('send-sms', SendSMSInstruction);

Đăng ký Custom Function

Plugin đăng ký sẵn các functions:

Function	Mô tả
`instanceId`	ID của instance hiện tại
`epoch`	Epoch timestamp
`genSnowflakeId`	Sinh Snowflake ID duy nhất

Plugin khác có thể đăng ký thêm qua workflowPlugin.functions.register().

Cơ chế Dispatcher

Plugin sử dụng Dispatcher để quản lý việc thực thi workflow:

Dispatcher kiểm tra queue mỗi 5 phút (cycling check)
Hỗ trợ event queue cho async processing
Sync message giữa các instance khi workflow bật/tắt

Logging

Mỗi workflow có log file riêng:

logs/workflows/{workflowId}/YYYY-MM-DD.log
logs/workflows/dispatcher/YYYY-MM-DD.log

Logger dùng LRU cache (max 20 logger) để tối ưu memory.

Telemetry

Plugin đăng ký gauge metric workflow.events.counter — theo dõi số event đang chờ trong dispatcher.

Lưu ý quan trọng

Test trước khi dùng thật — workflow lỗi có thể ảnh hưởng dữ liệu
Workflow loop có thể chạy vô hạn — luôn đặt điều kiện dừng
Workflow versioning: mỗi lần enable lại tạo version mới, version cũ bị disable
Xóa workflow sẽ xóa cả tasks liên quan
User nhận thông báo task qua WebSocket (ws:sendToUser)