• Português

      • Sincronizar dados de usuário do DingTalk

      DingTalkProfessional Edition+

      Introdução

      O plugin DingTalk sincroniza usuários e departamentos de uma organização DingTalk com o NocoBase. Ele oferece sincronização completa manual e atualizações incrementais por callback HTTP ou conexão Stream.

      Antes de começar

      1. Instale e ative os plugins DingTalk e Sincronização de dados de usuário.
      2. Crie um aplicativo interno na central de desenvolvedores do DingTalk.
      3. Conceda as permissões de contatos e configure o escopo de dados descritos abaixo.
      4. Copie o Client ID e o Client Secret. Consulte Autenticação: DingTalk.

      Configurar permissões de contatos e escopo de dados

      Abra o Gerenciamento de permissões do aplicativo no DingTalk e conceda:

      PermissãoIdentificadorObrigatóriaFinalidade
      Ler informações de departamentosqyapi_get_department_listSimLer lista, nomes e hierarquia de departamentos.
      Ler membros de departamentosqyapi_get_department_memberSimLer os membros de cada departamento.
      Ler informações de membrosqyapi_get_memberSimLer detalhes e associações de usuários.
      Informações de celular dos funcionáriosfieldMobileAo usar celularSincronizar telefone; obrigatória quando o identificador é mobile.
      E-mail e outras informações pessoaisfieldEmailNãoNecessária para sincronizar e-mails.

      Configure também o Escopo de permissões de dados para incluir os departamentos e funcionários permitidos. Selecione todos os funcionários para sincronizar toda a organização.

      Warning

      As permissões de API determinam os campos legíveis; o escopo de dados determina os departamentos e funcionários legíveis. Ambos são necessários. A assinatura de eventos não substitui as permissões de leitura.

      Se o mesmo aplicativo também for usado para login, conceda as permissões pessoais descritas em Autenticação: DingTalk.

      Adicionar uma fonte DingTalk

      Acesse Usuários e permissões > Sincronizar, clique em Adicionar e selecione DingTalk.

      CampoDescrição
      Nome da fonteNome exclusivo da fonte.
      AtivadaInicia a recepção de eventos e permite tarefas de sincronização.
      Client IDClient ID do aplicativo; aceita variáveis de ambiente e segredos.
      Client SecretClient Secret do aplicativo; aceita variáveis de ambiente e segredos.
      Identificador único do usuáriomobile ou unionId. Não altere após a primeira sincronização. Usuários sem o valor escolhido são ignorados.
      Modo de recepçãoCallback HTTP ou modo Stream para alterações incrementais.

      Salve e ative a fonte; em seguida clique em Sincronizar para executar primeiro uma sincronização completa.

      Escolher o modo de recepção de eventos

      Modo Stream

      O modo Stream estabelece uma conexão persistente de saída do servidor NocoBase para o DingTalk. Não requer URL pública, Token ou EncodingAESKey.

      1. Selecione modo Stream nas configurações de eventos do DingTalk.
      2. Assine os eventos necessários de usuários e departamentos.
      3. Selecione modo Stream no NocoBase, salve e ative a fonte.

      O cliente Stream inicia quando a fonte é ativada. Atualizar, desativar ou excluir a fonte atualiza ou encerra a conexão.

      Info

      O servidor NocoBase precisa estabelecer conexões de saída com o DingTalk. Não é necessário proxy reverso nem endpoint público de entrada.

      Callback HTTP

      1. Selecione Callback HTTP no NocoBase.
      2. Informe o Token e o EncodingAESKey configurados no DingTalk.
      3. Salve a fonte e copie a URL de callback de eventos gerada.
      4. Configure a URL no DingTalk e assine os eventos de usuários e departamentos.

      A URL deve ser acessível pelo DingTalk. Em produção use HTTPS e preserve o caminho completo no proxy reverso.

      Eventos incrementais compatíveis

      EventoTratamento no NocoBase
      user_add_orgCriar ou atualizar o usuário.
      user_modify_orgAtualizar o usuário.
      user_leave_orgExcluir o usuário sincronizado.
      org_dept_createCriar ou atualizar o departamento.
      org_dept_modifyAtualizar o departamento e sincronizar seus usuários.
      org_dept_removeExcluir o departamento sincronizado.

      Campos sincronizados

      Campos de departamento

      Campo do DingTalkCampo ou finalidade no NocoBase
      dept_idIdentificador único do departamento na fonte.
      nameNome do departamento.
      parent_idDepartamento pai. Se estiver fora do escopo, o departamento será sincronizado como raiz.

      Campos de usuário

      Campo do DingTalkCampo ou finalidade no NocoBase
      mobile ou unionidIdentificador único da fonte e nome de usuário conforme a configuração.
      nameApelido do usuário.
      mobileTelefone. Requer fieldMobile.
      email, usando org_email como alternativaE-mail. Requer fieldEmail.
      dept_id_listDepartamentos do usuário dentro do escopo de dados.
      dept_order_listDepartamento principal.
      leader_in_deptIndica se o usuário é responsável pelo departamento.

      Responsáveis por departamentos

      O NocoBase sincroniza leader_in_dept separadamente para cada departamento. Um usuário pode responder por vários departamentos, independentemente do departamento principal. Ao remover a marca no DingTalk, a próxima sincronização também a remove no NocoBase. Alterações manuais podem ser sobrescritas.

      As sincronizações completa e incremental usam o mesmo mapeamento. Avatar, cargo e número de funcionário não são sincronizados atualmente.

      Solução de problemas

      • Se os dados estiverem vazios ou incompletos, verifique as três permissões obrigatórias e o escopo de dados.
      • Se telefone ou e-mail estiverem vazios, verifique fieldMobile e fieldEmail.
      • Usuários sem o identificador único configurado são ignorados.
      • No Stream, procure Dingtalk stream client starting, Dingtalk stream client started e erros de conexão nos logs.
      • No callback HTTP, verifique acesso público, Token e EncodingAESKey.
      • Execute nova sincronização completa após alterar permissões ou escopo.