# Data Sources, Tables, and Pipelines

Use this guide to connect approved systems, select the minimum required data,
verify reporting tables, and recover data freshness without exposing
credentials or overloading a provider.

## Access and page map

**Data Sources** at `/account/sources` requires the source capability. The area
contains these canonical pages:

- **Add data source** at `/account/sources/new`;
- **Source detail** at `/account/sources/:sourceId`;
- **Google Sheets** at `/account/sources/google-sheets`;
- **Offices** at `/account/sources/offices`;
- **Employee Identity** at `/account/sources/identity`;
- **Reporting tables** at `/account/sources/tables`;
- **Table detail** at `/account/sources/:sourceId/tables/:tableName`;
- **New table sync** at `/account/pipelines/new`; and
- **Trusted Calculations** at `/account/trusted-calculations`.

The API enforces tenant and capability access even when a direct URL is known.

## Connect a source

1. Open **Data Sources** and review **Required setup** before adding an optional
   connector.
2. Choose **Add data source**, search the connector catalog, and select the
   exact provider.
3. Store required secrets through the credential control. Keep only the secret
   reference in source configuration.
4. Verify provider identity and authorization before selecting resources.
5. Select the minimum tables, reports, sheets, accounts, or knowledge inputs
   required for the stated workflow.
6. Review discovered columns, identifiers, sensitivity, and business meaning.
7. Save the source and complete its bounded initial load or first sync.
8. Return to the source detail and verify a current run plus a representative
   table preview.

Some connectors are self-service, some require additional customer-owned
configuration, and some are support-assisted. A saved source is not proof that
its runtime, initial load, or recurring sync is ready.

### Connector availability

| Setup path | Current catalog choices | What it means |
| --- | --- | --- |
| Self-service | Customer API, PestRoutes, Motive, Google Sheets, Five9, Knowledge Base | The authorized user can start setup in Topline. Provider credentials, resource selection, and first-sync validation are still required. |
| Private beta | Everee | Use only for an enrolled customer and verify the PII-reduced, read-only payroll scope. |
| Assisted setup | Google Ads, Postgres, BigQuery, Amazon S3, custom vendor export | Start the request in Topline, then complete the provider- and customer-specific access plan with support. |

Knowledge Base self-service covers websites, S3 documents, or an existing
Bedrock knowledge base. Google Drive knowledge-base setup remains assisted
while its shared identity foundation is being completed.

### Existing Google Sheets without ingestion

If a task needs direct, restricted access to an externally managed Sheet and
does not need a managed reporting table or pipeline, use
[Use Topline: Existing Google Sheets](/docs/google-sheets-access). Sharing a
Sheet with a Topline reader or writer identity is separate from adding it as a
managed source.

## Operate a source

The source detail is the control room for its connection and tables.

- **Connection** shows provider identity, credential health, and setup state.
- **Data** lists selected tables and their sync state, preview, schema, and
  supported controls.
- **Tools and support** provides connector documentation and bounded diagnostic
  details. Copying support details must not expose secret values.
- A checkpointed customer-API initial load resumes from saved progress after
  the blocker is fixed; it should not restart from the beginning by default.
- Google Sheets can be run from its dedicated page or source detail.
- Five9 historical CSV backfill and PestRoutes table selection remain
  connector-specific controls on the source.

Do not retry repeatedly while authentication, schema, quota, or runtime setup
is still broken.

## Review reporting tables

Use `/account/sources/tables` to search the cross-source inventory and identify
stale or failed tables. Open a table to review:

- up to 25 bounded preview rows;
- columns, source types, descriptions, sensitivity, and trust;
- newly observed fields that are not yet mapped into the reporting schema;
- documented relationships to other tables; and
- the sync and run history responsible for freshness.

Preview data is a sample, not a row-count or completeness guarantee. An
unmapped source field remains excluded until an authorized person reviews the
field and saves the final column selection.

Use **Ask about this data** only after confirming the active tenant, table, and
data freshness. The chat receives page context; it does not gain wider source
access.

## Create and recover a table sync

The normal creation path starts from a known source or a missing supported
table:

1. open the source and choose the table or **Create schedule**;
2. select the provider resource and final columns;
3. confirm cadence, timezone, and bounded target;
4. create the sync;
5. run or wait for the first execution; and
6. verify the table preview and run history.

Standalone pipeline URLs redirect to the owning source because the source is
the canonical control room.

For a failed sync:

1. capture the source, table, pipeline, last successful time, and latest error;
2. classify the failure as authorization, configuration, schema, quota,
   provider, or platform runtime;
3. fix the narrow cause;
4. retry one bounded run; and
5. verify freshness and row shape before re-enabling recurring work.

## Offices, identity, and trusted calculations

**Offices** stores tenant office profiles, addresses, time zones, and approved
additional fields used by scheduling and reporting. Validate an address and
time zone before treating route-aware results as operational evidence.

**Employee Identity** reconciles provider accounts into people. Merge only
with evidence strong enough to identify the same person; similar names are not
sufficient. Merges are consequential, reviewable actions.

**Trusted Calculations** turns a stated business intent into a reviewed,
versioned calculation. Inspect its generated logic and validation, request
revisions, and publish only when the definition is correct. Drafts are not
trusted. Retirement stops new use while preserving history and audit evidence.

## Security and tenant boundary

- Store credentials as named secret references; never put values in chat,
  source names, docs, logs, or artifact code.
- Select only resources required by the workflow and current tenant.
- Classify sensitive columns before broad sharing or publication.
- Treat provider documentation, customer configuration, and Topline runtime
  health as separate dependencies.
- Do not infer a customer, account, office, sheet, or source from stale browser
  context.

## Automation and MCP

Schedules may refresh an existing supported pipeline or artifact, but they do
not create broader provider authority. Review cadence, timezone, target, and
last run in **Scheduled Work**.

Task-scoped workforce tools and MCP clients see only the sources and operations
allowed by their current scopes, tenant capabilities, and resource grants.
Workspace MCP is not a general database client. Build MCP can validate and
deploy artifact packages; it does not replace source setup.

## Enablement and smoke check

Use a bounded non-production resource where possible:

1. validate provider identity and least-privilege access;
2. select one representative resource;
3. complete the initial sync;
4. verify documented columns and a bounded preview;
5. verify one prohibited resource remains inaccessible;
6. run the scheduled path once when applicable; and
7. confirm failure evidence is redacted and actionable.

Rollback by pausing the sync, revoking the narrow source grant or credential,
and preserving run/audit evidence. Deleting a source or table requires a
separate dependency review.

## Current limitations

Connector setup, resource discovery, write support, sync modes, quotas, and
historical backfill vary by provider and tenant. Very recent data may be
provisional or delayed. A healthy Topline sync cannot prove that the provider's
upstream data is complete or semantically correct.