Lặp theo phần tử (For each)

Mục đích

Bước Lặp theo phần tử (For each) cho phép bạn xử lý một danh sách mà không cần thiết kế lại quy trình. Với mỗi phần tử trong danh sách, hệ thống tạo ra một phiên chạy con độc lập để thực hiện toàn bộ nhóm bước bên trong (gọi là “thân vòng lặp”). Các phiên chạy con hoàn toàn tách biệt: mỗi phiên có công việc, ngân sách và dữ liệu riêng.

Bên trong thân vòng lặp, bạn có thể dùng các biến:

input.item — phần tử hiện tại của danh sách.
input.index — chỉ số thứ tự (bắt đầu từ 0) của phần tử đó.

Khi nào dùng

Gửi email thông báo cho từng người trong danh sách người phê duyệt.
Trợ lý AI (Agent) xem xét từng dòng trong đơn đặt hàng và trích xuất thông tin.
Đẩy từng bản ghi từ kết quả tích hợp (Integration) lên hệ thống ngoài.
Yêu cầu xác nhận từng hạng mục mua sắm qua bước Công việc người dùng (Human task) riêng biệt.
Xử lý từng hồ sơ — hoặc từng tệp — trong một thư mục theo dõi (Watched folder), xem mục bên dưới.

Cài đặt chính

Cài đặt	Mô tả
Danh sách lặp (List to iterate)	Biến mảng từ bước trước hoặc dữ liệu đầu vào của quy trình. Chỉ chọn được biến kiểu mảng (array).
Kiểu thực thi (Execution)	Parallel — các phiên chạy con chạy đồng thời (mặc định). Sequential — chạy lần lượt theo thứ tự danh sách.
Số lượng đồng thời tối đa (Max concurrent)	Chỉ áp dụng khi chọn Parallel. Giới hạn số phiên chạy con hoạt động cùng lúc (từ 1 đến 16, mặc định 5).
Tiếp tục khi một phần tử lỗi (Keep going if an item fails)	Bật (mặc định): một phiên chạy con thất bại được ghi nhận và vòng lặp vẫn chạy tiếp những phần tử còn lại. Tắt: sau lỗi đầu tiên vòng lặp không tạo thêm phiên con nào nữa, chờ các phiên đang chạy kết thúc rồi tổng kết.
Đánh lỗi cả phiên chạy nếu có phần tử lỗi (Fail the run if any item fails)	Bật (mặc định): khi mọi phần tử đã xong, chỉ cần một phần tử lỗi là bước lặp bị coi là lỗi và quy trình cha dừng lại. Tắt: bước lặp vẫn đi tiếp, phần lỗi nằm trong kết quả để bước sau tự xử lý.
Thân vòng lặp (Loop body)	Nhóm các bước được xây dựng trực tiếp trên canvas bên trong khung container. Mỗi bước trong thân vòng lặp đọc được `input.item`, `input.index` và các biến của quy trình cha.

Hai ô đánh dấu về lỗi là độc lập với nhau: ô thứ nhất quyết định có chạy tiếp hay không, ô thứ hai quyết định kết luận cuối cùng sau khi mọi phần tử đã xong. Cả hai đều bật sẵn, nên theo mặc định một phần tử lỗi không chặn các phần tử còn lại, nhưng vẫn làm cả phiên chạy hỏng ở cuối.

Ví dụ

Trong quy trình Đề xuất mua sắm, giả sử Trợ lý AI trả về danh sách các mặt hàng cần duyệt riêng (nodes.ai-review.output.items). Bạn thêm bước Lặp theo phần tử (For each) để xét từng mặt hàng:

Cài đặt	Giá trị
Danh sách lặp	`nodes.ai-review.output.items`
Kiểu thực thi	Parallel
Số lượng đồng thời tối đa	5
Tiếp tục khi một phần tử lỗi	Bật

Bên trong thân vòng lặp:

Bước Trợ lý AI (Agent) — đánh giá mặt hàng dựa trên input.item.name và input.item.price.
Bước Công việc người dùng (Human task) — người phụ trách xác nhận kết quả đánh giá.

Kết quả của bước lặp

Sau khi mọi phiên chạy con kết thúc, các bước tiếp theo của quy trình cha đọc được bốn biến sau — trong trình chọn biến chúng nằm dưới tên bước lặp:

Biến	Nội dung
Items — `nodes.<mã bước>.output.items`	Một mục cho mỗi phần tử, kèm chỉ số thứ tự, trạng thái, và dữ liệu mà phiên chạy con trả về (hoặc thông báo lỗi, nếu phần tử đó hỏng).
Succeeded — `…output.succeeded`	Số phần tử chạy thành công.
Failed — `…output.failed`	Số phần tử thất bại.
Total — `…output.total`	Tổng số phần tử đã chạy.

Lặp trên một thư mục theo dõi (Watched folder)

Danh sách mà vòng lặp duyệt không nhất thiết phải là kết quả của một bước trước đó. Nếu biểu mẫu bắt đầu có một trường tệp cho phép chọn nhiều tệp, người khởi chạy có thể bấm Dùng thư mục theo dõi thay cho Đính kèm tệp và chỉ định một thư mục theo dõi. Khi đó vòng lặp chạy trên chính nội dung của thư mục ấy — hàng nghìn tài liệu vào quy trình mà không ai phải kéo thả qua trình duyệt.

Có hai cách nối, và mỗi cách cho input.item một dạng dữ liệu khác nhau:

Cách nối	Mỗi phiên chạy con xử lý	`input.item` là
Danh sách lặp trỏ vào kết quả của một bước Gộp tệp (Group files) — biến hiện với tên Folders, đường dẫn `nodes.<mã bước>.output.groups`	một hồ sơ (một thư mục con)	danh sách các tệp của hồ sơ đó
Danh sách lặp trỏ thẳng vào trường tệp của biểu mẫu bắt đầu — đường dẫn `input.<tên trường>`	một tệp	một tài liệu duy nhất

Điều quyết định là có hay không một bước Gộp tệp nằm giữa trường tệp và vòng lặp. Có thì vòng lặp chạy theo hồ sơ; không thì chạy theo từng tệp. Đây không phải một tùy chọn khi khởi chạy — sơ đồ quy trình quyết định, còn màn hình khởi chạy chỉ cho biết kết quả: chạy theo hồ sơ thì hiện số hồ sơ kèm số tệp tương ứng, chạy theo tệp thì hiện số tệp.

Dạng dữ liệu này được chốt lại tại thời điểm phiên chạy bắt đầu. Sửa sơ đồ sau đó không làm đổi dạng dữ liệu của một phiên đang chạy; thay đổi chỉ có hiệu lực với những lần khởi chạy sau.

Xem Gộp tệp (Group files) để biết cách đặt mức thư mục cho một hồ sơ, và Thư mục theo dõi để thiết lập chính thư mục đó.

Xem thêm cách đọc dữ liệu đầu vào tại Bắt đầu (Start) và cách cấu hình Trợ lý AI tại Trợ lý AI (Agent).