> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farmtrace.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Table Setup Guide

> Start with the table setup model and choose the configuration detail you need.

This guide explains how to configure the table setup records used by the mobile app. It covers table registration, downloaded columns, visibility, role-based rules, reference data, filtering, common configuration patterns, troubleshooting, and the checks required before publishing a configuration change.

***

## 1. Core Configuration Model

Create **one table setup record for every source table that the app must download**.

Each setup record contains the following fields:

| Field        |  Required | Description                                                                         |
| ------------ | :-------: | ----------------------------------------------------------------------------------- |
| `Table Name` |    Yes    | Exact name of the source table, including spaces, punctuation, and capitalisation.  |
| `Table JSON` |    Yes    | JSON configuration object for the table, stored as text.                            |
| `Id`         | Automatic | Database ID of the setup record. Leave the automatically generated value unchanged. |

### Critical naming rule

`Table Name` and the `tableName` property inside `Table JSON` must be **identical**.

For example:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Table Name = Staff
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tableName": "Staff"
}
```

Treat this as the same table name written in two places.

***

## 2. Complete Configuration Example

For a source table named `Staff`, the `Table JSON` field could contain:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tableName": "Staff",
  "visible": true,
  "requestColumns": [
    "@row.id",
    "Id",
    "Full Name & ID",
    "Barcode Text",
    "Production Unit",
    "Contract Status"
  ],
  "queryFilter": "[Contract Status] = Active",
  "roleAccess": [
    {
      "role": "B. Farmtrace Developers",
      "isAllowedToView": true,
      "addedColumns": [
        "Email"
      ],
      "hideColumns": []
    }
  ]
}
```

Enter the JSON object itself into `Table JSON`.

Do **not** escape every quote unless the system receiving the value specifically requires escaped JSON text.

***

## 3. JSON Requirements

Before publishing a configuration, make sure the contents of `Table JSON` are valid JSON.

### Rules

* Use double quotes around property names and text values.
* Use `true`, `false`, or `null` for Boolean or null values.
* Do not place Boolean values inside quotes.
* Use square brackets for lists such as `requestColumns` and `roleAccess`.
* Do not include comments.
* Do not include trailing commas.
* Every `{`, `[`, and `"` must have a matching closing character.
* Run the final value through a JSON validator before publishing it.

### Correct

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "visible": true
}
```

### Incorrect

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "visible": "true",
}
```

***

## Continue

<CardGroup cols={2}>
  <Card title="Table setup fields" icon="list-tree" href="/dsync/table-setup/table-fields">
    Configure table names, visibility, downloaded columns, and row identity.
  </Card>

  <Card title="Filters and role access" icon="users" href="/dsync/table-setup/filters-and-roles">
    Apply source filters and calculate role-specific visibility and columns.
  </Card>

  <Card title="Table screens" icon="table-2" href="/dsync/table-setup/table-screen">
    Configure the fields used by the normal table screen and diagnose missing fields.
  </Card>

  <Card title="Reference data and scanning" icon="scan-line" href="/dsync/table-setup/reference-data">
    Prepare dropdowns, multi-reference fields, barcodes, scans, lookups, and reports.
  </Card>

  <Card title="Configuration patterns" icon="copy-check" href="/dsync/table-setup/configuration-patterns">
    Start from tested patterns for active, hidden, and role-specific tables.
  </Card>

  <Card title="Troubleshooting and limitations" icon="triangle-alert" href="/dsync/table-setup/troubleshooting">
    Check local data, refresh behavior, row identity, and known configuration limits.
  </Card>
</CardGroup>