abp/docs/en/low-code/data-import.md

//[doc-seo]
{
    "Description": "Import Excel or CSV data into ABP Low-Code pages with guided mapping, append or merge behavior, foreign-key matching, remote files, and invalid-row downloads."
}

Data Import

The React Low-Code runtime can import Excel and CSV files into a dynamic page. The import wizard previews the file in the browser, maps source columns to entity properties, reviews the operation, and sends the file plus the confirmed mapping to the backend.

Import is enabled by default for pages and can be disabled per page with importEnabled: false.

Import Workflow

1. Open a dynamic data page and select Import.
2. Upload an Excel or CSV file, or download a sample file for the page.
3. Review the detected columns and map each source column to one target property.
4. Choose Append or Merge.
5. Review required fields, conversions, relation matching, and file/image sources.
6. Run the import and download the invalid-row file if any rows fail.

Column names are matched automatically when a source header equals a property name or display label after normalizing spaces, underscores, hyphens, dots, and letter casing. Review every automatic mapping before import.

The wizard reports mappings as compatible, convertible, warning, or incompatible. The backend remains authoritative and validates each converted value, entity rule, and mapped property.

Append and Merge

Append creates a new record for every valid row. The Id column is not accepted in append mode.

Merge uses one mapped property as the match key:

• A matching record is updated.
• A non-matching row creates a record.
• The match property must be included in the column mapping.
• When the selected property can match multiple records, choose either Error or Use first. Use first also requires a deterministic sort property and direction.

Use an ID or unique business key whenever possible. A non-unique merge key makes the result depend on the selected multiple-match rule.

Foreign-Key Mapping

A foreign-key column can contain the related record ID or another allowed match property such as a unique username or code. The wizard exposes the supported related-entity match fields for that property.

If a foreign-key lookup can return multiple records, the same rules apply:

• Error rejects the row.
• Use first requires an explicit sort property and direction.

This decision is per mapped foreign-key column, independent of the main append or merge mode.

Value Extraction

Use a source-value regular expression when a cell contains extra text around the value that should be imported. The expression must contain a named value capture group:

Order: (?<value>[A-Z]+-\d+)

The server compiles and executes the expression with bounded input, evaluation count, and elapsed-time budgets. A structurally valid client preview does not replace server validation.

File and Image URLs

File and image properties can import remote files referenced by spreadsheet text. Source modes are:

Mode	Use it when
auto	The runtime should detect a supported URL shape
fullUrl	The whole cell is the URL
fileNameAndUrl	The cell contains a file name and URL
extractUrlFromText	The URL is embedded in surrounding text
customRegex	A custom expression extracts a named url group

Remote downloads are performed by the backend, not by the browser. The verified defaults require HTTPS on port 443, allow only public network destinations, follow at most three redirects, and reject private, link-local, multicast, and loopback destinations. Development loopback HTTP is available only when both the environment is Development and AllowLoopbackHttpInDevelopment is enabled.

Restrict production destinations with LowCode:Import:RemoteFiles:AllowedHosts when imports should fetch only from known hosts. Download count, per-file bytes, aggregate bytes, concurrency, redirects, and timeout are all bounded by LowCode:Import:RemoteFiles options.

Remote files are staged before row persistence. A failed row or failed merge does not replace an existing stored file with an incomplete download.

Partial Failures

Import continues after row-scoped validation or conversion failures. The result reports:

• Total rows
• Succeeded and failed rows
• Created and updated records
• A short-lived invalid-row download token when failures exist

The invalid-row file contains the original row values plus failure details so the rows can be corrected and imported again. The verified default token lifetime is 600 seconds.

Failures that make the whole request unsafe, such as an invalid archive, exceeded global file budget, or blocked remote destination, stop the import before normal row processing.

Limits and Configuration

Important verified defaults are:

Setting	Default
LowCode:Import:MaxRows	10000
LowCode:Import:MaxColumns	256
LowCode:Import:InvalidRowsTokenLifetimeSeconds	600
LowCode:Import:RemoteFiles:Enabled	true
LowCode:Import:RemoteFiles:RequestTimeoutSeconds	15
LowCode:Import:RemoteFiles:MaxConcurrentDownloads	4
LowCode:Import:RemoteFiles:MaxFilesPerImport	500
LowCode:Import:RemoteFiles:MaxFileBytes	10485760
LowCode:Import:RemoteFiles:MaxTotalBytesPerImport	104857600
LowCode:Import:RemoteFiles:AllowedPorts	[443]

The options validators reject non-positive, inconsistent, or above-ceiling values. Keep imports page-scoped and use the existing limits instead of accepting arbitrary workbook sizes.

See Also

• React Runtime
• Data Modeling and Page Behavior
• Model Descriptor Files
• Foreign Access