> ## 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.

# Reference data and scanning

> Configure fields for dropdowns, scans, lookups, reports, and other local references.

# Reference data and scanning

When a component references another table, identify all of the fields used by its reference configuration.

At minimum, consider:

| Configuration   | Required source field                                       |
| --------------- | ----------------------------------------------------------- |
| `displayCol`    | Field shown to the user.                                    |
| `postValueCol`  | Field returned or posted after selection.                   |
| `filterRefCol`  | Field used for reference filtering.                         |
| `filterRefCol2` | Second field used for reference filtering, when configured. |

All fields used by the reference must be included in the referenced table's effective requested columns.

***

## Example

Suppose a component references `Production Unit` with:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
displayCol = Description
postValueCol = PU_ID
filterRefCol = Active
```

The reference table should contain at least:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tableName": "Production Unit",
  "requestColumns": [
    "@row.id",
    "PU_ID",
    "Description",
    "Active"
  ]
}
```

If `Active` is not downloaded, the component cannot reliably perform the configured filtering locally.

***

## Reference-table naming

The referenced table name must match the configured `tableName` exactly.

A table can sync successfully while a component using that table still fails because one of the required reference fields was not downloaded.

***

## Barcode and smart scan configuration

For barcode or smart-scan functionality, make sure the referenced table downloads:

* the field containing the scanned value;
* the field displayed after a match;
* the field returned or posted after a match;
* any additional fields used by the scan configuration.

When a value does not match, compare the scanned value with the source value carefully.

Check for:

* leading spaces;
* trailing spaces;
* leading zeroes;
* different capitalisation;
* unexpected formatting.

Example:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
001234
```

is not necessarily equivalent to:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
1234
```

depending on how the values are stored and matched.

***

## `LOOKUP` and report reference data

Features using locally downloaded reference data require all fields involved in the operation to be downloaded.

For a `LOOKUP`, include:

1. the field used to locate the matching row;
2. the field returned from that row.

For a report reference, include:

1. the configured match field;
2. the configured display field;
3. any other fields required by the report configuration.

The fact that a field exists in the source database is not sufficient.

The app feature works against the **locally downloaded copy**, so required fields must exist in that copy.

***