Sincronización de las entidades
Cada entidad elige cuándo se leen sus registros del origen. Lo defines en Cuándo sincronizar, al crear o editar la entidad (Datos › Entidades › la entidad › Editar).
Los tres modos
| Modo | Qué hace | Cuándo usarlo |
|---|---|---|
| Programada | Lee todos los registros del origen cada cierto tiempo, en la programación del conector | El predeterminado. Bueno para la mayoría de los casos |
| Manual | Lee todos los registros solo cuando lo pides | Datos que cambian poco, como los documentos de un contrato |
| Cuando el usuario accede | Lee solo los registros de cada tenant ID, cuando un usuario suyo entra al portal | Orígenes demasiado grandes para copiarlos enteros, o que solo responden por cliente |
En las entidades Programadas y Manuales, los botones Sincronizar y Sincronización completa de la página de la entidad buscan los datos al instante (consulta incremental o completa).
Cuando el usuario accede
En este modo, la entidad nunca copia el origen entero. Cuando un usuario del portal entra, la plataforma le pide al origen solo los registros de su tenant ID, los guarda y los muestra. En el workspace Aurora Educação, la entidad Mensalidade funciona así: las mensualidades de cada responsable se leen del sistema académico cuando abre el portal.
Para usar este modo, la entidad necesita:
- leer de un endpoint, tool o tabla (no de una consulta SQL);
- tener un ID del titular;
- tener un filtro del sync con el Tenant ID del usuario — es el que hace que el origen devuelva solo los registros de quien entró.
Elige también la vigencia de los datos del tenant: por cuánto tiempo valen los registros leídos antes de leerse de nuevo (5 minutos, 15 minutos, 1 hora, 6 horas o 24 horas; el predeterminado es 1 hora). Dentro de la vigencia, el portal muestra lo que ya está guardado, sin llamar al origen. Después de ella, el portal muestra los registros guardados mientras busca los nuevos.
En la página de la entidad, los botones de sincronizar dan lugar al aviso Se sincroniza cuando el cliente accede, y aparece la pestaña Tenants. Lista cada tenant ID que ya sincronizó, con los usuarios del portal que tienen ese tenant ID, el estado (En cola, Sincronizando, Sincronizado o Con error), los registros, el resultado de la última lectura, la última sincronización y el último acceso. El menú de cada fila tiene Sincronizar ahora y Sincronización completa para ese tenant.
Filtros del sync
Los filtros del sync le dicen al origen qué enviar, para que la entidad guarde solo los registros que interesan — por ejemplo, solo las facturas de los últimos 12 meses.
Están en Filtros del sync, al crear o editar la entidad, y funcionan de forma distinta para cada tipo de conector:
| Conector | Cómo llega el filtro al origen |
|---|---|
| API | Como parámetro en cada llamada: la API devuelve solo lo que pasa por él |
| MCP | Como argumento de la tool en cada llamada |
| Base de datos | Como condición en la lectura de la tabla (todas deben cumplirse) |
Para cada filtro, elige el parámetro, argumento o columna, el operador (cuando el origen acepta más de uno: igual a, distinto de, mayor que, contiene, es uno de, está vacío…) y el valor. En los campos de fecha, el valor puede ser una fecha fija o un número de días atrás o días adelante, contado desde cada sincronización. Una entidad acepta hasta 20 filtros.
El botón Tenant usa como valor el tenant ID del usuario que entró al portal — solo vale en las entidades que sincronizan cuando el usuario accede.
Una sincronización completa quita de la entidad los registros que los filtros dejan fuera. La muestra de Buscar datos, al crear la entidad, no usa el filtro de Tenant.
Paginación
Las APIs suelen devolver los registros en páginas. En Paginación del sync, la plataforma ya viene con lo que declara la spec, y puedes ajustarlo:
| Opción | Cómo lee la sincronización |
|---|---|
| Sin paginación (una sola llamada) | Hace una llamada y guarda lo que vuelva |
| Por número de página | Pide una página tras otra hasta que venga una página menor que el tamaño pedido (o vacía) |
| Por offset | Igual, avanzando por el offset |
| Por cursor | Sigue el cursor que devuelve la respuesta hasta que venga vacío |
Para cada opción, informa el nombre de los parámetros (de la página, del tamaño de página, del offset, del límite, del cursor) y el tamaño de página, hasta 1.000. En el cursor, informa también la ruta del próximo cursor en la respuesta.
En las entidades de base de datos, la opción es Lectura del sync: cuántas filas por lectura lee la sincronización cada vez (el predeterminado es 500).
Seguimiento
En el Resumen de la entidad, el cuadro Sincronización muestra:
| Elemento | Qué muestra |
|---|---|
| Situación | Al día, En cola, Sincronizando, Con error o Nunca sincronizada |
| Registros | Cuántos registros tiene la entidad |
| Última sync y Última completa | Cuándo fueron la última sincronización y la última completa |
| Última ejecución | Si fue completa o incremental, y cuántos registros se leyeron, nuevos, modificados, sin cambios y eliminados |
Cuando la última sincronización falló, el mensaje de error aparece justo debajo. La pestaña Logs de la entidad muestra las llamadas que la sincronización hizo al conector — haz clic en una para ver qué se envió y qué volvió.
Si la lectura se detuvo en el límite de registros por ejecución, el cuadro avisa: en ese caso, la eliminación de los registros que desaparecieron del origen no se ejecutó.