Câu hỏi thường gặp (FAQ) — User Data Sync

Sử dụng

Đồng bộ có ghi đè dữ liệu hiện tại không?

Phụ thuộc vào cấu hình resource type. Mặc định, hệ thống sẽ:

• Tạo mới nếu user chưa tồn tại (dựa trên email hoặc ID nguồn)
• Cập nhật nếu user đã tồn tại — các field được map sẽ ghi đè
• Các field không có trong mapping sẽ giữ nguyên

Có thể đồng bộ từ nhiều nguồn không?

Có. Tạo nhiều sync source, mỗi cái cấu hình riêng:

Source 1: LDAP Production → đồng bộ nhân viên chính
Source 2: HR API → đồng bộ thông tin phòng ban
Source 3: CSV Import → đồng bộ user tạm thời

Mỗi source hoạt động độc lập, không ảnh hưởng lẫn nhau.

Pull và Push khác nhau thế nào?

	Pull	Push
Ai khởi tạo	Digiforce gọi đến nguồn	Nguồn gửi dữ liệu đến Digiforce
Khi nào dùng	LDAP, database — Digiforce chủ động lấy	Webhook, event — nguồn chủ động gửi
Action	userData:pull	userData:push
Yêu cầu	Cần source name	Cần dataType và records

Retry hoạt động thế nào?

Khi một record đồng bộ thất bại, bạn có thể thử lại bằng cách gọi:

await agent.resource('userData').retry({
  sourceId: 1,  // ID của sync source
  id: 42,       // ID của record thất bại
});

Plugin sẽ lấy lại dữ liệu record và thử xử lý lại.

Cấu hình

Làm sao đăng ký source type mới?

Plugin khác có thể đăng ký source type qua SyncSourceManager:

class MyHRPlugin extends Plugin {
  async load() {
    const syncPlugin = this.app.pm.get('user-data-sync') as PluginUserDataSyncServer;
    syncPlugin.sourceManager.registerType('my-hr-system', {
      title: 'My HR System',
      pull: async (sourceConfig) => {
        // Kết nối HR system và trả về records
      },
    });
  }
}

Làm sao đăng ký resource type mới?

Resource type xử lý dữ liệu đồng bộ (ví dụ: tạo user từ record):

syncPlugin.resourceManager.registerResource({
  name: 'department',
  accepts: ['department'],
  handle: async (records) => {
    // Xử lý tạo/cập nhật department
  },
});

Log file đồng bộ lưu ở đâu?

Plugin tạo logger riêng với cấu hình:

• Thư mục: logs/user-data-sync/
• Format file: YYYY-MM-DD.log
• Format nội dung: JSON

Ví dụ: logs/user-data-sync/2024-01-15.log

Xử lý sự cố

Đồng bộ thất bại?

Kiểm tra theo thứ tự:

1. Kết nối nguồn: Đảm bảo Digiforce server có thể kết nối đến nguồn (LDAP, API endpoint)
2. Credentials: Kiểm tra options trong sync source có thông tin xác thực đúng
3. Source enabled: Xác nhận source có enabled: true
4. Log file: Xem log tại logs/user-data-sync/ để biết lỗi cụ thể
5. Task status: Xem collection userDataSyncTasks để kiểm tra trạng thái và message

Push báo lỗi "dataType is not supported"?

Khi gọi userData:push, plugin kiểm tra dataType trong payload có được resource nào hỗ trợ không. Nếu không:

{ "code": 500, "message": "dataType user is not supported" }

Giải pháp: đảm bảo đã đăng ký resource type hỗ trợ dataType đó.

Đồng bộ chạy lâu?

Nguyên nhân và giải pháp:

Nguyên nhân	Giải pháp
Số lượng record lớn	Chia thành nhiều batch nhỏ
Network chậm	Kiểm tra kết nối đến nguồn
Database chậm	Kiểm tra index trên collection users

Thời gian mỗi lần đồng bộ được ghi trong field cost (ms) của userDataSyncTasks.

Source type không hiển thị?

Gọi userData:listSyncTypes để kiểm tra. Nếu type không có trong danh sách:

• Plugin cung cấp source type chưa được bật
• Hoặc source type chưa được đăng ký qua sourceManager.registerType()