# Data Connectors

Load spreadsheets and read databases, APIs and shop-floor PCs on a schedule, so reports and dashboards use the same up-to-date tables.

When the numbers you report on live in a spreadsheet someone emails each morning, or in another system such as your ERP or time clock, every report starts with copying and pasting. Data Connectors is your workspace's data pipeline for reporting: it brings that data in, keeps it current, and publishes it as datasets for dashboards, reports and Claude. At Acme Precision, the shift leads' daily goals spreadsheet is uploaded to Data Connectors, and labor is read from the shop's database every few minutes, so every dashboard reads the same tables.

[Add it from the Marketplace](/tenant/?open=settings/marketplace)

## What it does

Each **data source** fills one or more **tables**. Data comes in three ways:

- **Spreadsheets (CSV or Excel)**: upload a file and every sheet becomes a table. Upload a newer copy to the same source and rows with the same key are updated and new ones added. Nothing is written until the file has been checked.
- **Connections to your other systems**, read on a schedule and read-only:
  - **Database through the Bridge**: SQL Server, PostgreSQL, MySQL, Oracle, Actian Zen / Pervasive, Access or any database with an ODBC driver that your network reaches. The Bridge Harness on one of your PCs runs the queries, and the database login stays on that PC.
  - **REST API**: a web service that answers JSON, such as a time clock, CRM or online ERP.
  - **Bridge connector on a PC**: a program on a shop-floor PC, such as a machine or PLC reader.
  - **Sample data**: a made-up machine shop for trying everything before a real connection exists.
- **A file from a folder on your PC**: the module's assistant fetches a spreadsheet from a folder you share through the Bridge Harness and imports it like an upload.

A table can then be **published** as a dataset for the report and dashboard builders and Claude, and a sensitive table can be **restricted**.

The module adds these pages under **Data Connectors** in the sidebar:

- **Overview**: tiles for **Sources**, **Tables**, **Rows**, **Tables in reports** and **Last answer from a connection**, then **Connections** with each one's status and last success, and the **Data sources** list with each source's rows, **Last loaded** and **Status**. When there is something to show, it adds **Recent file imports**, the **Labor — last 7 days by work center** summary and **Recent syncs**.
- **Data sources**: every source, with **Add data source**. Open a file source to see its **Upload a file**, **Tables** and **Imports** tabs. Open a table to see its **Data**, **Fields** and **Publish** tabs.
- **Data Map**: every table and how the tables relate, with **Discover tables** and the **Dictionary**.

Connections, the Bridge connector, the API slots, sources read through a connection, the labor mapping and **Query** are in **Module Settings › Configuration**.

## Set it up

A Workspace Admin does this first.

1. Give the permissions to your own roles. Most people only need **Read data**; keep **Read restricted data** to a small group. See [Users and roles: create and edit roles](article:88d4e232-d5b8-4909-b452-cfe96d3d550f).
2. Open **Module Settings** from the ⋮ on the **Data Connectors** sidebar row, then **Configuration**. Under **General**, check the scheduled sync, the shift start times and labor type codes, and whether **AI Assist ticked by default on file uploads** stays on. AI Assist uses your workspace's own AI. See [Module settings and versions](article:fb7c92e4-6dcc-4ef4-80bc-1b6e7482e540).
3. For spreadsheets, add one file data source for each kind of file you receive, and upload the first copy (below).
4. For another system, add a connection, test it, run **Discover tables** for a database, and add a source for each table or endpoint you report on (below).
5. Publish each table people should report on, and restrict the sensitive ones.

## Add a spreadsheet data source

1. Open **Data sources** and click **Add data source**.
2. Under **Connector**, choose **File (CSV or Excel)**.
3. Type a **Name**, such as *Daily shift goals*. The **Code** fills itself in. It names the source's tables and can't be changed later.
4. Add a **Description** of what the file holds and who sends it, if it helps.
5. Click **Create source**. The source opens on **Upload a file**.

Choosing **A connected system** here explains that those sources are added from **Module Settings › Configuration** or the **Data Map**.

## Upload a spreadsheet and map it to tables

1. Open **Data sources**, click the source, and open **Upload a file**.
2. Leave **AI Assist** ticked if you want it to suggest table names, field names, types and keys.
3. Drop the file on **Drop a CSV or Excel file here**, or click **choose a file**.
4. On each sheet's card, untick sheets you don't want (notes, instructions, pivots), and set **Table**: keep **New table** and edit **New table name**, or pick an existing table.
5. For each column, set **Import**, **Field name** and **Type** (**Text**, **Number**, **Date**, **Date and time** or **Yes / no**). Tick **Key** on the column or columns that identify one row, such as work center, date and shift.
6. Choose **When rows are imported**: **Add and update by key**, **Add as new rows**, or **Replace all rows**.
7. Click **Check the file**.

A newer copy of the same file reuses last time's mapping; only columns marked **new column** need a look.

## Fix problems and import

