Overview

Import

Enables data import from Excel files (.xls, .xlsx) in the current metadata table route.

When active, an Import XLS/XLSX button appears in the List Grid toolbar that opens the file picker and sends the file to the backend import method already available.

Table Metadata

The main toggle is:

md_importable

Meaning: shows/hides the import button in the List Grid toolbar.

Values: true | false.

Default: false (if absent).

Extra Props (`md_props_bag`)

Import options are configured in extraProps.import (derived from md_props_bag).

Snippet 1JSON

{
  "import": {
    "enabled": true,
    "skipsettings": false,
    "allowedExtensions": ["xls", "xlsx"],
    "import_type": "I",
    "commit_level": "R",

Operational Notes

The button is visible if md_importable = true.
The file is validated client-side by extension (xls, xlsx) before upload.
The import is executed on the current route (md_route_name) of the active datasource.
skipsettings:

- false (default): opens the intermediate dialog to choose import options before upload.

- true: skips the dialog and starts direct upload/import using the options already defined in md_props_bag.import.

Recommended defaults in the suggest:

- use_column_captions = "C" (use column captions).

- use_descriptive_fkey = true.

UI and Progress

After import confirmation, a progress dialog opens with real-time percentage.
Available actions:

- Continue in background: closes the dialog and creates a progress notification.

- Cancel import (rollback): cancels and performs rollback.

- Stop and partial commit: stops and commits what has been done.

At the end of import, a summary notification is created (same text as the toast); clicking navigates to the import route without refresh if already on the same page.

Existing PK Behavior (Insert-Only Import)

If import_type = "I" and the record PK already exists:

the insert is skipped;
the record is counted in the summary as "skipped inserts (existing PK)".

File columns and lookups (export and import)

The XLS export and the import follow the same rules, so an exported file imports back as it is.

Headers

Every column is headed by its caption (mc_display_string_in_view; if empty, the column name).
When two columns of the same file have the same caption, each one gets its physical name in parentheses: People (ContactPersonID), People (LastEditedBy). Without collisions the headers stay as they always were.
The import recognises a column by its caption, by its caption with the physical name (or the column name) in parentheses, or by its physical name / column name.
A header that matches more than one column (for example an old file with two People columns) is refused with the error "Ambiguous column": write it as caption (physical name).

Lookup columns: `fkey_mode`

md_props_bag.import.fkey_mode decides how the lookup columns (mc_ui_column_type = lookupByID) travel:

Value	In the file	Notes
`description` (default)	the description of the linked record, under the caption	as always
`key`	the key of the linked record, under the caption
`both`	two columns: the description under the caption, the key under the physical name (`Order` + `OrderID`)	if the caption is the physical name, the description column becomes `caption (lookup text field)`, e.g. `OrderID (CustomerPurchaseOrderNumber)`

The export follows the route's value; without fkey_mode, use_descriptive_fkey applies (true = description, false = key).
In the import dialog the "Lookup columns in the file" choice is preselected from the same value and can be changed for a single import.

From description to key

Key only: used as is.
Description only: the linked record with that description (lookup text field) is looked up.

- One record: its key is used.

- No record: the row fails.

- More records with the same description: if the row updates an existing record and the key it already has matches that description, the link stays as it is (the user did not touch it). Otherwise, and always for new rows, it is an error listing the candidate keys: inserting needs the key, i.e. key or both.

Key and description (`both`): the key wins if its record has that description; if they do not match (one of the two was changed and the other was not) the row fails.
A primary key that is also a lookup (1:1 table) is resolved before the check that the record exists.
With commit_level R or I a lookup error stops the import without saving; with C or T the row is skipped and the import goes on.

Dates

Date cells written by the export (a number with a date format, as in Excel) are read as dates: a file exported and imported back unchanged is no longer refused on its date columns.