Import học viên

Khi cohort mới có 30–500 học viên, không thể nhập tay. Module TrainingManagement cung cấp import CSV để vừa tạo tài khoản mới vừa attach vào Batch trong một thao tác.

Một dòng tóm tắt

Vào trang Batch → Nhập học viên → upload CSV → preview → confirm → hệ thống tạo user mới (gửi welcome email kèm link đặt mật khẩu) + ghi danh vào Batch + auto enroll khoá thuộc Program.

Khi nào dùng?

• Cohort B2B mới — khách hàng gửi danh sách 50 nhân viên qua Excel.
• Migration từ hệ thống cũ — bạn có CSV xuất từ LMS cũ.
• Workshop đại trà — phát mã code không kịp; import danh sách trực tiếp nhanh hơn.

Vào trang Import

Trong trang chi tiết Batch → header → Nhập học viên:

URL: /admin/batches/{batch}/import.

Format CSV

Cột bắt buộc

email,first_name,last_name,phone
hung@example.com,Hùng,Nguyễn Văn,0901234567
lan@example.com,Lan,Trần Thị,0987654321
mai@example.com,Mai,Phạm,

Cột	Bắt buộc	Mô tả
email	✅	Định danh chính. Phải hợp lệ + chưa tồn tại với role khác (vd: không thể import 1 email là super_admin).
first_name	✅	Tên (không phải họ tên đầy đủ).
last_name	✅	Họ + tên đệm.
phone	⬜	Số điện thoại. Có thể trống.

UTF-8 + dấu phẩy

• Encoding UTF-8 (BOM hoặc không đều OK).
• Phân tách bằng dấu phẩy ,.
• Tên có dấu phẩy → đặt trong dấu nháy kép: "Nguyễn Văn, Hùng".
• Header bắt buộc ở dòng đầu — không có header → import fail.

Tải file mẫu

Trang Import có nút Tải file CSV mẫu — download template với header đúng + 2 dòng ví dụ. Edit và upload.

Quy trình import

Bước 1 — Upload

1. Click Chọn file → chọn CSV.
2. Click Xem trước.
3. Hệ thống parse CSV và validate từng dòng.

Bước 2 — Preview

Trang preview hiển thị mỗi dòng với:

Cột	Giá trị
Dòng	Số thứ tự trong CSV
Email	Đã trim
Tên	First name
Họ	Last name
SĐT	Phone
Trạng thái	(xem dưới)
Hành động	(xem dưới)

Trạng thái + hành động

Trạng thái	Action	Ý nghĩa
existing	"Sẵn có — sẽ thêm vào lớp"	User đã tồn tại trong tenant → chỉ attach vào Batch
new	"Tạo mới — sẽ thêm vào lớp"	User chưa tồn tại → tạo account + attach vào Batch
duplicate	"Trùng trong file — bỏ qua"	Email đã xuất hiện ở dòng trước → bỏ qua dòng sau
invalid	"Lỗi — bỏ qua"	Email sai format / tên trống / phone sai → bỏ qua

Tổng kết hiển thị: ":total dòng — :existing có sẵn, :new tạo mới, :duplicate trùng, :invalid lỗi".

Bước 3 — Tuỳ chọn welcome email

Tick checkbox "Gửi email chào mừng cho tài khoản mới":

• ✅ Bật (mặc định) → user mới nhận email chứa link đặt mật khẩu + giới thiệu tổ chức.
• ❌ Tắt → tạo account với mật khẩu tạm; bạn phải gửi mật khẩu cho họ qua kênh khác.

Bảo mật mật khẩu

Mật khẩu tạm không bao giờ hiển thị cho bạn. Nếu tắt welcome email, user sẽ không biết mật khẩu — bạn phải dùng tính năng "Quên mật khẩu" hoặc nhờ Tenant Admin reset.

→ Khuyến nghị luôn bật welcome email.

Bước 4 — Confirm

Click Xác nhận nhập:

1. Hệ thống chạy import (sync, có thể mất 5–30 giây cho 50–500 dòng).
2. Mỗi dòng existing / new được xử lý:
   • existing → attach vào batch_users + auto enroll khoá Program.
   • new → tạo User (role mặc định cho user mới — Tenant Admin cấu hình ở Cài đặt → Chung → Tài khoản) → attach Batch → auto enroll.
3. Nếu bật welcome email → queue email.

Bước 5 — Kết quả

Trang result:

"Đã nhập xong"

"Ghi danh :enrolled · Tạo mới :created tài khoản · Bỏ qua :skipped"

Nếu bật welcome email + có user mới:

"Email chào mừng đã được xếp hàng gửi cho tất cả tài khoản mới."

Sau khi import

Học viên new

