Tạo action

Action là một thao tác có tên trên dữ liệu, thường là một câu SQL có tham số. Sau khi publish, người dùng chạy action qua form tự sinh ở trang Chạy action, trong view, từ JS action hoặc theo lịch.

Vai trò cần có

• Editor trở lên: tạo, sửa, publish, rollback action và đặt môi trường áp dụng.
• Admin trở lên: đặt quyền chạy (thẻ Quyền trên action) và xoá action.

Tạo action SQL

1. Vào Xây dựng > Action, bấm Tạo action.

2. Nhập Tên và Slug. Slug là mã dùng để gọi action từ view hoặc JS action và không đổi được sau khi publish.

3. Chọn Loại là SQL, sau đó chọn Data source (PostgreSQL hoặc MySQL).

4. Chọn Kiểu:

   • Chỉ đọc: chạy trong transaction read-only. Publish bị từ chối nếu SQL có INSERT, UPDATE, DELETE.
   • Ghi dữ liệu: được phép ghi. Người chạy luôn phải xác nhận trước khi chạy.

   Kiểu cũng không đổi được sau khi publish. Muốn đổi kiểu, tạo action mới.

5. Bấm Tạo. Trang chi tiết mở ở tab Định nghĩa.

Ô Loại có SQL và JavaScript (JS action). Action SQL chạy trên data source PostgreSQL hoặc MySQL. Hiện chưa có loại action nào chạy trên data source HTTP; data source HTTP mới chỉ lưu được config và thử kết nối.

Viết SQL và khai báo param

Viết câu SQL ở tab Định nghĩa. Editor gợi ý tên bảng và tên cột của data source. Tham số viết theo dạng {{tenParam}}:

SELECT id, customer, status, total
FROM orders
WHERE status = {{status}}
ORDER BY id

Mỗi {{tenParam}} phải được khai báo ở phần Param:

1. Bấm Thêm param, hoặc Thêm N param từ SQL để thêm một lần mọi param đang dùng trong SQL mà chưa khai báo.
2. Đặt Tên trùng với tên trong {{...}}, Nhãn hiển thị trên form, Kiểu param, và tick bắt buộc nếu cần.
3. Mở Nâng cao để thêm Mô tả (hiện dưới ô nhập ở form chạy) và Giá trị mặc định (điền sẵn ở form chạy).

Param luôn được truyền dưới dạng giá trị (bind), không bao giờ được ghép vào chuỗi SQL. Mỗi action có tối đa 50 param.

Kiểu param

Kiểu	Ô nhập trên form chạy
string	Ô chữ
number, integer	Ô số
boolean	Công tắc
date, datetime	Bộ chọn ngày; datetime có thêm ô giờ
enum	Danh sách thả xuống

Chi tiết: Tham số.

Danh sách chọn (enum) và master data

Với kiểu enum, chọn Nguồn giá trị:

• Danh sách cố định: nhập Giá trị enum, cách nhau bằng dấu phẩy. Form hiển thị trước các giá trị sẽ có trong dropdown.
• Lấy từ action: dùng kết quả của một action khác làm danh sách (master data, ví dụ danh sách cửa hàng). Chọn Chọn action nguồn đã publish, sau đó chọn Cột giá trị và Cột nhãn.

Ghi chú

Action nguồn được chạy không kèm param, vì vậy action nguồn không được có param bắt buộc. Người chạy phải có quyền chạy action nguồn; nếu không, danh sách báo lỗi.

Param ở vị trí tên cột hoặc tên bảng

Chỉ param kiểu enum dùng danh sách cố định mới được đặt ở vị trí tên cột hoặc tên bảng, ví dụ để chọn cột sắp xếp:

SELECT id, customer, total FROM orders ORDER BY {{sort_column}}

Danh sách cố định đóng vai trò danh sách cho phép. Danh sách lấy từ action khác không dùng được ở vị trí này. Sau khi publish, trang cho biết những param nào được nội suy như tên cột.

Transformer

Transformer (tuỳ chọn) là một hàm JavaScript ngắn dùng để biến đổi kết quả trước khi hiển thị: đổi tên cột, thêm link, ảnh, badge. Bấm Thêm transformer:

export default (rows, ctx) => rows.map((r) => ({
  ID: linkToView('order-detail', { orderId: r.id }, r.id),
  'Ảnh': image(r.photo_url, { width: 40, height: 40 }),
  'Trạng thái': badge(r.status, r.status === 'paid' ? 'success' : 'warning'),
  'Ngày tạo': formatDate(r.created_at, 'YYYY-MM-DD'),
}));

Các hàm builtin: linkToAction, linkToView, linkToURL, image, video, badge, formatDate. Transformer chạy trong sandbox: không có fetch và không đọc được dữ liệu nào ngoài rows và ctx.

Lưu nháp, publish và version

