Cài đặt và sử dụng — User Data Sync

Tổng quan

Plugin đồng bộ dữ liệu user từ nguồn bên ngoài vào Digiforce. Hỗ trợ hai chiều: pull (kéo từ nguồn) và push (nguồn đẩy vào). Mỗi lần đồng bộ được ghi nhận thành một task với trạng thái và thông tin chi tiết.

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-user-data-sync và bật.

Hoặc kích hoạt qua dòng lệnh:

bash

yarn pm enable plugin-user-data-sync

Bước 2: Tạo nguồn đồng bộ (Sync Source)

Vào Settings → User Data Sync → Sources → nhấn Add Source:

Trường	Mô tả	Bắt buộc
`name`	Tên duy nhất của nguồn (ví dụ: `ldap-production`)	Có
`displayName`	Tên hiển thị (ví dụ: "LDAP Production")	Không
`sourceType`	Loại nguồn (liệt kê từ `listSyncTypes`)	Có
`enabled`	Bật/tắt nguồn này	Không (mặc định: `false`)
`options`	Cấu hình kết nối (JSON — tùy loại nguồn)	Có

Ví dụ cấu hình LDAP source

json

{
  "url": "ldap://ldap.example.com:389",
  "bindDN": "cn=admin,dc=example,dc=com",
  "bindPassword": "secret",
  "searchBase": "ou=users,dc=example,dc=com",
  "searchFilter": "(objectClass=person)",
  "fieldMapping": {
    "displayName": "nickname",
    "mail": "email",
    "telephoneNumber": "phone"
  }
}

Bước 3: Kiểm tra loại nguồn khả dụng

Gọi API để xem danh sách source types đã đăng ký:

typescript

const res = await agent.resource('userData').listSyncTypes();
// Trả về danh sách source types: ['ldap', 'http-api', ...]

Bước 4: Chạy đồng bộ

Pull — Kéo dữ liệu từ nguồn

typescript

await agent.resource('userData').pull({
  name: 'ldap-production',
});

Plugin sẽ:

Tìm source config theo name
Kết nối đến nguồn
Kéo dữ liệu user
Tạo/cập nhật records trong Digiforce
Ghi nhận task với trạng thái và thời gian

Push — Nhận dữ liệu từ nguồn

typescript

await agent.resource('userData').push({
  values: {
    dataType: 'user',
    records: [
      { email: 'new@example.com', nickname: 'New User' },
    ],
  },
});

Push kiểm tra dataType có được resource nào hỗ trợ không. Nếu không hỗ trợ, trả lỗi 500.

Retry — Thử lại record thất bại

typescript

await agent.resource('userData').retry({
  sourceId: 1,
  id: 42,
});

Kiến trúc plugin

SyncSourceManager

Quản lý các loại nguồn (source types). Plugin khác có thể đăng ký source type mới:

typescript

const plugin = app.pm.get('user-data-sync') as PluginUserDataSyncServer;
plugin.sourceManager.registerType('custom-hr', {
  title: 'Custom HR System',
  // ... implementation
});

UserDataResourceManager

Quản lý các loại resource để xử lý dữ liệu đồng bộ (ví dụ: user, department). Mỗi resource khai báo accepts — danh sách dataType nó hỗ trợ.

Theo dõi đồng bộ

Collection `userDataSyncTasks`

Mỗi lần đồng bộ tạo 1 task:

Field	Mô tả
`batch`	Mã batch duy nhất
`source`	Nguồn đồng bộ (belongsTo `userDataSyncSources`)
`status`	Trạng thái: `pending`, `running`, `success`, `failed`
`message`	Thông báo lỗi (nếu có)
`cost`	Thời gian xử lý (ms)

Logging

Plugin tạo logger riêng ghi vào thư mục user-data-sync/:

logs/user-data-sync/2024-01-15.log

Format JSON, dễ phân tích bằng ELK hoặc log viewer.

ACL — Phân quyền

Resource	Quyền (snippet)
`userData:*`	Admin
`userDataSyncSources:*`	Admin
`userDataSyncTasks:*`	Admin

Chỉ admin có quyền quản lý đồng bộ user.

Lưu ý quan trọng

Đồng bộ thêm và cập nhật — mặc định không xóa user
Test với số lượng nhỏ trước khi đồng bộ toàn bộ
Kiểm tra field mapping đúng trước khi chạy production
Source type phải được đăng ký trước khi tạo source config
Log file riêng giúp debug đồng bộ mà không ảnh hưởng log chính