1. Nhận welcome email với link Đặt mật khẩu.
2. Click → đặt mật khẩu → đăng nhập Learnspace.
3. Thấy lớp + khoá ngay trong Khoá học của tôi.

Học viên existing

1. Lần đăng nhập tiếp theo (hoặc nếu đang online → refresh) thấy lớp + khoá mới.
2. Nhận notification "Bạn đã được thêm vào lớp X" (nếu Tenant Admin cấu hình email batch enrollment).

Học viên duplicate / invalid

Không xử lý. Bạn cần sửa CSV và import lại các dòng đó (chỉ dòng cần — không bị duplicate vì email đã có).

Lỗi thường gặp

invalid — email sai format

abc@@example.com   ← double @
abc.example.com    ← thiếu @
"":xyz@example.com ← ký tự đặc biệt

Sửa CSV và import lại.

invalid — tên trống

first_name hoặc last_name là khoảng trắng / rỗng → fail. CSV phải có giá trị thực.

invalid — phone sai

Phone không bắt buộc nhưng nếu có, phải hợp lệ (regex tuỳ tenant). Trống thì không lỗi; điền sai thì fail.

duplicate trong file

email,first_name,last_name,phone
hung@example.com,Hùng,A,
hung@example.com,Hùng,B,   ← duplicate trong file

Dòng sau bị skip. Sửa CSV để mỗi email chỉ xuất hiện 1 lần.

Email đã có nhưng không attach được

Trường hợp đặc biệt:

• Email là user nhưng đã ở trạng thái deleted → cần Tenant Admin restore trước.
• Email là user nhưng có role incompatible (vd: super_admin) → import fail (an toàn — không gán super_admin vào Batch).

Quan hệ với các module khác

Với UserManagement

• User mới được tạo với role mặc định (Tenant Admin set ở Cài đặt → Chung → tab Tài khoản → Vai trò mặc định cho người dùng mới, thường là panel_user hoặc role học viên).
• Bạn (Training Manager) không đổi được default role; cần vào Tenant Admin.

Với Notifications

• Welcome email dùng template "Welcome New User" — Tenant Admin tuỳ biến nội dung.
• Mỗi email gửi qua queue — không block UI.

Với Batch

• User attach batch_users → trigger BatchCourseEnrollmentSync → auto enroll khoá Program.
• Nếu Batch có lộ trình mặc định → auto clone template thành lộ trình cá nhân.

Với Ecommerce

Import không liên quan Ecommerce — không tạo đơn hàng, không tính doanh thu. Phù hợp với enrollment miễn phí cohort B2B đã được thanh toán ngoài hệ thống.

Nếu cần track doanh thu, dùng Manual order (Sales/Finance) thay vì import.

Best practices

1. Test với 2–3 dòng trước — không upload 500 dòng ngay lần đầu. Test 3 dòng + xem flow chuẩn rồi mới scale.
2. Đặt template tên file rõ ràng — cohort-2026-04-acme-corp.csv thay vì students.csv.
3. Lưu file CSV đã import — nếu cần audit / so sánh sau, có file gốc.
4. Dùng Excel cẩn thận — Excel hay tự đổi format số điện thoại (vd: 0901... thành scientific notation). Save as CSV UTF-8 từ Excel; verify trong text editor trước khi upload.
5. Communicate với học viên — báo trước cho HR khách hàng / nhóm rằng welcome email sẽ tới, có khi vào Spam — tăng tỷ lệ activate.

Câu hỏi thường gặp

Tôi import 500 dòng nhưng UI báo timeout? Hệ thống xử lý sync. Nếu thực sự timeout, chia file thành 100/lần.

Import xong nhưng học viên báo không nhận welcome email?

• Check Spam folder.
• Kiểm tra Email Log trong Notifications (Tenant Admin) — email có ở Sent / Bounced?
• SMTP / DKIM / SPF cấu hình đúng không?

Có thể import học viên + đặt password tự? Không có UI. Chỉ tạo user với password tạm + welcome email. Nếu thực sự cần, nhờ Tenant Admin script.

Import xong rồi muốn rollback? Không có nút rollback. Cách thủ công:

• Detach các học viên vừa import khỏi Batch (filter theo created_at của batch_users).
• Xoá các user mới tạo (filter theo created_at của users + nguồn import).

Cẩn thận — chỉ làm nếu chắc chắn không attach nhầm vào người đã có.

File CSV có hỗ trợ thêm cột tuỳ biến (group, role)? Hiện chỉ 4 cột chuẩn. Mở rộng cần Tenant Admin code thêm hoặc dùng API.

Import vào Batch đã ở trạng thái Completed/Cancelled? Hệ thống chặn — chỉ Batch Active / Draft / Paused cho phép enroll mới. Lỗi "Không thể ghi danh học viên khi lớp ở trạng thái :status".