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:

```bash
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