1. Read the list under **Check**. Each line gives the sheet, the row number as Excel shows it, the column and the value: a value of the wrong type, an empty key, or a key used twice.
2. Click **Explain with AI Assist** for a plain-language summary of what to change in the spreadsheet.
3. Click **Download the file with problems marked** for an Excel copy with the bad cells in red and an **Issues** sheet.
4. Fix the spreadsheet and click **Upload a fixed file**, or click **Import and skip N rows** to import the rest now.
5. After a clean check, click **Import N rows**. Large files import in steps.

The source then opens on **Tables** with the new row counts, and **Imports** lists the file with rows added, updated and skipped.

## Bring in a spreadsheet from a folder on your PC

1. On your PC, share the folder through the Bridge Harness: on the **Shared folders** connector, click **Add a shared folder**. **View only** is enough. See [Bridge connectors](article:241e9db8-1d01-4885-a349-ec8627b73712).
2. Open the module's chat and ask, for example: "Bring in Daily Output.xlsx from my Reports folder into the Daily shift goals source."
3. Check the mapping it proposes, then ask it to check and import the file, or open the import on **Data sources**.

The assistant reaches only folders you shared yourself, while your PC is on and you are signed in.

## Browse a table

1. Open **Data sources**, click the source, then **Tables**, and click a table.
2. On **Data**, search and page with **‹ ›**. For a spreadsheet, **_source_row** is the row in the file each row came from.
3. Open **Fields** to see each field's name and type.
4. A file source's **Imports** tab lists every file. Administrators can **Download the original file**.

## Publish a table for reports and dashboards

1. Open the table and click the **Publish** tab.
2. Tick **Group by** on the text, date and code fields people should group or filter by.
3. For numbers, choose **Add up as**: **Total**, **Average**, **Lowest**, **Highest** or **Count distinct**.
4. Choose **Who can use it**.
5. Click **Publish** (or **Update dataset**). **Stop publishing** removes the dataset.

The dataset then appears in the dashboard and report builders. See [Dashboard](article:1d8a33a4-3a13-4874-b8e5-5ef9da22df95).

## Restrict a sensitive table

1. Open the table and click **Fields**.
2. Set **Who can see it** to **Restricted (Read restricted data)**.
3. Click **Save**.

The table, its rows and its dataset are then hidden from everyone without **Read restricted data**, in every page, report, dashboard and Claude. The rest of the same source is held back too.

## Add a connection

1. Open **Module Settings › Configuration › Connections** and click **Add connection**.
2. Choose the **Kind**: **Database through the Bridge (ODBC)**, **REST API**, **Bridge connector on a PC** or **Sample data**.
3. Type a **Code** (for example *shop_database*) and a **Name**, then fill in the kind's own fields.
4. Click **Save**, then **Test**.

**Test** says what the connection sees, for example "Connected. 6 tables and 0 views visible", or why it can't reach it.

## Connect a database through the Bridge

1. On a PC that reaches the database, install the database's ODBC driver and create a data source (DSN) in Windows' **ODBC Data Sources (64-bit)**, with a **read-only** login. Note its name, for example *SHOP_DB*.
2. Install the Bridge Harness on that PC, issue the **ODBC connector** to the person signed in there, and have them sign in on the harness. See [Bridges](article:cb384d28-568f-4aee-a61f-59a5f8ef5a5f).
3. In **Configuration › Connections**, the **Bridge connector** card lists the PC under **Connectors that reported to this workspace**. Check the PC name and person, then click **Trust**.
4. Click **Add connection**, choose **Database through the Bridge (ODBC)**, type the **ODBC data source (DSN)** and choose the **Database type**: SQL Server, PostgreSQL, MySQL / MariaDB, Oracle, Actian Zen / Pervasive, Microsoft Access, or Other.
5. Click **Save**, then **Test**.

The card then shows the PC **online**, and the connection says the DSN is set up on that PC. Only the trusted PC is given queries, and one trusted PC serves every database connection, so put each connection's DSN on it.

## Connect a REST API

1. In **Configuration › API slots**, type the API's base address in a free slot (for example *https://api.example.com/v2/*) and its key or token. The key is stored and never shown again. Use a read-only key.
2. Click **Save**, and tell Data Visions support you added an API address: support opens your workspace's network to it.
3. Click **Add connection**, choose **REST API**, choose the **API slot** and how it signs in (**Bearer token**, **API key in a header**, **API key in the address**, or **User name and password**).
4. Click **Save**, then **Test**.

## Discover a database's tables and check access

1. Open **Data Map** and click **Discover tables**. With more than one connection, choose which. If it pauses, click it again.
2. Choose **All tables**, or type in **Find a table or column…**. A table outside the database's default schema shows as *schema.table*, such as *erp.labor_entries*.
3. Drag and zoom, and use **Fit** or **Auto-layout**. Dashed lines are suggested links; solid lines are confirmed.
4. To compare with a data dictionary, click **Dictionary**, then **Import dictionary…** (or **Replace dictionary…**), and choose the views and column definitions file. It lists each table with your company's decision: **Request**, **Optional**, **Review**, **Exclude** or **Not needed**.
5. Read **Compared with the connected source**. **Marked Exclude but visible** lists tables the connection's login shouldn't reach; **Requested but not found** lists tables still to be granted.

