Sincronização de pessoas

A sincronização de pessoas mantém a lista de pessoas da Eduvem igual ao cadastro de colaboradores da sua empresa. Em vez de cadastrar, atualizar e desativar pessoas uma a uma, você envia a lista completa de colaboradores - por um arquivo CSV ou, de forma automática, pelo sistema de RH via API de integração. A Eduvem compara a lista com quem já está na plataforma, mostra o que vai mudar e só aplica depois de uma aprovação.

Cada colaborador é identificado pelo externalId: o código que o seu sistema de RH já usa para essa pessoa (a matrícula funcional, por exemplo). É ele que liga, de um envio para o outro, a linha do arquivo à pessoa na plataforma.

Como ativar

O recurso vem desligado em todas as instituições. Para usá-lo, peça a ativação ao suporte da Eduvem. Na mesma solicitação você pode pedir ajustes nos limites de segurança, a aplicação automática pela API e o aviso de envio parado, descritos mais abaixo.

Com o recurso ativo, a entrada Sincronização de pessoas aparece no menu de Participantes para os administradores da instituição. Administradores de divisão e de sala não a veem: a sincronização trata da instituição inteira.

O arquivo

O arquivo é um CSV com uma linha de cabeçalho e uma linha por pessoa, em UTF-8. O separador pode ser ponto e vírgula, vírgula ou tabulação (ele é reconhecido pelo cabeçalho), e os nomes das colunas não diferenciam maiúsculas de minúsculas. Na tela, o ícone de planilha baixa um modelo com todas as colunas e uma linha de exemplo. O limite é de 50.000 linhas por envio.

Coluna	O que é	Como é tratada
`externalId`	Código do colaborador no seu sistema de RH, até 100 caracteres	Obrigatória em todas as linhas. Se o mesmo código aparece duas vezes no arquivo, as duas linhas são recusadas
`fullName`	Nome completo	Atualizado a cada envio; não pode vir vazio
`email`, `cpf`, `username`	E-mail, CPF e nome de usuário	Usados para criar a pessoa e para encontrar quem já está na plataforma. Numa pessoa que já existe, nunca são alterados: um valor diferente é apenas apontado no relatório
`division`	Nome da divisão	Atualizada a cada envio; precisa ser o nome de uma divisão ativa, e só vale para instituições que usam divisões
`state`, `city`, `custom1` a `custom12`	Estado, cidade e campos personalizados do cadastro	Atualizados a cada envio
`status`	Situação do colaborador	Opcional: `ativo` (ou `active`) e `desligado` (ou `terminated`)
`terminationDate`	Data de desligamento	Opcional, no formato `AAAA-MM-DD`

Em status, escreva exatamente um destes quatro valores; outras palavras, como “inativo” ou “demitido”, são recusadas como status inválido.

Algumas regras valem para todas as colunas atualizadas a cada envio:

Coluna ausente do arquivo: o campo fica como está na plataforma.
Célula vazia numa coluna presente: o campo é apagado.
Uma coluna com nome desconhecido recusa o arquivo inteiro. Colunas de senha (qualquer cabeçalho com “senha”, “pass”, “pwd” ou “secret”) também são recusadas: a sincronização nunca recebe senhas.
Para criar uma pessoa nova, a linha precisa trazer o nome completo e ao menos um entre e-mail, CPF ou nome de usuário.

Como uma linha encontra a pessoa

Cada linha é comparada com as pessoas da instituição nesta ordem: externalId, depois CPF (também quando o CPF é o nome de usuário da pessoa), depois e-mail, depois nome de usuário - sem diferenciar maiúsculas, minúsculas e acentos. No primeiro envio, quem já estava na plataforma é encontrado pelo CPF, e-mail ou usuário e passa a ficar vinculado ao externalId do arquivo.

A sincronização nunca troca o vínculo de uma pessoa por conta própria. A linha é recusada quando os identificadores dela apontam para pessoas diferentes, ou quando a pessoa encontrada já está vinculada a outro externalId.

Desligamentos

Uma linha com status igual a desligado desativa a pessoa quando a terminationDate está vazia, é hoje ou já passou. Com uma data futura, nada acontece por enquanto: a desativação vem no primeiro envio depois dessa data. Uma linha de desligamento que não encontra ninguém não cria ninguém.

