Entity sync
Each entity chooses when its records are read from the source. You set this in When to sync, when creating or editing the entity (Data › Entities › the entity › Edit).
The three modes
| Mode | What it does | When to use |
|---|---|---|
| Scheduled | Reads all the records from the source from time to time, on the connector's schedule | The default. Good for most cases |
| Manual | Reads all the records only when you ask | Data that rarely changes, such as the documents of a contract |
| When the user opens the portal | Reads only the records of each tenant ID, when a user of that tenant signs in to the portal | Sources too big to copy whole, or that only answer per customer |
In Scheduled and Manual entities, the Sync and Full sync buttons on the entity page fetch the data right away (see incremental or full).
When the user opens the portal
In this mode, the entity never copies the whole source. When a portal user signs in, the platform asks the source only for the records of their tenant ID, stores them and shows them. In the Aurora Educação workspace, the Mensalidade entity works this way: each guardian's tuition fees are read from the academic system when they open the portal.
To use this mode, the entity needs to:
- read from an endpoint, tool or table (not from an SQL query);
- have an Owner ID;
- have a sync filter with the user's Tenant ID — it is what makes the source return only the records of the person who signed in.
Also choose the tenant data validity: how long the records read are valid before being read again (5 minutes, 15 minutes, 1 hour, 6 hours or 24 hours; the default is 1 hour). Within the validity, the portal shows what is already stored, without calling the source. After it, the portal shows the stored records while it fetches the new ones.
On the entity page, the sync buttons give way to the notice Syncs when the customer opens the portal, and the Tenants tab appears. It lists each tenant ID that has already synced, with the portal users who have that tenant ID, the status (Queued, Syncing, Synced or Error), the records, the result of the last read, the last sync and the last access. The menu on each row has Sync now and Full sync for that tenant.
Sync filters
Sync filters tell the source what to send, so the entity stores only the records that matter — for example, only the invoices from the last 12 months.
They are in Sync filters, when creating or editing the entity, and work differently for each connector type:
| Connector | How the filter reaches the source |
|---|---|
| API | As a parameter on every call: the API returns only what passes it |
| MCP | As a tool argument on every call |
| Database | As a condition on the table read (all of them must hold) |
For each filter, choose the parameter, argument or column, the operator (when the source accepts more than one: equal to, different from, greater than, contains, is one of, is empty…) and the value. On date fields, the value can be a fixed date or a number of days ago or days ahead, counted from each sync. An entity accepts up to 20 filters.
The Tenant button uses as the value the tenant ID of the user who signed in to the portal — it only applies to entities that sync when the user opens the portal.
A full sync removes from the entity the records that the filters leave out. The sample from Fetch data, when creating the entity, doesn't use the Tenant filter.
Pagination
APIs usually return the records in pages. In Sync pagination, the platform already comes with what the spec declares, and you can adjust it:
| Option | How the sync reads |
|---|---|
| No pagination (a single call) | Makes one call and stores what comes back |
| By page number | Asks for one page after another until a page smaller than the requested size (or an empty one) comes back |
| By offset | Same, advancing by the offset |
| By cursor | Follows the cursor the response returns until it comes back empty |
For each option, enter the parameter names (page, page size, offset, limit, cursor) and the page size, up to 1,000. For the cursor, also enter the path of the next cursor in the response.
In database entities, the option is Sync read: how many rows per read the sync reads at a time (the default is 500).
Follow along
In the entity Overview, the Sync panel shows:
| Item | What it shows |
|---|---|
| Status | Up to date, Queued, Syncing, Error or Never synced |
| Records | How many records the entity has |
| Last sync and Last full sync | When the last sync and the last full sync happened |
| Last run | Whether it was full or incremental, and how many records were read, new, changed, unchanged and removed |
When the last sync failed, the error message appears right below. The entity Logs tab shows the calls the sync made to the connector — click one to see what was sent and what came back.
If the read stopped at the per-run record limit, the panel warns you: in that case, the removal of records that disappeared from the source didn't run.