• Bahasa Indonesia

      • Menyinkronkan Data Pengguna dari DingTalk

      Authentication: DingTalkProfessional Edition+

      Pengantar

      Plugin DingTalk menyinkronkan pengguna dan departemen organisasi DingTalk ke NocoBase. Plugin ini mendukung sinkronisasi penuh manual dan pembaruan inkremental melalui callback HTTP atau koneksi Stream.

      Persiapan

      1. Instal dan aktifkan plugin DingTalk dan Sinkronisasi Data Pengguna.
      2. Buat aplikasi internal perusahaan di konsol pengembang DingTalk.
      3. Berikan izin kontak dan atur cakupan izin data seperti dijelaskan di bawah.
      4. Salin Client ID dan Client Secret. Lihat Autentikasi: DingTalk.

      Mengatur izin kontak dan cakupan izin data

      Buka Manajemen Izin aplikasi di DingTalk dan berikan izin berikut:

      IzinIdentifikasiWajibKegunaan
      Membaca informasi departemenqyapi_get_department_listYaMembaca daftar, nama, dan hierarki departemen.
      Membaca anggota departemenqyapi_get_department_memberYaMembaca anggota setiap departemen.
      Membaca informasi anggotaqyapi_get_memberYaMembaca detail pengguna dan keanggotaan departemen.
      Informasi nomor seluler karyawanfieldMobileSaat memakai nomor selulerMenyinkronkan nomor telepon; wajib bila pengenal unik adalah mobile.
      Email dan informasi pribadi lainnyafieldEmailTidakDiperlukan untuk menyinkronkan alamat email.

      Atur juga Cakupan Izin Data agar mencakup departemen dan karyawan yang boleh disinkronkan. Pilih semua karyawan untuk sinkronisasi seluruh organisasi.

      Warning

      Izin API menentukan field yang dapat dibaca, sedangkan cakupan izin data menentukan departemen dan karyawan yang dapat dibaca. Keduanya wajib dikonfigurasi. Langganan event tidak menggantikan izin baca kontak.

      Jika aplikasi yang sama juga dipakai untuk login, tambahkan izin informasi pribadi yang dijelaskan di Autentikasi: DingTalk.

      Menambahkan sumber sinkronisasi DingTalk

      Buka Pengguna & Izin > Sinkronkan, klik Tambah, lalu pilih DingTalk.

      FieldKeterangan
      Nama sumberNama unik sumber sinkronisasi.
      AktifMemulai penerimaan event dan mengizinkan tugas sinkronisasi.
      Client IDClient ID aplikasi; mendukung variabel lingkungan dan secret.
      Client SecretClient Secret aplikasi; mendukung variabel lingkungan dan secret.
      Pengenal unik penggunamobile atau unionId. Jangan ubah setelah sinkronisasi pertama. Pengguna tanpa nilai yang dipilih akan dilewati.
      Mode penerimaan eventCallback HTTP atau mode Stream untuk perubahan inkremental.

      Simpan dan aktifkan sumber, lalu klik Sinkronkan untuk menjalankan sinkronisasi penuh pertama.

      Memilih mode penerimaan event

      Mode Stream

      Mode Stream membuat koneksi persisten keluar dari server NocoBase ke DingTalk. URL callback publik, Token, dan EncodingAESKey tidak diperlukan.

      1. Pilih mode Stream pada pengaturan langganan event DingTalk.
      2. Langgan event perubahan pengguna dan departemen yang diperlukan.
      3. Pilih mode Stream di NocoBase, simpan, dan aktifkan sumber.

      Klien Stream dimulai saat sumber diaktifkan. Pembaruan, penonaktifan, atau penghapusan sumber akan memperbarui atau menutup koneksi.

      Info

      Server NocoBase harus dapat membuat koneksi keluar ke DingTalk. Mode Stream tidak memerlukan reverse proxy atau endpoint masuk publik.

      Callback HTTP

      1. Pilih Callback HTTP di NocoBase.
      2. Masukkan Token dan EncodingAESKey dari konfigurasi event DingTalk.
      3. Simpan sumber dan salin URL callback event yang dibuat.
      4. Atur URL tersebut di DingTalk dan langgan event pengguna serta departemen.

      URL callback harus dapat diakses DingTalk. Gunakan HTTPS di produksi dan pastikan reverse proxy meneruskan path secara utuh.

      Event inkremental yang didukung

      EventPenanganan di NocoBase
      user_add_orgMembuat atau memperbarui pengguna.
      user_modify_orgMemperbarui pengguna.
      user_leave_orgMenghapus pengguna yang disinkronkan.
      org_dept_createMembuat atau memperbarui departemen.
      org_dept_modifyMemperbarui departemen dan menyinkronkan penggunanya.
      org_dept_removeMenghapus departemen yang disinkronkan.

      Field yang disinkronkan

      Field departemen

      Field DingTalkField atau kegunaan NocoBase
      dept_idPengenal unik departemen dari sumber.
      nameNama departemen.
      parent_idDepartemen induk. Jika di luar cakupan data, departemen disinkronkan sebagai departemen akar.

      Field pengguna

      Field DingTalkField atau kegunaan NocoBase
      mobile atau unionidPengenal unik sumber dan username sesuai konfigurasi.
      nameNama panggilan pengguna.
      mobileNomor telepon. Memerlukan fieldMobile.
      email, dengan fallback org_emailAlamat email. Memerlukan fieldEmail.
      dept_id_listKeanggotaan departemen dalam cakupan izin data.
      dept_order_listDepartemen utama.
      leader_in_deptMenandai apakah pengguna adalah penanggung jawab departemen.

      Penanggung jawab departemen

      NocoBase menyinkronkan leader_in_dept secara terpisah untuk setiap departemen. Seorang pengguna dapat bertanggung jawab atas beberapa departemen, terlepas dari departemen utamanya. Jika tanda dihapus di DingTalk, sinkronisasi berikutnya akan menghapusnya di NocoBase. Perubahan manual dapat ditimpa.

      Sinkronisasi penuh dan inkremental memakai pemetaan field yang sama. Avatar, jabatan, dan nomor karyawan belum disinkronkan.

      Pemecahan masalah

      • Jika data kosong atau tidak lengkap, periksa tiga izin wajib dan cakupan izin data.
      • Jika nomor seluler atau email kosong, periksa fieldMobile dan fieldEmail.
      • Pengguna tanpa pengenal unik yang dikonfigurasi akan dilewati.
      • Untuk Stream, periksa log Dingtalk stream client starting, Dingtalk stream client started, dan error koneksi.
      • Untuk callback HTTP, periksa akses publik, Token, dan EncodingAESKey.
      • Jalankan ulang sinkronisasi penuh setelah mengubah izin atau cakupan data.