ldap_groups_sync/modules/ldap_departments_sync/README.md

LDAP Departments Sync

Módulo Drupal para sincronização de departamentos do LDAP com grupos do Drupal.

Funcionalidades

• Sincronização automática de departamentos do LDAP para grupos no Drupal
• Mapeamento flexível de atributos LDAP para campos de grupo
• Sincronização de membros de departamentos baseada em campos de usuário
• Suporte a hierarquia de departamentos
• Mapeamento dinâmico de papéis (roles) nos grupos baseado em campos
• Campos de referência a departamentos reutilizáveis para content types

Requisitos

• Drupal 10.x ou 11.x
• Módulo LDAP (ldap_servers, ldap_query)
• Módulo Group
• Módulo Entity Reference Views Select (opcional, para widgets avançados)
• Módulo Telephone (para campo de telefone)
• Módulo Profile (opcional, para usar field_department em profiles)

Instalação

1. Coloque o módulo no diretório modules/custom/ldap_departments_sync
2. Habilite o módulo: drush en ldap_departments_sync -y
3. Configure em /admin/config/ldap/ldap_departments_sync

Instalação da Configuração Padrão

O módulo inclui configurações opcionais que podem ser instaladas via interface:

1. Acesse /admin/config/ldap/ldap_departments_sync
2. Na seção "Tipo de Grupo", clique em "Instalar Configuração Padrão"
3. Isso criará:
   • Tipo de grupo "Departments"
   • Campos de departamento (código, sigla, tipo, telefone, sala, e-mail, coordenadores)
   • Roles do grupo (admin, member, etc.)
   • Displays de visualização e formulário

Configuração

Mapeamento de Atributos LDAP

Configure os mapeamentos entre atributos LDAP e campos de grupo em: /admin/config/ldap/ldap_departments_sync

Exemplo de configuração padrão:

• imeccDepartmentCode → field_dept_code
• description → label
• cn → field_dept_acronym
• imeccDepartmentType → field_dept_type
• imeccDepartmentCoord → field_dept_coord (referência a usuário)
• imeccDepartmentAssocCoord → field_dept_coord_assoc (referência a usuário)

Sincronização de Membros

O módulo pode sincronizar automaticamente membros para os grupos baseado em:

• Matching entre field_user_dept_code (usuário) e field_dept_code (grupo)
• Atribuição automática de roles baseado em campos de usuário

Hierarquia de Departamentos

Para habilitar hierarquia:

1. Marque "Enable Hierarchy"
2. Configure:
   • Parent Attribute: atributo LDAP do pai (ex: departmentNumber)
   • Child Attribute: atributo LDAP do filho para matching (ex: imeccDepartmentCode)

Adicionando Campos de Referência a Departamentos

O módulo fornece um handler de seleção customizado que facilita a criação de campos de referência a departamentos em qualquer entidade (nodes, users, profiles, etc.).

Como Adicionar um Campo de Departamento

1. Acesse a página de gerenciamento de campos da entidade desejada:

   • Content Types: Structure > Content types > [Tipo] > Manage fields
   • User: Configuration > People > Account settings > Manage fields
   • Profiles: Configuration > People > Profile types > [Tipo] > Manage fields

2. Clique em "Create a new field"

3. Em "Add a new field":

   • Selecione "Reference" como categoria
   • Escolha "Other..." (ou "Outro...")
   • Preencha o Label (ex: "Departamento", "Department", "Setor", etc.)
   • Clique em "Continue"

4. Configure o field storage:

   • Type of item to reference: Selecione "Group" (Grupo)
   • Clique em "Save field settings"

5. Configure as definições do campo:

   • Reference method: Selecione "Department selection"
   • Group type: Automaticamente pré-selecionado como "Departments"
   • Filter by department type: (Opcional) Marque para filtrar por tipo
   • Allowed department types: (Opcional) Selecione tipos permitidos:
     • ☐ Acadêmico
     • ☐ Administrativo
   • Configure outras opções conforme necessário:
     • Required: Se o campo é obrigatório
     • Help text: Texto de ajuda
     • Default value: Valor padrão
   • Clique em "Save settings"

Vantagens desta Abordagem

• ✅ Nomes customizáveis: Escolha qualquer machine name para o campo
• ✅ Múltiplos campos: Adicione vários campos de departamento no mesmo bundle com propósitos diferentes
• ✅ Filtragem por tipo: Opção de filtrar apenas departamentos acadêmicos ou administrativos
• ✅ Pré-configurado: O handler "Department selection" já vem configurado com as opções corretas
• ✅ Flexível: Use em qualquer tipo de entidade (nodes, users, profiles, custom entities, etc.)

Exemplos de Uso

Múltiplos campos no mesmo content type:

Article:
  - field_primary_department (obrigatório, todos os tipos)
  - field_secondary_department (opcional, todos os tipos)
  - field_academic_dept (opcional, apenas acadêmicos)

Diferentes configurações por bundle:

Student Profile:
  - field_department (obrigatório, apenas acadêmicos)

Staff Profile:
  - field_department (obrigatório, apenas administrativos)

Sincronização Manual

Execute via Drush:

drush ldap-departments-sync

Ou via interface em /admin/config/ldap/ldap_departments_sync clicando em "Sync Now".

Sincronização Automática (Cron)

O módulo sincroniza automaticamente durante a execução do cron do Drupal.

Estrutura de Campos do Grupo

Campos padrão criados para o group type "departments":

• field_dept_code - Código do departamento (texto, obrigatório, único)
• field_dept_acronym - Sigla/acrônimo
• field_dept_type - Tipo (acadêmico/administrativo)
• field_dept_phone - Telefone
• field_dept_room - Sala
• field_dept_mail - E-mail
• field_dept_coord - Coordenador (referência a usuário)
• field_dept_coord_assoc - Coordenador associado (referência a usuário)
• field_parent_group - Grupo pai (para hierarquia)

Campos de Usuário

Campos necessários no user entity para sincronização de membros:

• field_user_dept_code - Código do departamento do usuário
• field_user_department - Referência ao grupo de departamento

Desenvolvimento

Hooks Disponíveis

(Documentação futura)

API

(Documentação futura)

Licença

GPL-2.0-or-later

Autor

Desenvolvido para o IME - UNICAMP