Syncing a connected source#

An automation connected to a source — a Google Sheet, a CSV at a URL or an API endpoint — does not own its rows. It mirrors them: the rows and the column list belong to the origin, and the automation reads them again on a schedule or when you ask.

Connected sources are available on paid plans.

A connected table is read-only#

In the Input dataset tab the chip says Remote · Google Sheet (or CSV URL, or API) with a padlock. The cells cannot be edited, rows cannot be added or deleted, and Import rows is not offered. You edit the data where it lives, and the next sync brings the change across. A row's Edit button reads View and opens it read-only.

What you can still do here:

• Rename a column and change its type — that is your view of the origin's data, and a sync keeps it. You cannot add or delete columns: the origin decides what columns there are.
• Move columns.
• Link templates, map them, filter them, and render — exactly as with a table you own.

To make the rows yours, use Import and detach.

The sync panel#

Above the table, a strip says where the data comes from and when it was last read: Remote · Google Sheet · docs.google.com/…/pub · Synced 2 hours ago. The address opens the origin in a new tab. On the right:

• the schedule,
• Sync now, which reads the origin immediately (Reading… while it works),
• Import and detach.

When a sync finishes, a message says what it did — "Source read — 3 new, 12 updated, 2 no longer in the source, 12 ready to render again." — or "Nothing has changed" when the source is exactly as it was the last time.

The schedule#

Scheduled reads are started every 15 minutes, so Every hour means within a quarter of an hour of the hour being up. Sync now ignores the schedule entirely and works on every schedule.

Scheduled syncing is a paid-plan feature. If the account moves to a plan without it, the schedule is set back to Only when I ask — the panel says Manual only — and Sync now keeps working, so the rows can still be refreshed.

What a sync does#

A sync reads the whole source again and compares it with the rows the automation already has:

• A row that is in both is updated in place. It keeps its identity, its render history and its video, and takes the new values. Values in columns the origin does not send are left alone.
• A new row is added.
• A row the origin no longer sends is kept, not deleted, and marked orphaned. It still holds the video it produced, and the Orphaned chip finds it. Deleting it would throw away the render state because someone tidied a spreadsheet.
• An orphaned row that comes back at the origin carries on as itself.

The table keeps the origin's order, with the orphaned rows gathered at the end.

A source whose contents are byte-for-byte what they were last time changes nothing, and costs nothing.

A row that changed renders again#

When a sync brings a new value for a row that already rendered, that row goes back to Not checked and is included in the template's next Render N. Its previous video is kept, and still plays until it expires. A row that is being rendered at that moment is not interrupted.

Without this, a row whose data moved on would never get a new video. See When a row renders again.

The key column#

The key column is how a sync decides which incoming line is which stored row. You choose it when you connect the source: a SKU, a product id, an email address — any field that is unique and does not change.

With a key column, editing a cell at the origin updates that row in place: same row, same history, a new video on the next render.

Without one, a row is recognised by a hash of all of its values. Change one cell at the origin and that row reads as one row deleted, one row added: the old row is kept as orphaned, and the new one starts from scratch — no history, rendered again as if it were new. The sync panel says so under the strip for as long as no key column is set.

Two more things only work with a key column:

• Taking single rows out of a template's filter by hand. Without one, a row's identity changes with its values, so an excluded row would come back as a new one. Rules still work. See Filters.
• Duplicates. If two incoming rows share the same key, only the first is kept, and the sync says how many were skipped: two rows cannot share one video's state.

When the origin's columns change#

Nothing is ever re-matched silently. On each sync, the incoming column names are compared with the ones already stored, by the origin's own name for them — which is why renaming a column here does not confuse the next sync.

When a column disappears, a warning above the table says so: "The source has stopped sending price. That column and its values are kept here, but any template variable fed by it cannot render until you map it to another column. It was most likely renamed at the origin."

Blocking is deliberate. Rendering 500 videos with an empty field because a spreadsheet column got renamed is worse than stopping and asking.

When a sync fails#

A failed sync never touches the rows: the table keeps the last rows that could be read. The failure is shown where you will see it without opening anything:

• In the automations list, the line is highlighted, its type chip turns red, and the Last batch column says "Sync failed — the URL returned 403".
• In the sync panel, "Sync failed — [reason]. The rows below are the last ones we could read. We will try again in 2 hours."

A source that keeps failing is tried less and less often rather than every hour forever: after each failure the wait before the next try doubles, up to once a day. The first successful read puts it back on its normal schedule. Sync now tries straight away whatever the wait.

The reasons you are most likely to see:

Import and detach#

Import and detach takes the rows as they stand right now and makes them yours:

• the cells unlock, and you can add and delete rows and columns and use Import rows;
• every row keeps its data and every video it has produced;
• rows marked as orphaned become ordinary rows again;
• nothing is ever read from the origin again.

It is one way. The dialog asks you to confirm — Yes, make it mine — and reconnecting later means creating a new automation. Use it when the sheet has done its job of getting the data in, and you want to work in JSON2Video from then on.

Next#

• Rendering videos
• Automations overview