@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)