Importação de Usuários e Perfis Externos
O sistema permite que usuários externos possam ser importados em lote. Esta funcionalidade facilita o cadastro e manutenção de usuários provindos de fontes externas.
Para acessar a funcionalidade entre em Configurações->Serviços->Importação de Usuários e Perfis Externos:
Fig. 01
Importação de Usuários Externos
Objetivo
Este manual descreve o fluxo de importação de usuários externos no ServerApp usando pacote ZIP com três arquivos CSV:
- users.csv
- roles.csv
- user_roles.csv
O fluxo operacional possui três ações:
- Simular (Dry-run): valida o pacote e calcula o plano sem gravar no banco.
- Aplicar (Apply): executa criação/atualização em transação.
- Rollback último apply: tenta desfazer o último lote aplicado pendente por provider.
Escopo da sincronização (regra atual)
Comportamento atual é aditivo/atualização:
- usuários do arquivo: cria ou atualiza
- roles do arquivo: cria ou atualiza
- vínculos user-role do arquivo: adiciona se faltar
Não é feito nesta versão:
- remoção de vínculos não presentes no arquivo
- inativação/remoção de usuários ausentes no arquivo
- inativação/remoção de roles ausentes no arquivo
Fluxo de uso no sistema (UI)
- Abrir menu Configurações > Serviços > Importação de Usuários e Perfis Externos.
- Informar o provider externo do lote.
- Selecionar o arquivo ZIP.
- Executar Simular (Dry-run).
- Se não houver erros impeditivos, executar Aplicar.
- Se necessário, executar Rollback último apply para o mesmo provider.
Exibição dos resultados na tela
Após execução de simulação/aplicação/rollback, a área de resultado usa abas:
- Aba Resultado: mostra contadores consolidados da operação.
- Aba Ocorrências: mostra grid com Severity, Code, File, Row, Message.
O botão Exportar ocorrências (CSV) permanece na área de ocorrências e exporta exatamente os itens exibidos para a operação atual.
Pacote para processamento
Para executar a importação os arquivos com os dados dos usuários deverão ser empacotados em um arquivo ZIP.
Estrutura do pacote ZIP
O ZIP deve conter os arquivos:
- users.csv
- roles.csv
- user_roles.csv
Se faltar algum deles, a simulação retorna erro.
Formato dos CSVs
O parser aceita aliases de cabeçalho (case-insensitive, ignorando _, - e espaço), mas recomenda-se usar nomes canônicos.
users.csv
Colunas recomendadas:
- externalUserId (obrigatória)
- userName (obrigatória)
- email (opcional)
- userFullName (obrigatória)
- canCreateReport (opcional, default true)
externalUserId,userName,email,userFullName,canCreateReport
ext-001,maria.silva,maria@cliente.com,Maria Silva,true
ext-002,joao.souza,joao@cliente.com,João Souza,false
camCreateReport determina se o usuário ou usuários de um perfil poderão gerar novos relatórios.
roles.csv
Colunas recomendadas:
- roleName (obrigatória)
- canCreateReport (opcional, default true)
roleName,canCreateReport
Operador,true
Supervisor,false
user_roles.csv
Colunas recomendadas:
- externalUserId (obrigatória)
- roleName (obrigatória)
externalUserId,roleName
ext-001,Operador
ext-002,Supervisor
Valores booleanos aceitos
Para canCreateReport:
- Verdadeiro: true, 1, yes, y, sim, s
- Falso: false, 0, no, n, nao, não
Campo vazio usa padrão true.
Tabela — checagens da Simulação (Dry-run)
|
Categoria |
O que é validado |
Código(s) de ocorrência |
|
Entrada básica |
Provider externo obrigatório |
invalid-provider |
|
Entrada básica |
ZIP ausente/ilegível |
invalid-file |
|
Estrutura ZIP |
users.csv obrigatório |
missing-users-csv |
|
Estrutura ZIP |
roles.csv obrigatório |
missing-roles-csv |
|
Estrutura ZIP |
user_roles.csv obrigatório |
missing-user-roles-csv |
|
Cabeçalho/colunas users |
Header/colunas obrigatórias (externalUserId, userName, userFullName) |
users-header-missing, users-column-missing |
|
Linhas users |
externalUserId vazio/duplicado |
users-externalid-empty, users-externalid-duplicate |
|
Linhas users |
userName vazio |
users-username-empty |
|
Linhas users |
userFullName vazio |
users-fullname-empty |
|
Linhas users |
canCreateReport inválido |
users-cancreate-invalid |
|
Cabeçalho/colunas roles |
Header/coluna obrigatória (roleName) |
roles-header-missing, roles-column-missing |
|
Linhas roles |
roleName vazio/duplicado |
roles-name-empty, roles-name-duplicate |
|
Linhas roles |
canCreateReport inválido |
roles-cancreate-invalid |
|
Cabeçalho/colunas user_roles |
Header/colunas obrigatórias (externalUserId, roleName) |
userroles-header-missing, userroles-column-missing |
|
Linhas user_roles |
externalUserId/roleName vazios |
userroles-values-empty |
|
Linhas user_roles |
par externalUserId/roleName duplicado no arquivo |
userroles-pair-duplicate |
|
Consistência entre arquivos |
vínculo referencia usuário inexistente em users.csv |
user-role-user-missing |
|
Consistência entre arquivos |
vínculo referencia role inexistente em roles.csv/Identity |
user-role-role-missing |
Tabela — o que o Apply faz (inserção/update)
|
Entidade |
Condição |
Ação no Apply |
Código de erro em falha |
|
Role |
role não existe |
INSERT role |
role-create-failed |
|
Role |
role existe e canCreateReport mudou |
UPDATE role |
role-update-failed |
|
Role |
role existe sem mudança |
ignora (sem update) |
— |
|
Usuário externo |
não existe por (ExternalProvider, ExternalUserId) |
INSERT user (senha aleatória técnica) |
user-create-failed |
|
Usuário externo |
existe e dados diferem (userName, email, fullName, canCreateReport, provider/externalId) |
UPDATE user |
user-update-failed |
|
Usuário externo |
existe sem mudança |
ignora (sem update) |
— |
|
User-role |
vínculo já existe |
ignora (sem inserção) |
— |
|
User-role |
vínculo não existe |
INSERT em associação de role |
user-role-add-failed |
|
Pós-validação apply |
usuário/role esperados não encontrados após etapa anterior |
marca erro e mantém transação sem commit |
user-role-user-not-found, user-role-role-not-found |
|
Erro inesperado |
exceção não tratada durante apply |
rollback da transação |
apply-exception |
Tabela — comportamento do Rollback por condição
|
Operação original |
O que o rollback tenta fazer |
Quando reverte |
Quando não reverte |
|
UserCreate |
remover usuário criado no lote |
quando usuário ainda existe e identidade do snapshot bate (ExternalProvider + ExternalUserId) |
usuário já removido; identidade divergente; bloqueio por integridade referencial (ex.: dependências de negócio como relatório vinculado) |
|
UserUpdate |
restaurar estado anterior do usuário |
quando usuário existe, snapshot before existe e não há drift impeditivo no alvo |
usuário não encontrado; snapshot ausente; falha de update; drift impeditivo |
|
RoleCreate |
remover role criada no lote |
quando role existe e validações de segurança permitem remover |
role já removida; drift impeditivo; falha ao remover |
|
RoleUpdate |
restaurar estado anterior da role |
quando role existe e snapshot before está íntegro |
role não encontrada; snapshot ausente; drift impeditivo; falha ao atualizar |
|
UserRoleAdd |
remover vínculo usuário-role adicionado no lote |
quando usuário/role existem e vínculo está presente |
usuário/role ausentes; vínculo já não existe; falha ao remover |
Observações importantes sobre rollback
- O rollback atua sobre o último lote apply pendente por provider.
- Lote já marcado como rollback não é reprocessado.
- Se houver dependências externas ao escopo de segurança (ex.: entidades de negócio referenciando usuário), a remoção pode ser bloqueada pelo banco.
- Ocorrências do rollback também são listadas na aba Ocorrências e podem ser exportadas em CSV.
Boas práticas operacionais
- Sempre executar dry-run antes de apply.
- Corrigir ocorrências do dry-run antes de gravar.
- Versionar os ZIPs processados em produção para auditoria.
- Processar lotes menores em primeira carga.
- Confirmar provider correto antes de aplicar/rollback.
Códigos de erro/ocorrência mais comuns
- Estrutura/validação: invalid-provider, invalid-file, missing-users-csv, missing-roles-csv, missing-user-roles-csv
- CSV users: users-header-missing, users-column-missing, users-externalid-empty, users-externalid-duplicate, users-username-empty, users-fullname-empty, users-cancreate-invalid
- CSV roles: roles-header-missing, roles-column-missing, roles-name-empty, roles-name-duplicate, roles-cancreate-invalid
- CSV user_roles: userroles-header-missing, userroles-column-missing, userroles-values-empty, userroles-pair-duplicate, user-role-user-missing, user-role-role-missing
- Apply: role-create-failed, role-update-failed, user-create-failed, user-update-failed, user-role-user-not-found, user-role-role-not-found, user-role-add-failed, apply-exception