1. Bấm Lưu nháp để lưu phần đang sửa. Lưu nháp không kiểm tra gì và không ảnh hưởng tới bản đang chạy.
2. Bấm Publish. Server kiểm tra SQL trước khi cho phép chạy. Nếu có lỗi, trang hiện Publish bị từ chối: kèm danh sách lỗi và badge số lỗi trên thanh đầu trang.
3. Với action ghi dữ liệu hoặc action đã bật ở production, hộp Publish vN? hiện ra. Hộp này so sánh câu lệnh với bản đang dùng, liệt kê param được thêm, bỏ hoặc đổi kiểu, và các môi trường áp dụng. Xác nhận để publish.
4. Mỗi lần publish thành công tạo một version mới. Trang Chạy action, view, JS action, job và lịch (kể cả job đang chờ) dùng version mới ngay lập tức.

Các trường hợp publish bị từ chối

• SQL dùng param chưa khai báo, hoặc có param đã khai báo nhưng không dùng.
• Param ở vị trí tên cột hoặc tên bảng nhưng không phải enum có danh sách cố định.
• Action Chỉ đọc có câu ghi (INSERT, UPDATE, DELETE).
• Câu DDL như DROP, ALTER, TRUNCATE, GRANT.
• Nhiều câu lệnh không bọc trong transaction (PostgreSQL). Với MySQL: mỗi action chỉ có một câu lệnh, không có câu điều khiển transaction, và chỉ dùng các loại câu được phép (đọc: SELECT, SHOW, EXPLAIN, DESC; ghi: INSERT, REPLACE, UPDATE, DELETE, CALL).
• Biến hệ thống sai tên, ví dụ {{$user.name}} (chỉ có $user.id và $user.email).
• Danh sách lấy từ action không hợp lệ: action nguồn không tồn tại, chưa publish, hoặc người publish không có quyền chạy.

Bản nháp và bản đang dùng

Khi còn bản nháp chưa publish, trang hiện thông báo Bản nháp chưa publish — trang Chạy action vẫn chạy vN. Nút Chạy thử chỉ hiện khi action đã được publish và người dùng có quyền chạy; nút này mở trang Chạy action với form sinh từ param. Bản nháp không chạy được.

So sánh và rollback

1. Mở tab Version (N). Mỗi dòng là một version đã publish; bản đang chạy được đánh dấu đang dùng.
2. Bấm Xem code trên một version. Tab Code hiện câu lệnh và transformer của version đó; tab So với bản đang dùng (vN) hiện khác biệt theo từng dòng.
3. Bấm Quay về bản này (hoặc Quay về vN trong hộp xem code), sau đó xác nhận.

Rollback chỉ đổi bản đang dùng. Thao tác này không tạo version mới, không sửa version cũ, và có thể chuyển lại bản mới hơn bất cứ lúc nào. Từ lúc xác nhận, mọi lần chạy (kể cả job đang chờ) dùng version đã chọn.

Môi trường áp dụng

Action được tạo chung cho cả project nhưng chỉ chạy được ở các môi trường đã bật. Mặc định, action mới áp dụng ở mọi môi trường trừ production.

1. Mở tab Cài đặt & quyền (với editor, tab này có tên Cài đặt).
2. Ở thẻ Môi trường áp dụng, bật hoặc tắt từng môi trường. Thay đổi được lưu ngay.
3. Khi bật một môi trường production, hệ thống luôn yêu cầu xác nhận: bấm Bật ở production. Tắt môi trường không cần xác nhận.

Cùng tab này có thẻ Thông tin chung gồm Tên, Mô tả (hiện cho người chạy), Timeout (giây) (0,1–300, mặc định 30) và Số dòng tối đa (1–1.000.000, mặc định 10.000). Các thay đổi ở đây áp dụng ngay cho bản đang chạy và không tạo version.

Quyền chạy

Thẻ Quyền trên action (chỉ admin thấy) quy định ai được chạy action, trên trang Chạy action, trong view và qua JS action.

• Chế độ quyền: open — mọi thành viên hoặc restricted — chỉ ai được cấp. Đổi chế độ luôn có bước xác nhận.
• Ở chế độ restricted, dùng Cấp quyền chạy cho để thêm thành viên, group hoặc JS action, sau đó bấm Cấp quyền. Bấm Thu hồi để gỡ quyền.
• Action restricted bị ẩn khỏi trang Chạy action đối với người chưa được cấp. Owner và admin cũng không chạy được nếu chưa được cấp.

Chú ý

Action ghi dữ liệu ở chế độ open cho phép mọi thành viên ghi dữ liệu qua action đó. Trang sẽ khuyến nghị chuyển sang restricted và chỉ cấp quyền cho người cần. Xem Phân quyền.

Xoá action

Thẻ Xoá action nằm cuối tab Cài đặt & quyền (cần vai trò Admin). Khi action bị xoá, không ai chạy được action đó nữa, lịch của action bị xoá, job chưa xong bị huỷ và quyền đã cấp bị gỡ. Lịch sử chạy được giữ nguyên. Thao tác này không hoàn tác được.

Không xoá được action khi còn JS action gọi action đó, còn view (bản đang dùng) khai báo action đó, hoặc còn param của action khác lấy danh sách từ action đó. Hộp xác nhận liệt kê từng chỗ cần gỡ trước.

Xem thêm

• JS action: điều phối nhiều action trong một lần chạy.
• Chạy action
• Giới hạn