Skip to content
footnote Docs
Install

Connectors

A connector reads a tool you already use, so metric names and documents arrive by themselves. It only reads: nothing is ever written back to the tool.

Where Footnote sits. Cube or dbt define the metrics and dimensions, and Footnote reads their names. Documents in Google Drive or Git become suggestions for their owners. Footnote holds context items, each with an owner and a check date, and the names, but no data rows. Agents ask over MCP and read what applies; people write, check and ask in the web app.Where Footnote sits. Cube or dbt define the metrics and dimensions, and Footnote reads their names. Documents in Google Drive or Git become suggestions for their owners. Footnote holds context items, each with an owner and a check date, and the names, but no data rows. Agents ask over MCP and read what applies; people write, check and ask in the web app.

Two kinds

KindWhat it readsWhat it may change
DefinitionsThe metrics and dimensions a tool definesIt flags the context that relies on a definition that changed or went
DocumentsFolders, spaces or pages you chooseIt makes at most one suggestion per document, for one domain’s owners to review

Neither kind publishes anything. Only an owner does that.

The connectors

ConnectorReadsHow often
CubeDefinitions, from Cube model filesEvery hour, 15 minutes at the shortest, out of date after 6 hours
Cube CloudDefinitions, from a Cube Cloud deployment’s metadataEvery hour, 15 minutes at the shortest, out of date after 6 hours
dbt MetricFlowDefinitions, from dbt’s built fileEvery hour, 15 minutes at the shortest, out of date after 6 hours
Static listDefinitions, from a list you pasteEvery hour, out of date after 6 hours
Markdown in GitDocuments, from a Git repositoryEvery day, 15 minutes at the shortest, out of date after 2 days
Google DriveDocuments, from Google Docs in foldersEvery day, 15 minutes at the shortest, out of date after 2 days

An admin can set each source’s own schedule, within those limits.

Connect one

Only admins connect a tool, in Settings, Integrations. The five steps are in Integrations:

  1. Pick the tool. The page says what it will hold and never hold.
  2. Connect it, and press Test connection, which must pass before you go on. It reads once and keeps nothing.
  3. Choose the views or folders to read.
  4. Map each to a domain. Every folder needs one, and a view may go without.
  5. Schedule it, and say why you are adding it.

Change settings goes through the same steps, filled in. A secret left empty keeps the one stored.

Whoever runs the service can also name a Cube model folder or another connector’s folder in its settings. Such a source is read only in the app: its settings are set on the server.

What a read does to definitions

What happenedWhat follows
A definition an item relies on changedThe item is Due for a check, and still reaches agents, marked as possibly out of date
A definition an item relies on wentThe same, naming the new definition if the tool renamed it
A definition an item only mentions changedThe item stays as it is, and its owners are told
A domain changed in the toolNothing is flagged. The owners are told, and the domain stays until an owner changes it
The read failedNothing changes, and the source’s page says why

Publishing a version written against the current definitions clears the flag.

A read that could not read everything keeps what it missed: only a complete read marks a definition as gone.

What counts as a change depends on what the tool gives. Cube model files and dbt give each calculation, so a changed calculation flags. Cube Cloud gives metadata only: a member’s type, how it adds up, its title, description and format. A changed calculation there flags nothing until one of those, or its meta, changes too.

A model that moves from Cube model files to Cube Cloud keeps its definitions, since both read them as the same ids. Disconnect the files source an admin added, and the next Cube Cloud read takes them over. It flags no item for the move and tells the owners once.

A files source set up on the server (CUBE_MODEL_DIR) cannot be disconnected, so its refs stay with it.

A member the files source had already marked missing takes the new mark as a change when it comes back, so the items on it are flagged.

A member Cube Cloud does not show, for example one the security context hides, stays with the disconnected source and is never marked missing.

What a read does to documents

For each new or changed document, a read makes one suggestion in the Inbox of the domain’s owners. They are told once per read, never once per suggestion.

  • Changed. A changed document replaces its open suggestion. One already published becomes a suggestion to change that item.
  • Declined. A suggestion an owner declined is not offered again until the document changes.
  • Gone. A document that left withdraws its open suggestion. An item it became is listed for its owners and stays as it is.
  • Skipped. A document with an email address, a phone number or what looks like a password or key is skipped. So is one that names no metric, market or other term, and one with no words.
  • Waiting. Past the source’s daily cap, a document waits and goes first next time.

A read that would remove more than half of a source’s documents at once, and more than five, keeps them all, so a broken folder never empties the Inbox.

Each document’s text lives in memory for one read. Only its link, title, change mark and a quote of at most 500 characters are kept. Who may read a document in the tool is not copied.

Watch a source

Settings, Integrations, lists every source with how it is:

StatusWhat it means
HealthyIts last read worked, or it has not been read yet
PausedAn admin paused it. The job leaves it out
Needs a new keyIts last read failed because its key was refused or is missing
FailedIts last read failed for another reason

Beside its status, a source that is waiting to be read says Queued: it was just added or changed, you asked for a read, or its time has come, and the job has not taken it yet. The job runs every five minutes. Reading means the job is reading it now. A failed read stays shown while its retry is queued.

Pausing a source also switches off its figures in Ask, whatever the Show figures in Ask switch says: an answer links into the tool instead. Its figures settings stay on its page, and an admin can still change them. What is published stays. Resume it and it is queued for a read.

Figures that are switched on also go off in Ask when the data contact leaves the workspace or the token is gone. The tool’s page says which, so you can name another contact or set the token again.

A source whose key was refused is not paused: it is tried again at its usual time, so a key fixed in the tool works again by itself. Until then Integrations says it needs a new key and when it was last tried, its page says when it is tried again, and both offer Replace key.

Read again reads one source at the job’s next turn, and a change to its settings does the same. To read the server’s own sources from the command line, the ones its settings name or the demo when they name none, run the command below. It never reads a source an admin added.

Terminal window
npm run connectors:sync

To read every source, an admin sends POST /api/v1/operations/jobs/connectors.sync/run.

The job looks for due sources as the service starts and every five minutes after, so a model folder the server was started on is read at once. After a failure that clears by itself, such as a timeout, a source tries again after one minute, then two, four and so on. It waits at most half of its out-of-date time, and never less than the tool asked.

Disconnect one

Disconnect ends a source an admin added: it reads no more and its secrets are removed. A document source’s open suggestions are withdrawn, and what owners published stays. A definitions source’s definitions stay as they were, so connecting the tool again reads it whole.

Build your own

A new connector needs no change to the app: see Build a connector. Connector security has the rules the service enforces on every connector.