• Français

      • Synchroniser les données utilisateur depuis Feishu

      Introduction

      Le plugin Feishu / Lark synchronise les utilisateurs et départements d'une organisation Feishu vers NocoBase. Synchronisation complète à la demande et mises à jour incrémentales via callback HTTP ou connexion Stream.

      Avant de commencer

      1. Installez et activez les plugins Feishu / Lark et Synchronisation des données utilisateur.
      2. Créez une application interne sur la plateforme ouverte Feishu, voir Authentification : Feishu / Lark.
      3. Accordez les permissions de contacts et configurez le périmètre de visibilité comme décrit ci-dessous.

      Permissions de contacts et périmètre de visibilité

      Dans Gestion des permissions de l'application, activez :

      PermissionScopeRequisObjectif
      Obtenir les informations de base de l'utilisateurcontact:user.base:readonlyOuiLit noms, open_id / union_id et autres champs de base.
      Obtenir les informations de base du départementcontact:department.base:readonlyOuiLit noms et hiérarchie des départements.
      Obtenir la structure organisationnelle des départementscontact:department.organize:readonlyOuiParcourt les sous-départements ; lit les responsables.
      Obtenir la structure organisationnelle de l'utilisateurcontact:user.department:readonlyOuiLit départements et département principal.
      Obtenir le user IDcontact:user.id:readonlySi identifiant user_idLit le champ user_id.
      Obtenir le téléphone de l'utilisateurcontact:user.phone:readonlyPour les téléphonesLit les numéros ; requis si identifiant mobile.
      Obtenir l'e-mail de l'utilisateurcontact:user.email:readonlyPour les e-mailsLit les e-mails ; requis si identifiant email.

      Configurez ensuite le périmètre de permissions de contacts (départements et membres accessibles) :

      1. Dans Configuration développement → Permissions, cliquez sur Configurer dans la colonne « Périmètre de données accessible » (l'activation d'une permission de contacts y mène automatiquement).
      2. Choisissez les départements et membres ; recommandé : Tous les membres au départ, puis restreindre si besoin.
      3. Cliquez sur OK.
      Warning

      Sans Obtenir les informations de base de l'utilisateur, l'API ne renvoie pas les noms et les surnoms synchronisés restent vides. Le périmètre de permissions de contacts et la « disponibilité de l'application » (qui peut l'utiliser) sont deux réglages indépendants ; seul le premier affecte la synchronisation. Les permissions d'API déterminent les champs lisibles, le périmètre les départements et utilisateurs lisibles ; configurez les deux. Après modification, relancez une synchronisation complète. L'abonnement aux événements ne remplace pas les permissions de lecture : à chaque événement, NocoBase interroge l'API Feishu.

      Ajouter une source de synchronisation Feishu

      Dans Utilisateurs et permissions → Synchronisation, ajoutez une source de type Feishu / Lark :

      ChampDescription
      Nom de la sourceNom unique de la source.
      ActivéDémarre la réception d'événements et autorise les tâches de synchronisation.
      RégionFeishu China ou Lark Global.
      App ID / App SecretIdentifiants de l'application. Variables d'environnement et secrets pris en charge.
      Champ d'identifiant uniqueuser_id, union_id, open_id, mobile ou email ; union_id recommandé. Doit correspondre à l'authentificateur ; utilisateurs sans valeur ignorés.
      Mode de réception des événementsCallback HTTP ou mode Stream, voir ci-dessous.

      Enregistrez et activez la source, puis cliquez Synchroniser pour la première synchronisation complète.

      Choisir le mode de réception

      Mode Stream

      Le mode Stream maintient une connexion WebSocket initiée par le serveur NocoBase. Aucune URL publique, token ni clé de chiffrement requis.

      1. Sélectionnez mode Stream dans NocoBase, enregistrez et activez.
      2. Sur la plateforme, dans Événements et callbacks, passez la réception en connexion longue (WebSocket) et abonnez-vous aux événements de contacts.

      La connexion démarre automatiquement (reconnexion automatique) et se renouvelle ou se ferme selon le cycle de vie de la source.

      Info

      Le mode Stream ne nécessite ni adresse entrante publique ni proxy inverse ; adapté aux déploiements intranet. Vérifiez la connexion dans les journaux avec Feishu stream client.

      Callback HTTP

      1. Sélectionnez callback HTTP et configurez le Verification Token et éventuellement l'Encrypt Key — au moins un requis.
      2. Enregistrez et copiez l'URL de callback d'événements affichée.
      3. Sur la plateforme, dans Événements et callbacks → Configuration des événements, choisissez l'envoi au serveur, collez l'URL et abonnez-vous aux événements de contacts.

      L'URL doit être joignable par Feishu (HTTPS en production). Avec Encrypt Key, le contenu est chiffré.

      Warning

      Sans Verification Token ni Encrypt Key, les requêtes sont rejetées (401). Une source passée en mode Stream ferme le endpoint HTTP (403).

      Événements incrémentaux pris en charge

      ÉvénementTraitement dans NocoBase
      contact.user.created_v3Créer ou mettre à jour l'utilisateur.
      contact.user.updated_v3Mettre à jour l'utilisateur.
      contact.user.deleted_v3Supprimer l'utilisateur synchronisé.
      contact.department.created_v3Créer ou mettre à jour le département.
      contact.department.updated_v3Mettre à jour le département.
      contact.department.deleted_v3Supprimer le département synchronisé.

      Les utilisateurs avec le rôle Root ne sont jamais supprimés par la synchronisation.

      Champs synchronisés

      Champs de département

      Champ FeishuChamp / usage NocoBase
      open_department_idIdentifiant source du département.
      nameNom du département.
      parent_department_idDépartement parent pour la hiérarchie ; hors périmètre = synchronisé comme racine.

      Champs d'utilisateur

      Champ FeishuChamp / usage NocoBase
      Valeur du champ identifiantIdentifiant source et nom d'utilisateur issus du champ d'identifiant unique.
      name, sinon en_nameSurnom ; vide si les deux manquent.
      mobileTéléphone.
      emailE-mail.
      department_idsDépartements de l'utilisateur ; dans le périmètre uniquement.
      main_department_idDépartement principal.

      Responsables de département

      Les responsables issus des données de département sont synchronisés comme propriétaires : un utilisateur peut diriger plusieurs départements, pas nécessairement le sien. Seuls les départements du périmètre participent. Un responsable retiré côté Feishu l'est à la prochaine synchronisation ; les modifications manuelles peuvent être écrasées.

      Avatar, poste, matricule et autres champs ne sont pas synchronisés actuellement.

      Dépannage

      • Résultats vides ou départements manquants : vérifiez permissions et périmètre.
      • Surnoms vides : activez Obtenir les informations de base de l'utilisateur (contact:user.base:readonly) et resynchronisez.
      • Utilisateurs ignorés : valeur d'identifiant manquante ou incohérence avec l'authentificateur.
      • Callback HTTP 401 : Verification Token / Encrypt Key absents ou incorrects ; 403 : source passée en mode Stream.
      • Erreurs redirect_uri ou d'URL de callback : correspondance exacte avec l'URL affichée par NocoBase (préfixe APP_PUBLIC_PATH inclus).
      • Échec par limite de fréquence API : attendez la levée de la limite et relancez manuellement.