A desativação por desligamento só alcança quem já está vinculado ao sistema de RH (tem um externalId). Uma pessoa encontrada apenas por CPF, e-mail ou usuário, ainda sem vínculo, é apontada como erro de linha e não é desativada.

Enviando um arquivo

Painel Nova sincronização, com as colunas do arquivo, o modelo para baixar, as opções Desativar quem não está no arquivo e Enviar convite aos novos e o botão Gerar prévia

Em Participantes > Sincronização de pessoas, no painel Nova sincronização, escolha o arquivo CSV.
Marque as opções que valem para este envio (as duas vêm desmarcadas):
- Desativar quem não está no arquivo - desativa as pessoas vinculadas ao sistema de RH que não aparecem no arquivo. Use apenas quando o arquivo for a lista completa de colaboradores.
- Enviar convite aos novos - envia o e-mail de cadastro às pessoas criadas que tenham e-mail.
Clique em Gerar prévia.

Em arquivos grandes, a prévia pode levar alguns minutos. Você pode sair da tela: ao voltar, a prévia está esperando. A instituição tem uma sincronização em andamento por vez. Enquanto uma prévia aguarda aprovação, Trocar arquivo volta ao painel de envio; ao gerar a prévia do novo arquivo, a anterior é cancelada.

A prévia

Prévia de um envio com duas pessoas novas: o arquivo enviado, as opções escolhidas e a tabela O que vai mudar

Nada é alterado até alguém aprovar. A prévia mostra:

O que vai mudar - quantas pessoas em cada tipo de alteração: Criar, Atualizar, Mudar de divisão, Reativar, Desativar, Sem alteração, Erros de linha (essas linhas não serão aplicadas) e Contas protegidas ignoradas.
Impacto para os participantes - os Convites a enviar, as Pessoas sem e-mail (criadas sem convite) e as Matrículas que seriam canceladas por mudança de grupo, com o número das que já têm certificado.
Erros de linha - as primeiras 20 linhas recusadas, com o número da linha, o identificador parcialmente oculto e o motivo em palavras simples.

Abaixo da prévia ficam os botões Baixar relatório por linha (CSV), Aprovar e aplicar e Cancelar. Uma prévia não aprovada expira em 24 horas.

Final da prévia, com o quadro Impacto para os participantes e os botões Baixar relatório por linha (CSV), Aprovar e aplicar e Cancelar

Depois de aprovada, a tela mostra o andamento (Aplicando alterações) - você pode sair, o processo continua - e, no fim, o resumo Sincronização aplicada: pessoas criadas, atualizadas, que mudaram de divisão, reativadas e desativadas, além dos erros de linha ignorados, das falhas ao aplicar e dos convites que falharam, quando houver.

Resumo Sincronização aplicada, com o estado Concluída e as contagens de pessoas criadas, atualizadas, que mudaram de divisão, reativadas e desativadas

O que cada alteração faz

Criar - cadastra a pessoa com os dados da linha. Quem tem e-mail é criado sem senha: o primeiro acesso é pelo convite (se a opção estava marcada) ou pelo fluxo Esqueci a senha. Quem não tem e-mail entra com o CPF ou o nome de usuário, seguindo as mesmas regras de senha inicial da criação por CPF e da criação por nome de usuário.
Atualizar - grava o nome, o estado, a cidade e os campos personalizados que mudaram.
Mudar de divisão - move a pessoa para a divisão indicada no arquivo.
Desativar - o acesso é pausado e o histórico é mantido: as matrículas ficam suspensas e as sessões abertas são encerradas. A sincronização nunca exclui nem anonimiza ninguém.
Reativar - devolve o acesso a quem a própria sincronização desativou e voltou a aparecer como ativo no arquivo, restaurando as matrículas que ela tinha suspendido. Uma pessoa desativada por um administrador ou por outro motivo não é reativada pela sincronização: a linha aparece como erro e a reativação é feita manualmente.

Contas protegidas nunca são alteradas: pessoas com qualquer papel administrativo na instituição, nas salas ou nas divisões, e as contas da equipe Eduvem. Elas aparecem na prévia como contas protegidas ignoradas.

Mudanças de cadastro também mexem nos grupos. Se a pessoa deixa de atender às regras de uma audiência associada a um grupo com a opção Somente pela audiência, ela sai do grupo e as matrículas que esse grupo tinha feito para ela são canceladas - é esse número que aparece em Matrículas que seriam canceladas por mudança de grupo. Com a sincronização ativa numa instituição que usa divisões, as audiências também podem ter uma regra pela divisão.

