Sincronização das entidades

Cada entidade escolhe quando os registros dela são lidos da origem. Você define isso em Quando sincronizar, ao criar ou editar a entidade (Dados › Entidades › a entidade › Editar).

Os três modos

Modo	O que faz	Quando usar
Agendada	Lê todos os registros da origem de tempos em tempos, na agenda do conector	O padrão. Bom para a maioria dos casos
Manual	Lê todos os registros só quando você pedir	Dados que mudam pouco, como os documentos de um contrato
Quando o usuário acessa	Lê só os registros de cada tenant ID, quando um usuário dele entra no portal	Origens grandes demais para copiar inteiras, ou que só respondem por cliente

Nas entidades Agendadas e Manuais, os botões Sincronizar e Sincronização completa da página da entidade buscam os dados na hora (veja incremental ou completa).

Quando o usuário acessa

Nesse modo, a entidade nunca copia a origem inteira. Quando um usuário do portal entra, a plataforma pede à origem só os registros do tenant ID dele, guarda e mostra. No workspace Aurora Educação, a entidade Mensalidade funciona assim: as mensalidades de cada responsável são lidas do sistema acadêmico quando ele abre o portal.

Para usar este modo, a entidade precisa:

• ler de um endpoint, tool ou tabela (não de uma consulta SQL);
• ter um ID do Titular;
• ter um filtro do sync com o Tenant ID do usuário — é ele que faz a origem devolver só os registros de quem entrou.

Escolha também a validade dos dados do tenant: por quanto tempo os registros lidos valem antes de serem lidos de novo (5 minutos, 15 minutos, 1 hora, 6 horas ou 24 horas; o padrão é 1 hora). Dentro da validade, o portal mostra o que já está guardado, sem chamar a origem. Depois dela, o portal mostra os registros guardados enquanto busca os novos.

Na página da entidade, os botões de sincronizar dão lugar ao aviso Sincroniza quando o cliente acessa, e aparece a aba Tenants. Ela lista cada tenant ID que já sincronizou, com os usuários do portal que têm esse tenant ID, o status (Na fila, Sincronizando, Sincronizado ou Com erro), os registros, o resultado da última leitura, a última sincronização e o último acesso. O menu de cada linha tem Sincronizar agora e Sincronização completa para aquele tenant.

Filtros do sync

Os filtros do sync dizem à origem o que mandar, para que a entidade guarde só os registros que interessam — por exemplo, só as faturas dos últimos 12 meses.

Eles ficam em Filtros do sync, na criação ou edição da entidade, e funcionam de um jeito diferente para cada tipo de conector:

Conector	Como o filtro vai para a origem
API	Como parâmetro em toda chamada: a API devolve só o que passa por ele
MCP	Como argumento da tool em toda chamada
Banco de dados	Como condição na leitura da tabela (todas precisam valer)

Para cada filtro, escolha o parâmetro, argumento ou coluna, o operador (quando a origem aceita mais de um: igual a, diferente de, maior que, contém, é um destes, está vazio…) e o valor. Em campos de data, o valor pode ser uma data fixa ou um número de dias atrás ou dias à frente, contado a partir de cada sincronização. Uma entidade aceita até 20 filtros.

O botão Tenant usa como valor o tenant ID do usuário que entrou no portal — só vale nas entidades que sincronizam quando o usuário acessa.

informação

Uma sincronização completa remove da entidade os registros que os filtros deixam de fora. A amostra de Buscar dados, na criação da entidade, não usa o filtro de Tenant.

Paginação

APIs costumam devolver os registros em páginas. Em Paginação do sync, a plataforma já vem com o que a spec declara, e você pode ajustar:

Opção	Como a sincronização lê
Sem paginação (uma chamada só)	Faz uma chamada e guarda o que voltar
Por número de página	Pede uma página atrás da outra até vir uma página menor que o tamanho pedido (ou vazia)
Por offset	Igual, avançando pelo offset
Por cursor	Segue o cursor que a resposta devolve até ele vir vazio

Para cada opção, informe o nome dos parâmetros (da página, do tamanho da página, do offset, do limite, do cursor) e o tamanho da página, até 1.000. No cursor, informe também o caminho do próximo cursor na resposta.

Nas entidades de banco de dados, a opção é Leitura do sync: quantas linhas por leitura a sincronização lê de cada vez (o padrão é 500).

Acompanhar

Na Visão geral da entidade, o quadro Sincronização mostra:

Item	O que mostra
Situação	Em dia, Na fila, Sincronizando, Com erro ou Nunca sincronizada
Registros	Quantos registros a entidade tem
Última sync e Última completa	Quando foram a última sincronização e a última completa
Última execução	Se foi completa ou incremental, e quantos registros foram lidos, novos, alterados, sem mudança e removidos

Quando a última sincronização falhou, a mensagem de erro aparece logo abaixo. A aba Logs da entidade mostra as chamadas que a sincronização fez ao conector — clique numa delas para ver o que foi enviado e o que voltou.

Se a leitura parou no limite de registros por execução, o quadro avisa: nesse caso, a remoção dos registros que sumiram da origem não rodou.