## Bring a table in on a schedule

1. On **Data Map**, click the table, then the **New source** tab. Choose **How to sync** and the **Key columns**. For day-by-day, also choose the **Date column** and **Back-fill from**. Click **Create and sync**.
2. Or open **Module Settings › Configuration › Sources** and click **New**. Choose the **Connection**, fill **Code** and **Name**, and choose the **Mode** (**Full**, **Daily** or **Custom SELECT**, which is for databases only). For a database, fill the **Table**, **Columns**, **Extra filter** and **Key columns**; for an API, the **Endpoint**, where the rows are in the answer and how it pages; for a Bridge connector, the **Target**. Set **Every (minutes)** and click **Create**.

The source appears on **Overview** with its row count, and fills a table you can publish.

To control a source in **Sources**: **Sync now** pulls it straight away, **Test (20 live rows)** shows live rows without storing them, clearing **Enabled** and clicking **Save** pauses it, **Start over** reloads it from the beginning, and **Delete** removes only the copy in your workspace. To pause every source of one connection, edit the connection and clear **Enabled**. On **Overview**, **Sync due sources** syncs every source that is due. To pause everything, clear **Scheduled sync** under **General** and click **Save**.

## Map labor

1. Open **Module Settings › Configuration › Labor mapping**.
2. Choose the **Labor source**.
3. Pick the source's column for each standard field: date, shift, work center, employee, job, operation, part, pieces good and scrap, hours, standard hours and labor type. Leave shift empty to work it out from **Shift start times**.
4. If the source has a labor type code, check **Labor type codes** under **General**: which code means run, setup or indirect.
5. Check **How the first rows map**.
6. Click **Save mapping and rebuild**.

The **Overview** labor summary, the **Labor** dataset and the labor reports then use these fields. Labor performance is standard hours ÷ hours worked × 100.

## Confirm links between tables

1. Click a table on **Data Map** and open **Relationships**.
2. Click **confirm** or **reject** on a suggested link.
3. To add one, under **Add a relationship**, fill **Column in** this table, **Related table** and **Column there**, and click **Add**.

Reports use confirmed links to show names instead of numbers.

## Look at a database live

1. On **Data Map**, click a table and click **Preview 50 rows live**, or **Read columns from one row** on **Columns**.
2. Or open **Module Settings › Configuration › Query**, choose the **Connection**, type one SELECT in that database's own SQL and click **Run**.

Nothing is stored. Anything other than a single SELECT is refused before it is sent. This needs **Run live queries**.

## Who can do what

Each action in the module needs a permission. A Workspace Admin gives permissions to roles; see [Users and roles: create and edit roles](article:88d4e232-d5b8-4909-b452-cfe96d3d550f). **Out of the box** shows the module's starting roles that have it.

| Permission | What it lets someone do | Out of the box |
|---|---|---|
| **View connected data** | See connections, data sources, tables and rows, the Data Map, import and sync history, the dictionary, and use datasets published for everyone. | Admin, Operator, Viewer |
| **View restricted data** | See tables and datasets an administrator marked restricted, such as cost, pay or customer data. | Admin |
| **Manage data sources** | Add and change connections and data sources, trust the Bridge connector, upload and import files, map, publish and restrict tables, sync, labor mapping, relationships, dictionary import, and download original files. | Admin |
| **Query a connected database directly** | Preview database tables live and send a read-only query straight to a connected database, reaching any table its login can read. **Give with care.** | Admin |

## Ask its agent

The **Data Connectors Assistant** works with the module in its chat, within your own permissions. Try:

- "Add a file source for our daily shift goals."
- "Are my connections working?"
- "Bring in Daily Output.xlsx from my shared Reports folder."
- "Publish the shift goals table with pieces good and scrap as totals."

See [Agent chat](article:073c6465-d85c-4364-8768-acf42a3a6a48).

## Good to know

- Files can be up to 50 MB, in .csv or .xlsx. Save old .xls files as .xlsx first. A sheet can have up to 400 columns and 500,000 rows.
- An import never deletes rows, except with **Replace all rows**. To undo one, upload the earlier file with **Replace all rows**.
- AI Assist sees the column headings, a few sample values and up to 40 problem examples, never the whole file. It uses your workspace's own AI.
- Connections only read. Nothing is ever written back to your other systems.
- Each connection has its own pace (requests per minute). If a system asks to slow down, only that connection's sources pause.
- Pages, reports and dashboards read your workspace's copy, not the other system.
- There is no button to delete a file data source.

## More help

Open the module's **Help** for the full reference: how-tos, every field, permissions, questions and problems, and what's new. See [Find and follow a runbook](article:4b62ad1f-577a-4998-8bce-f00226376522) for how runbooks work in modules that have them.


Source: https://datavisions.ai/docs/module-guides/data-connectors
