Connectors

Before you start

Connectors need the Silver tier or above. A tier is a ratchet on what you have already spent rather than a plan you buy, so Silver arrives on its own once your lifetime spend reaches it — see tiers and limits.

You will also need administrator access to the other system: a Google Cloud project where you can create a service account, or a Microsoft Entra tenant where you can register an application and grant it consent. This is the part worth checking before you begin, because it is usually somebody else’s permission to give.

The account belongs to you, not to us. You create it in your own Google or Microsoft tenant, you decide which single folder or site it can read, and you can revoke it at your end at any time without asking us. We never write to your Drive — read access is all a connector ever needs, and all it ever asks for.

Registering the account

Connectors are registered once for the whole organisation, under Settings → Connectors, and that needs to be an organisation owner or admin. Registering introduces a long-lived credential to a system we do not run, which is why it sits with the people who answer for the organisation rather than with each workspace. See team and roles.

Add a connector and you are asked for the service you are connecting and the key that proves it. What you paste is stored encrypted, is never sent back to a browser, and is bound to your organisation — a copy of it lifted into another organisation cannot be decrypted there.

An organisation may hold up to ten registered accounts. That is a bound so nothing is unbounded rather than a tier benefit; no rung of the ladder buys more.

Google Drive

Register a service account key and Ragextract shows you the account’s address. Create or find the Drive folder you want read, and in its sharing options add that address as a Viewer. Viewer is enough.

Enable the Drive API on the Google Cloud project first. It is off by default on a new project, and this is the single most common reason a first sync fails. The symptom is misleading: the account signs in perfectly and then sees nothing at all, which reads like a fault at our end.

Microsoft 365

Register an application in Entra and give it the Sites.Selected application permission, with admin consent. Then — and this is the step that gets missed — grant that application id Read on the site itself. There is no portal screen for it; it is done with Graph Explorer or PnP PowerShell.

Without that second grant the connector authenticates and can see nothing, exactly as an unenabled Drive API does. Because the permission names one site, a Microsoft account corresponds to one site: connecting a second site means registering a second account.

Microsoft client secrets expire. Entra caps them at two years, so a connector that has run untouched for months will one day stop because the secret behind it lapsed. Google service account keys do not expire, so this is a diary entry you only need for Microsoft.

Choosing the folder and the tables

A registered account imports nothing until it is pointed at something. That happens in workspace settings → Connectors, and needs Manage on that workspace rather than an organisation role — choosing a folder spends that workspace’s credits into that workspace’s tables, and the people who run a workspace are the right people to decide it.

You pick the folder from what the account can actually see, rather than pasting an identifier. If a folder is not in the list, it has not been shared with the account yet.

Then you name the tables it feeds. One connector can feed several, and All tables is a rule rather than a snapshot: a table created next month is covered without anyone reopening the dialog. A table already fed by another connector cannot be chosen, so a row always has one place it came from.

Choosing “All tables” means creating a table can spend credits. A new table in that workspace is backfilled with everything the connector already holds, so the new-table dialog tells you what that will cost before you agree to it — in a flow that otherwise has nothing to do with connectors.

What a sync makes

A connector reads one level down. Each subfolder becomes a bundle named after it, and that bundle becomes one row on every table the connector feeds. Documents sitting loose in the top folder are read too.

A bundle holds at most fifteen documents. A subfolder with more than that is still synced — it is not skipped and it is not split — and it is marked truncated so you can see that the folder is larger than the row behind it. Which fifteen is decided by name, so it is the same fifteen every time rather than whatever order the provider happened to answer in.

Documents are copied into the workspace, not linked. Deleting the folder at your end does not empty your tables, and what we hold is governed by our own retention rather than by your Drive.

What syncs, and what does not

New files are imported. That is the whole of what a sync acts on, and the restraint is deliberate.

An edited file is reported, not re-read. If someone changes a document in the folder, the run log names it and the row keeps the version we copied. Re-reading on every save would spend credits on every save, and a document people are actively editing would cost more than one nobody touches.

A deleted file is reported, not deleted. Your row stays. Removing a customer’s work because somebody tidied a shared folder is not a trade we are willing to make on your behalf.

You will see an Updated files overwrite option in a connector’s settings, switched off and not selectable. It is the answer to “my file changed and the row did not”, and it is not available yet. It is shown rather than hidden so the question has a visible answer.

When it runs

With Automatic sync on, a connector is checked about every fifteen minutes. That is the answer to how long a document may sit in a folder before it is a row, and it is a deliberate floor rather than a technical limit — nothing in a document pipeline is improved by checking every thirty seconds.

With it off, nothing runs until you press Sync. The two controls are separate: switching automatic sync off does not disable the connector, it just stops it running on its own.

Every run is recorded, whether anyone was watching or not, with what it added and what it noticed upstream. A sync that finds nothing new says so — that is the healthy state a connector spends most of its life in.

What it costs

The same as any other document. Reading a page costs one credit and answering a cell costs what that column costs; a connector changes how documents arrive, never their price. See how credits work.

A document is read once, however many tables the connector feeds. The expensive half — reading and indexing the pages — happens a single time and every table shares it. What multiplies is rows: a folder producing seven rows across three tables is twenty-one rows, and each one runs its own table’s columns. The confirmation before a sync says both numbers for that reason.

Set a monthly spend cap before connecting a large folder. A connector spends credits while nobody is signed in, and a first sync is the moment a folder that has been filling up for a year arrives all at once. Every organisation has a default cap; it is worth knowing what yours is rather than discovering it.

If the organisation drops below Silver

Connectors stop syncing. Nothing is deleted — the connection stays registered, every document already imported stays in the workspace, and the rows built from them stay in their tables. New documents simply stop arriving until the organisation is back on Silver.

You can still see what you have configured, and you can still remove a connector: taking back a credential to your own Drive is never something we would hold behind a tier.

What it does not do

It does not write to your Drive or SharePoint site, ever, in any tier or configuration. It does not read anything outside the folder you shared. It does not go more than one level deep. It does not remove or rewrite rows when the source changes. And it is not a backup — it is a one-way import, and the copy it makes lives under our retention rather than yours.

See also mailhooks, the other way documents arrive without anyone signing in, and auto mode, which is what makes an arriving row extract itself.