Data sources

Reusable reference tables that lookup fields read — columns, rows, filters, CSV import, managed sync from a database or Salesforce, and bulk row management.

Updated 2026-09-03

A data source is a reusable table of reference data: a price list, a site list, an equipment registry, a parts catalog. Instead of hard-coding options into every form, you maintain the table once and point lookup fields at it. Update the table, and every form that reads it sees the change on the next sync.

Columns and rows

Each data source defines its columns up front. A column has a key, a label, and a type. A source you define by hand uses text, number, or boolean. A managed source can also carry date and date-and-time columns, since it takes those types from the database or Salesforce object it mirrors.

You manage rows three ways:

  • In the dashboard, by hand — open the data source under Data sources, then add, edit, or deactivate rows one at a time.
  • In the dashboard, from a CSV file — upload a spreadsheet export to add and update many rows at once. See importing rows from a CSV file below.
  • Through the API — bulk insert from 1 to 1,000 rows per request, and list rows with cursor pagination. See the API reference for the endpoints.

Rows can carry an external id from your own system, which makes repeated imports straightforward to reconcile.

Columns that hold an id from another table

Data mirrored from a database usually arrives normalized: a varieties source stores its supplier as an id into a suppliers table, not as a company name. Shown as-is, that column reads as a meaningless code to the person filling the form.

Resolve it in the source database, by pointing the managed source at a view rather than at the table:

create view fieldscroll_varieties as
select v.id, v.name, v.subname, s.name as supplier_name
from varieties v
left join suppliers s on s.id = v.supplier;

Then configure the managed source against fieldscroll_varieties, and supplier_name is an ordinary text column everywhere — the picker, formulas, reports, and the dashboard.

A view is additive and read-only: it changes no table and migrates no data. It is usually the better boundary anyway, since it gives FieldScroll a stable set of columns instead of coupling the sync to your raw table shape, and it lets you grant read access to just the view.

Importing rows from a CSV file

The Import CSV button on a data source's rows page loads a spreadsheet export. The file needs a header row whose names match the source's column keys — the Export CSV button on the same page writes a file in exactly that shape, so exporting, editing in a spreadsheet, and re-importing is a supported round trip.

Before the file picker opens, you make two choices.

Identifier column. Pick the column that names each row — a part number, a site code, an employee id. It defaults to the first column. FieldScroll matches rows in the file against rows already in the data source by this value, so re-uploading a corrected file updates those rows in place instead of adding a second copy of each one. Every row in the file must have a value in this column, and no two rows may share one.

Remove rows not in the file. Leave this off — the default — and the import only adds and updates. Rows already in the data source that the file does not mention are left alone. Turn it on when the file is the complete list and anything missing from it should go away.

What the import checks

  • Values that contain commas, quotes, or line breaks are read correctly as long as the file quotes them the way spreadsheet programs do. A site name written as Houston, TX stays one value.
  • A row with the wrong number of columns is reported by line number and nothing is imported. The same goes for a blank or repeated identifier value, or a header the data source does not have. You fix the file and upload again — a bad file never lands halfway.
  • When Remove rows not in the file is on and the file would delete more than half of the current rows, FieldScroll declines to delete anything and tells you so on screen. Additions and updates still apply. This catches the common accident of uploading a filtered or partial export as if it were the full list. If the deletion is intended, remove the rows by hand or in smaller passes.

Size limit

One import handles up to 5,000 rows. For larger loads, use the API row endpoints, which accept up to 1,000 rows per request across as many requests as you need. The importer does not split a file for you: a half-uploaded file with Remove rows not in the file turned on would look like a shrinking list and delete rows it should have kept.

Managed sources (synced from a database or Salesforce)

A data source can also mirror data you already keep somewhere else, instead of being maintained by hand. Data sources → New offers three choices:

  • Manual — you keep the rows yourself, by hand, from a CSV file, or through the API.
  • Managed (external database) — mirror a table or a view from your own PostgreSQL or MySQL database.
  • Managed (Salesforce) — mirror records from one Salesforce object.

The two managed kinds behave the same way once they are set up. FieldScroll keeps the rows in sync on a polling interval, and mirrored rows are read-only inside FieldScroll: edits happen in the database or Salesforce org you connected and arrive here on the next sync. A managed source starts its first sync as soon as you create it, rather than waiting for the next scheduled run.

Mirroring a database table

You connect a PostgreSQL or MySQL database in the dashboard, pick the table or view, and map its columns. A view works as well as a base table, so you can shape exactly what FieldScroll sees — join, filter, or rename columns in a view and point the source at that.

Mirroring a Salesforce object

The Salesforce wizard has three steps. What you need on the Salesforce side, the other direction (pushing records into Salesforce), and a table of Salesforce error messages are in the Salesforce guide.

Connect. Say whether the account is a production or Developer Edition org or a sandbox, then sign in through a Salesforce window. You type your password on Salesforce's own page, so FieldScroll never sees it. The access tokens Salesforce hands back are stored encrypted and are not shown anywhere in the dashboard.

Object. Filter the objects the connected Salesforce user can query and pick one — Account, Work Order, a custom object, whatever you use.

Fields and sync. Pick the fields to mirror. Some kinds cannot be mirrored and are not offered: address and location fields, file and base64 fields, and fields Salesforce reports as untyped. Each field you pick gets a column key derived from its Salesforce API name — BillingPostalCode becomes billing_postal_code — and you can edit that key before saving. The column type follows the Salesforce type: checkboxes become boolean; number, currency, and percent fields become number; date and date/time fields keep those types; everything else becomes text. The Salesforce record Id is always the row's external id, so you never map it yourself.

