Trình xử lý gửi mail đến từng người dùng được dùng trong Marketing Workflow để gửi một email riêng cho từng participant thuộc loại người dùng. Mỗi participant sẽ được xử lý độc lập: hệ thống lấy thông tin user, xác định email nhận, render mail template theo parameters của workflow run, rồi gửi mail.
Handler name cần chọn trong Workflow Step là:
send_email_to_one_user

Khi nào nên dùng

Dùng trình xử lý này khi cần gửi cùng một mẫu email cho nhiều người dùng trong một campaign hoặc participant segment, ví dụ:
  • gửi email thông báo mở bán,
  • gửi email chăm sóc khách hàng,
  • gửi email nhắc lịch,
  • gửi email theo danh sách user được lọc bằng participant segment.

Điều kiện cần có

Workflow chỉ chạy đúng khi thỏa các điều kiện sau:
  • Workflow Step có handlerName là send_email_to_one_user.
  • Participant Segment có participantType là user.
  • Fetch participants script trả về danh sách participant hợp lệ.
  • Workflow Run có parameters chứa mailTemplateName.
  • Mail template tương ứng đã tồn tại trong hệ thống mail template.
  • User có email, hoặc participant trả về email ở cột phù hợp.

Cấu hình Workflow Step

Trong màn hình thêm hoặc sửa Workflow Step:
  • Handler Name: chọn Gửi email đến một người dùng, tương ứng với giá trị kỹ thuật send_email_to_one_user.
  • Status: nên để ACTIVATED.
  • Step Order: dùng để xác định thứ tự chạy nếu workflow có nhiều step.
  • Handler Script: không cần nhập nếu đã chọn handler name.

Gắn parameters vào Workflow Run

Khi tạo hoặc sửa Workflow Run, nhập JSON vào ô Parameters.
Ví dụ tối thiểu:
{
  "mailTemplateName": "chua-nguyen-bac-phat-mo-ban"
}
Trong đó:
  • mailTemplateName là bắt buộc.
  • Giá trị của mailTemplateName phải trùng với tên mail template trong hệ thống.
  • Toàn bộ object JSON này sẽ được truyền vào mail template dưới dạng parameters.
Nếu thiếu mailTemplateName, handler sẽ trả về kết quả: 
mailTemplateName is empty

Parameters truyền vào mail template

Khi gửi mail, hệ thống sẽ truyền các parameters từ Workflow Run vào mail template. Ngoài các field bạn tự khai báo trong JSON, handler còn tự động thêm:
user
user là thông tin người dùng được lấy từ user id của participant.
Ví dụ Workflow Run parameters:
{
  "mailTemplateName": "chua-nguyen-bac-phat-mo-ban",
  "campaignName": "Chùa Nguyễn Bắc Phật mở bán",
  "landingPageUrl": "https://example.com/mo-ban"
}
Mail template có thể dùng các biến như:
user
campaignName
landingPageUrl

Dữ liệu participant cần trả về

Participant Segment nên trả về mỗi participant theo cấu trúc khuyến nghị:
[pageTokenOrLastId, userId, email]
Ví dụ ý nghĩa:
[1001, 25, "user@example.com"]
Handler sẽ hiểu:
  • nếu participant có từ 3 phần tử trở lên: userId nằm ở phần tử thứ 2, email nằm ở phần tử thứ 3;
  • nếu participant có 2 phần tử: phần tử thứ nhất là userId, phần tử thứ hai là email.
Khuyến nghị dùng dạng 3 phần tử vì executor cũng dùng phần tử đầu tiên làm page token để chạy phân trang qua participant segment.

Luồng xử lý

flowchart TD
    A[Workflow Run đến thời điểm chạy] --> B[Executor lấy campaign participant segment]
    B --> C[Executor chạy fetch participants script]
    C --> D[Parse parameters từ Workflow Run]
    D --> E[Lấy Workflow Step đang ACTIVATED]
    E --> F[Gọi handler send_email_to_one_user cho từng participant]
    F --> G[Kiểm tra participant type là user]
    G --> H[Lấy user và email]
    H --> I[Lấy mailTemplateName từ parameters]
    I --> J[Gửi templated mail]

Kết quả xử lý

Handler trả về chuỗi kết quả để executor ghi log.
Một số kết quả thường gặp:
send mail successfully
mailTemplateName is empty
participantType is empty
participant is invalid
participants is invalid
user id: <id> is invalid
user email is empty

Ví dụ cấu hình hoàn chỉnh

Workflow Step:
handlerName = send_email_to_one_user
status = ACTIVATED
Workflow Run parameters:
{
  "mailTemplateName": "chua-nguyen-bac-phat-mo-ban"
}
Participant Segment:
participantType = user
Participant trả về:
[lastId, userId, email]
Khi workflow run được executor xử lý, mỗi user trong participant segment sẽ nhận một email được render từ template chua-nguyen-bac-phat-mo-ban.