• Русский

      • Синхронизация пользовательских данных из DingTalk

      DingTalkProfessional Edition+

      Введение

      Плагин DingTalk синхронизирует пользователей и отделы организации DingTalk с NocoBase. Поддерживаются ручная полная синхронизация и инкрементальные обновления через HTTP callback или соединение Stream.

      Перед началом

      1. Установите и включите плагины DingTalk и Синхронизация пользовательских данных.
      2. Создайте внутреннее приложение в консоли разработчика DingTalk.
      3. Предоставьте разрешения адресной книги и настройте область данных, описанные ниже.
      4. Скопируйте Client ID и Client Secret. См. Аутентификация: DingTalk.

      Настройка разрешений адресной книги и области данных

      В разделе Управление разрешениями приложения DingTalk предоставьте:

      РазрешениеИдентификаторОбязательноНазначение
      Чтение информации об отделахqyapi_get_department_listДаЧтение списка, названий и иерархии отделов.
      Чтение сотрудников отделаqyapi_get_department_memberДаЧтение сотрудников каждого отдела.
      Чтение информации о сотрудникахqyapi_get_memberДаЧтение данных пользователей и их отделов.
      Мобильные номера сотрудниковfieldMobileПри использовании номераСинхронизация телефона; обязательно, если идентификатор — mobile.
      Электронная почта и личные данныеfieldEmailНетТребуется для синхронизации адресов электронной почты.

      Настройте Область разрешений данных, включив отделы и сотрудников, доступных для синхронизации. Для всей организации выберите всех сотрудников.

      Warning

      Разрешения API определяют доступные поля, а область данных — доступные отделы и сотрудников. Необходимо настроить оба параметра. Подписка на события не заменяет разрешения на чтение.

      Если приложение также используется для входа, предоставьте личные разрешения из раздела Аутентификация: DingTalk.

      Добавление источника DingTalk

      Откройте Пользователи и права > Синхронизация, нажмите Добавить и выберите DingTalk.

      ПолеОписание
      Имя источникаУникальное имя источника.
      ВключенЗапускает прием событий и разрешает задачи синхронизации.
      Client IDClient ID приложения; поддерживает переменные окружения и секреты.
      Client SecretClient Secret приложения; поддерживает переменные окружения и секреты.
      Уникальный идентификатор пользователяmobile или unionId. Не меняйте после первой синхронизации. Пользователи без выбранного значения пропускаются.
      Режим приема событийHTTP callback или Stream для инкрементальных изменений.

      Сохраните и включите источник, затем сначала выполните полную синхронизацию кнопкой Синхронизировать.

      Выбор режима приема событий

      Режим Stream

      Режим Stream устанавливает постоянное исходящее соединение от сервера NocoBase к DingTalk. Публичный URL, Token и EncodingAESKey не требуются.

      1. Выберите режим Stream в настройках подписки DingTalk.
      2. Подпишитесь на необходимые события пользователей и отделов.
      3. Выберите режим Stream в NocoBase, сохраните и включите источник.

      Клиент Stream запускается при включении источника. Обновление, отключение или удаление источника обновляет или закрывает соединение.

      Info

      Сервер NocoBase должен иметь исходящий доступ к DingTalk. Обратный прокси и публичная входящая точка не нужны.

      HTTP callback

      1. Выберите HTTP callback в NocoBase.
      2. Укажите Token и EncodingAESKey из настроек DingTalk.
      3. Сохраните источник и скопируйте созданный URL callback событий.
      4. Настройте URL в DingTalk и подпишитесь на необходимые события.

      URL должен быть доступен DingTalk. В рабочей среде используйте HTTPS и передавайте полный путь через обратный прокси.

      Поддерживаемые инкрементальные события

      СобытиеОбработка в NocoBase
      user_add_orgСоздать или обновить пользователя.
      user_modify_orgОбновить пользователя.
      user_leave_orgУдалить синхронизированного пользователя.
      org_dept_createСоздать или обновить отдел.
      org_dept_modifyОбновить отдел и синхронизировать его пользователей.
      org_dept_removeУдалить синхронизированный отдел.

      Синхронизируемые поля

      Поля отдела

      Поле DingTalkПоле или назначение в NocoBase
      dept_idУникальный идентификатор отдела в источнике.
      nameНазвание отдела.
      parent_idРодительский отдел. Если он вне области данных, отдел синхронизируется как корневой.

      Поля пользователя

      Поле DingTalkПоле или назначение в NocoBase
      mobile или unionidУникальный идентификатор источника и имя пользователя согласно настройке.
      nameОтображаемое имя пользователя.
      mobileТелефон. Требует fieldMobile.
      email, иначе org_emailЭлектронная почта. Требует fieldEmail.
      dept_id_listОтделы пользователя в пределах области данных.
      dept_order_listОсновной отдел.
      leader_in_deptПризнак руководителя соответствующего отдела.

      Руководители отделов

      NocoBase синхронизирует leader_in_dept отдельно для каждого отдела. Пользователь может руководить несколькими отделами независимо от основного отдела. После снятия признака в DingTalk следующая синхронизация снимет его в NocoBase. Ручные изменения могут быть перезаписаны.

      Полная и инкрементальная синхронизация используют одинаковое сопоставление. Аватар, должность и табельный номер сейчас не синхронизируются.

      Устранение неполадок

      • Если данные пусты или неполны, проверьте три обязательных разрешения и область данных.
      • Если отсутствует телефон или почта, проверьте fieldMobile и fieldEmail.
      • Пользователи без настроенного уникального идентификатора пропускаются.
      • Для Stream ищите в журналах Dingtalk stream client starting, Dingtalk stream client started и ошибки соединения.
      • Для HTTP callback проверьте публичный доступ, Token и EncodingAESKey.
      • После изменения разрешений или области выполните полную синхронизацию повторно.