Limites de segurança

Três limites protegem a instituição contra um arquivo errado, como uma lista pela metade ou um arquivo de outra empresa. Eles contam as pessoas sincronizadas: as pessoas ativas, vinculadas ao sistema de RH e que não são contas protegidas.

Limite	Quando dispara (valores padrão)	O que acontece
Arquivo pequeno demais	Com Desativar quem não está no arquivo marcada, o arquivo encontra menos de 50% das pessoas sincronizadas	A sincronização é interrompida antes de alterar qualquer pessoa (estado Bloqueada pelo limite). Confira se o arquivo é a lista completa de colaboradores e use Enviar novo arquivo
Muitas desativações	O envio desativaria mais de 20% das pessoas sincronizadas, mais de 500 pessoas, todas elas, ou a instituição tem menos de 25 pessoas sincronizadas	A prévia aguarda uma pessoa. Para liberar Aprovar e aplicar, é preciso digitar o número exato de desativações
Cancelamento de matrículas	O envio cancelaria alguma matrícula que já tem certificado, ou mais de 100 matrículas	A prévia aguarda a aprovação de uma pessoa na tela

Quando mais de um limite dispara, vale o primeiro da tabela. Os valores podem ser ajustados para a sua instituição pelo suporte da Eduvem, mas nenhum limite pode ser desligado.

Aviso de muitas desativações na prévia, pedindo que se digite o número exato de desativações para liberar a aprovação

Histórico e relatório por linha

No fim da tela, Histórico de sincronizações abre a lista dos envios mais recentes, com as colunas Data, Origem (Arquivo CSV ou API), Estado, Criar, Atualizar, Desativar, Erros e Aprovado por. Em Aprovado por aparece o nome de quem aprovou, Automático (token) quando a API aplicou sozinha, ou via token seguido do início do código do token que aprovou.

Histórico de sincronizações com dois envios por arquivo CSV, com data, origem, estado, contagens e quem aprovou (nome substituído)

Os estados possíveis são: Na fila, Gerando prévia, Aguardando aprovação, Aplicando, Concluída, Falhou, Bloqueada pelo limite, Interrompida, Cancelada e Expirada.

O relatório por linha (CSV) traz, para cada linha, a ação planejada, o resultado e o motivo de cada erro, com o identificador da pessoa parcialmente oculto e apenas os nomes dos campos que mudaram - nunca os valores. Os dados pessoais do arquivo enviado são apagados da plataforma alguns dias depois do fim da sincronização.

Pela API de integração (sistemas de RH)

O seu sistema de RH pode enviar a lista de colaboradores sozinho, num agendamento, pela API de integração:

O token precisa da permissão Sincronização de pessoas. Ela só aparece na lista de permissões dos tokens enquanto a sincronização está ativa na instituição e nunca vem marcada por padrão.
O envio usa as mesmas colunas do arquivo, em JSON, com as mesmas opções (desativar quem não está no envio e enviar convites). A API também permite consultar uma sincronização, percorrer a lista de alterações e aprovar ou cancelar. Os detalhes estão na documentação da API.
Aplicação automática só acontece quando a sua instituição permite (o suporte da Eduvem ativa a pedido) e nenhum limite de segurança disparou. Nos demais casos, a sincronização enviada pela API aparece na tela como Aguardando aprovação, e uma pessoa aprova ali, como num envio por arquivo. O mesmo vale para aprovar pela API: um token só aprova o que a instituição deixaria ser aplicado automaticamente.

Aviso de envio parado

Se o envio automático do RH parar, quem saiu da empresa pode continuar com acesso. A pedido, a Eduvem envia um e-mail aos administradores da instituição quando nenhuma sincronização é concluída há um número de dias definido. O aviso sai uma vez por interrupção e volta a valer depois que uma nova sincronização é concluída. Instituições que nunca concluíram uma sincronização não recebem o aviso.

Relação com a desativação automática

Enquanto a sincronização está ativa, a desativação automática não alcança as pessoas vinculadas ao sistema de RH: a situação delas é definida pelos envios do RH. As demais pessoas continuam seguindo a regra da desativação automática.