@digiforce-nc/plugin-workflow-get-json-field

Plugin đăng ký node trích xuất field từ JSON trong workflow, mở rộng plugin-workflow. Sử dụng dot path hoặc array index để lấy giá trị cụ thể từ object JSON phức tạp.

Plugin này làm gì?

Node Get JSON Field nhận một object JSON (từ biến workflow, HTTP response, hoặc dữ liệu bản ghi) và trích xuất giá trị tại đường dẫn (path) chỉ định. Hỗ trợ dot notation, array index, và nested path.

Khi workflow nhận dữ liệu từ API bên ngoài (qua HTTP Request node hoặc Webhook trigger), dữ liệu thường là JSON phức tạp nhiều cấp. Node này giúp "đào" vào đúng field cần thiết mà không cần viết JavaScript.

Cấu hình

Tham số	Kiểu	Mô tả
`source`	`string`	Biến workflow chứa JSON object nguồn
`path`	`string`	Đường dẫn trích xuất (dot notation): `data.user.name`
`defaultValue`	`any`	Giá trị mặc định khi path không tồn tại
`parseJson`	`boolean`	Tự động parse string thành JSON trước khi trích xuất

Input / Output

Hướng	Dữ liệu	Mô tả
Input	`source`	Object JSON hoặc chuỗi JSON
Input	`path`	Đường dẫn field cần lấy
Output	`result`	Giá trị tại path (bất kỳ kiểu: string, number, object, array)
Output	`exists`	`true` nếu path tồn tại, `false` nếu dùng defaultValue

Tính năng chính

#	Tính năng	Chi tiết
1	Dot notation	Truy cập nested field: `user.address.city`
2	Array index	Truy cập phần tử mảng: `items[0]`, `items[-1]` (cuối)
3	Auto parse	Tự động parse chuỗi JSON thành object
4	Default value	Giá trị fallback khi path không tìm thấy
5	Nested path	Kết hợp object và array: `data.users[2].roles[0].name`

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

#	Kịch bản	Mô tả
1	Lấy token từ API	Trích `data.access_token` từ response đăng nhập
2	Đọc webhook data	Lấy `payload.order.id` từ body webhook Shopee
3	Parse config	Đọc `settings.smtp.host` từ JSON config lưu trong DB
4	Lấy phần tử đầu	Trích `results[0]` từ kết quả search API
5	Nested extraction	Lấy `data.customer.addresses[0].city` từ response CRM

Ví dụ path thường dùng

Path	Mô tả	Kết quả
`data.name`	Field đơn giản	`"John"`
`items[0]`	Phần tử đầu tiên	object
`items[-1]`	Phần tử cuối cùng	object
`data.users[0].email`	Nested + array	`"john@example.com"`
`meta.total`	Metadata field	`42`

Lưu ý quan trọng

Path phân biệt hoa thường: user.Name khác user.name
Nếu source là string, bật parseJson: true để tự động parse
Array index âm: items[-1] lấy phần tử cuối, items[-2] lấy phần tử kế cuối
Khi path trỏ đến object hoặc array, kết quả là toàn bộ object/array đó
Nếu source là null hoặc undefined, trả về defaultValue ngay

Dependencies

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