Last, set how often to sync. The default is every 60 minutes and the shortest allowed is 15. Salesforce counts API calls against a daily limit for your org, and every sync reads the whole object, so a short interval spends that budget quickly.

An object with more than 100,000 records syncs only part of the way. See Needs attention below.

When the Salesforce object changes shape

Salesforce orgs change, and a mapped field can move out from under a source. What happens then is deliberately different from a database source:

  • A field that disappears from Salesforce is kept, not dropped. The column stays in the source, holding the values from the last sync that had it, until no published form points at it any more. A live form never loses a column it reads.
  • New Salesforce fields are not added on their own. A database source picks up new columns as they appear; a Salesforce source does not. Add the field in the source's settings when you want it.
  • A mapped field whose type changes stops the sync. If a field is re-typed in Salesforce so that it would land as a different kind of column — a number field turned into a picklist, say — the sync stops and the error names the field and asks you to re-map it. FieldScroll does not quietly change a column's type under forms that already read it.

Watching a sync

Each managed source's page has a sync panel showing where that source stands: Synced, Syncing while one is running, Error when the last one failed, Needs attention when a sync finished but did not do everything it was asked to, or Pending first sync before the first one lands. Next to the status it shows when the last sync finished, how often the source syncs, what it mirrors and from where, and the full text of the last error. Sync now runs a sync immediately instead of waiting for the interval.

The data sources list carries the same statuses in a Sync column, so you can scan every source at once. Sources you maintain by hand show a dash, since nothing syncs them.

A Salesforce source also has a Reconnect Salesforce button, which signs in again and stores fresh tokens. Use it when the error says the connection expired or someone revoked FieldScroll's access in Salesforce. You need it after a sandbox refresh too, since a refresh changes the address the old tokens pointed at.

Needs attention most often means the delete pass was skipped. When rows disappear upstream, FieldScroll declines to remove more than half the rows in one sync — a guardrail against a bad query emptying a source your forms depend on. New and changed rows still arrive; the deletions wait. Until you look at it, rows deleted upstream stay selectable in forms and stay on devices, so field users can collect against something that no longer exists.

Check the source against the database or Salesforce object it mirrors first — a sudden halving is as likely to be a broken query or a bad deploy on your side as a real change. If the shrink is genuine, say a seasonal catalog turning over, there is nothing in the dashboard yet that lets the delete through: mirrored rows are read-only in FieldScroll, and the guardrail cannot be raised or acknowledged from the interface. Contact support and we will clear it. The source keeps showing Needs attention until then.

The other reason is size. A managed source syncs up to 100,000 rows or Salesforce records. Past that the snapshot is cut short, and the deletes are skipped rather than guessed at from a partial picture.

To check a source against the database or Salesforce object it mirrors — and to know which of these fields prove what — see checking a data source is current.

How forms use data sources

A lookup field in a form points at one data source and presents its rows as a searchable dropdown. For each lookup field you choose:

  • Display columns — which columns appear in each picker row and in the field after selection.
  • Search columns — which columns the user's typed search matches against.
  • Filters — narrow the rows offered. A filter can compare against a fixed value, or against another field's current answer — for example, show only parts whose category matches what the user picked in the category field above. When the lookup sits inside a repeating section, you choose where that answer is read from: the current row, the parent section, or the top of the form. That lets a lookup in each row filter by something chosen once at the start — say, a project picked at the top of the form. When the answer being matched against is itself a lookup, the filter reads one detail of the selected row — the species id out of the species that was chosen — so you do not need a spare hidden field copying that id into place. Pattern 7 walks the whole shape through, including forms that still carry those copying fields from before.
  • Auto-select — when filters leave exactly one matching row, the field can fill itself in.

A long list is not truncated. The picker loads more rows as the user scrolls and shows how many rows are displayed out of how many match, so a 500-row source reads as a 500-row source. One case has a ceiling worth knowing: when a filter has to be calculated from other answers, the picker works from the first 2,000 matching rows and tells the user to search rather than presenting a partial list as the whole one.

When the user picks a row, the record stores a snapshot of the whole row — not just an id. If you later edit or remove the source row, existing records still read exactly as they were captured.

Offline behavior

Data sources marked for mobile sync download to the device along with published forms, so lookup fields keep working without signal. The device checks two version counters on each sync — one for the column layout, one for the row data — and re-pulls only what changed.

A source that syncs to mobile can also be reached from a printed QR code: a code can name one row, and scanning it opens the form with the lookup field already filled from that row. The row is read from the device's copy, so this needs the mobile-sync setting above. See QR codes and deep links.

Removing a data source

You delete a data source from its edit page. If a published form still has a lookup field pointing at it, the delete is blocked and the dashboard names the form that depends on it, so a live form never loses the rows it reads. Update or unpublish that form first, then delete.

Limits worth knowing

  • A dashboard CSV import caps at 5,000 rows per file.
  • Bulk inserts cap at 1,000 rows per API request. Larger imports take multiple requests.
  • Rows are maintained by hand, from a CSV file, through the API, or synced automatically from a connected database or a Salesforce object — see the managed sources section above.
  • Managed sources cannot be imported into by hand or by CSV. Their rows come from the database or Salesforce object they mirror.
  • A managed source syncs up to 100,000 rows or Salesforce records.
  • A Salesforce source syncs no more often than every 15 minutes. The default is every 60.
  • A single sync will not delete more than half of a source's rows. When more than that disappears upstream, the deletions are held back and the source shows Needs attention.
  • Lookup fields read data sources within the same organization.

For where data sources fit in the larger picture, see the data model.