@digiforce-nc/plugin-workflow-json-variable-mapping

Plugin đăng ký node mapping biến JSON trong workflow, mở rộng plugin-workflow. Chuyển đổi cấu trúc (shape) của object JSON từ dạng này sang dạng khác bằng cách ánh xạ field.

Plugin này làm gì?

Node JSON Variable Mapping nhận một hoặc nhiều object JSON nguồn và tạo object mới theo cấu trúc đích. Mỗi field trong object đích được ánh xạ từ một path trong object nguồn hoặc từ biến workflow. Phù hợp để chuẩn bị dữ liệu trước khi gửi API hoặc lưu vào DB.

Ví dụ điển hình: Hệ thống nội bộ dùng firstName + lastName, nhưng API CRM bên ngoài yêu cầu first_name + last_name. Node này chuyển đổi giữa hai format mà không cần viết code.

Cấu hình

Tham số	Kiểu	Mô tả
mappings	array	Danh sách rules ánh xạ field
mappings[].source	string	Path nguồn (biến workflow hoặc dot notation)
mappings[].target	string	Tên field đích trong object kết quả
mappings[].type	string	Kiểu chuyển đổi: direct, template, constant
mappings[].value	any	Giá trị cố định (khi type = constant)

Input / Output

Hướng	Dữ liệu	Mô tả
Input	source objects	Một hoặc nhiều object/biến từ workflow context
Input	mapping rules	Quy tắc ánh xạ field nguồn sang field đích
Output	result	Object mới theo cấu trúc đích

Tính năng chính

#	Tính năng	Chi tiết
1	Field mapping	Ánh xạ trực tiếp field nguồn sang field đích
2	Rename field	Đổi tên field (ví dụ: firstName sang first_name)
3	Constant value	Gán giá trị cố định cho field đích
4	Nested source	Đọc từ nested path: order.customer.email
5	Multi-source	Kết hợp dữ liệu từ nhiều biến workflow vào một object
6	Template	Tạo giá trị bằng template kết hợp nhiều biến

Trường hợp sử dụng

#	Kịch bản	Mô tả
1	Chuẩn bị API payload	Transform từ cấu trúc nội bộ sang format API bên ngoài
2	Đổi tên field	Chuyển camelCase sang snake_case cho hệ thống khác
3	Merge dữ liệu	Gộp thông tin từ node query + node HTTP thành một object
4	Tạo audit log	Tạo object log từ nhiều biến: user, action, timestamp
5	Chuẩn hóa data	Đồng nhất format dữ liệu từ nhiều nguồn khác nhau

Ví dụ mapping

Source path	Target field	Type	Kết quả
order.customerName	name	direct	Copy giá trị
order.items.length	itemCount	direct	Số lượng items
—	source	constant	"digiforce"
order.id	ref	template	"ORD-[order.id]"
user.email	contact_email	direct	Rename field

Lưu ý quan trọng

• Nếu source path không tồn tại, field đích sẽ là undefined (không gây lỗi)
• Type constant bỏ qua source - luôn gán giá trị cố định
• Type template cho phép ghép nhiều biến: "Order #[orderId] - [customerName]"
• Mapping không hỗ trợ transform kiểu dữ liệu - dùng Dynamic Calculation nếu cần
• Thứ tự mapping rules quan trọng khi có field đích trùng nhau (rule sau ghi đè)

Dependencies

Package	Vai trò
@digiforce-nc/plugin-workflow	Workflow engine (peer)
@digiforce-nc/server	Server framework (peer)

Mục lục chi tiết

• Cấu hình node
• Ví dụ sử dụng