Bản ghi thực thể (Entity record)

Mục đích

Bước Bản ghi thực thể (Entity record) kết nối quy trình với một Thực thể trong hệ thống và thực hiện một trong năm thao tác, chia thành hai nhóm: Đọc — Get one (đọc một bản ghi theo id hoặc khóa nghiệp vụ) và Search (tìm nhiều bản ghi theo bộ lọc); Ghi — Create (luôn tạo bản ghi mới), Update (cập nhật bản ghi theo id), và Upsert (tìm theo khóa nghiệp vụ, tạo mới nếu chưa có). Với các thao tác ghi, bạn chỉ chọn những trường cần ghi và gán giá trị từ biểu mẫu, đầu ra của các bước trước, hoặc giá trị cố định — các trường không được ánh xạ giữ nguyên giá trị hiện có.

Khi nào dùng

• Đọc một bản ghi nhà cung cấp theo id để hiển thị chi tiết trong bước Trợ lý AI (Agent) hoặc Email tiếp theo.
• Tìm các bản ghi Đơn mua hàng thỏa một điều kiện lọc (ví dụ: quá hạn thanh toán) để xử lý hàng loạt.
• Lưu kết quả phê duyệt vào bản ghi nhà cung cấp hoặc hợp đồng.
• Tạo bản ghi mua hàng mới khi quy trình hoàn tất.
• Cập nhật trạng thái bản ghi theo id được trả về từ bước trước.
• Tìm và cập nhật bản ghi theo khóa nghiệp vụ tự nhiên (ví dụ: mã nhà cung cấp) mà không cần biết id nội bộ.

Cài đặt chính

Trường	Mô tả
Thực thể (Entity)	Thực thể chứa bản ghi cần đọc hoặc ghi (bắt buộc). Với Thực thể hệ thống dựng sẵn (Users, Groups), chỉ Get one và Search khả dụng — các thao tác ghi bị ẩn khỏi danh sách chọn.
Thao tác (Operation)	Nhóm Đọc: Get one, Search. Nhóm Ghi: Create, Update, Upsert.
Khớp theo (Match by) — chỉ Get one	Id — nhập biểu thức/đường dẫn biến trỏ đến id bản ghi; Key — ánh xạ các trường tạo thành khóa nghiệp vụ trong phần Trường bên dưới.
ID bản ghi (Record id) — Get one theo Id, Update	Biểu thức hoặc đường dẫn biến trỏ đến id bản ghi cần đọc hoặc cập nhật.
Khớp trên khóa nào — Get one theo Key, Upsert	Chỉ hiện khi Thực thể khai báo nhiều hơn một khóa nghiệp vụ; chọn khóa dùng để khớp. Các trường tạo thành khóa đã chọn hiển thị dưới dạng huy hiệu.
Bộ lọc (Filters) — Search	Các điều kiện AND: chọn trường, toán tử (là, không phải, chứa, không chứa, bắt đầu bằng, kết thúc bằng, >, ≥, <, ≤, là một trong, không thuộc, trong khoảng, trống, không trống — tùy kiểu trường), và giá trị so sánh.
Tìm kiếm văn bản (Text search) — Search	Từ khóa tự do, quét trên các trường dạng văn bản có thể tìm kiếm của Thực thể.
Sắp xếp theo / Chiều — Search	Sắp theo Updated at (mặc định), Created at, hoặc một trường của Thực thể. Trường được đánh dấu Nhạy cảm không thể dùng làm khóa sắp xếp — giá trị sẽ lộ qua con trỏ phân trang.
Giới hạn (Limit) — Search	Số bản ghi tối đa trả về, tối đa 100.
Trường (Fields) — Create / Update / Upsert, và Get one theo Key	Danh sách cặp Trường → Giá trị. Mỗi dòng chọn một trường ghi được của Thực thể (trường tính toán bị loại khỏi danh sách; trường owner vẫn được phép ghi — đây là cách một quy trình gán chủ sở hữu bản ghi) và gán giá trị từ biến, template {{ }}, hoặc giá trị cố định.
Lưu bản ghi vào biến	Đường dẫn biến (ví dụ vars.reviewer) lưu toàn bộ bản ghi — object cho Get one / Create / Update / Upsert, hoặc toàn bộ mảng records[] cho Search. Id của bản ghi đọc qua <biến>.id, không cần một trường lưu-id riêng. Khả dụng cho mọi thao tác.

Ghi chú

Khi khớp theo Key (ở Get one hoặc Upsert), các trường tạo thành khóa nghiệp vụ của Thực thể hiển thị dưới dạng huy hiệu. Nếu Thực thể khai báo nhiều hơn một khóa, chọn khóa cần dùng trước, rồi đảm bảo mọi trường của khóa đó đều được ánh xạ đầy đủ trong phần Trường.

Chú ý

Thao tác Create không kiểm tra trùng lặp. Nếu quy trình chạy lại do lỗi, bản ghi có thể bị tạo thêm lần nữa — dùng Upsert khi cần đảm bảo không trùng. Trên một Thực thể đã lưu trữ (archived), Create bị chặn hoàn toàn và Upsert chỉ có thể cập nhật bản ghi đã có (không bao giờ tạo mới); Get one, Search, Update vẫn hoạt động bình thường.

Chú ý

Với người dùng không có quyền instance.admin, các trường được đánh dấu Nhạy cảm trên Thực thể hiển thị dạng che trong kết quả của Get one / Search — kể cả khi được lưu qua Lưu bản ghi vào biến. Trường id và các trường hệ thống trong metadata (phiên bản, thời điểm cập nhật, …) luôn hiển thị.

Ví dụ

Trong quy trình Đề xuất mua sắm, sau khi người dùng phê duyệt và tài liệu hợp đồng được tạo, một bước Bản ghi thực thể cập nhật Thực thể Đơn mua hàng như sau:

• Thực thể: Đơn mua hàng
• Thao tác: Upsert (khóa nghiệp vụ: ma_don)
• Trường:

Trường Thực thể	Nguồn giá trị
trang_thai	Giá trị cố định: "approved"
nguoi_phe_duyet	nodes.approval-step.output.actor
ngay_phe_duyet	nodes.approval-step.output.completed_at
so_tien	nodes.start-form.output.body.so_tien

• Lưu bản ghi vào biến: vars.purchaseOrder

Biến vars.purchaseOrder sau đó có thể được dùng trong bước Email — ví dụ {{ vars.purchaseOrder.id }} — để kèm link bản ghi vào email thông báo.

Để tránh tạo trùng nhà cung cấp, thêm một bước Bản ghi thực thể trước bước Upsert ở trên, với thao tác Search trên Thực thể Nhà cung cấp: bộ lọc ma_nha_cung_cap là {{ nodes.start-form.output.body.ma_ncc }}, giới hạn 1 bản ghi, lưu kết quả vào vars.ncc_tim_thay. Bước Quyết định (Decision) tiếp theo rẽ nhánh dựa trên nodes.buoc_tim_ncc.output.returnedCount để biết đã có bản ghi trùng khớp hay chưa.