Reference & Administration

Files and sources

Advanced import accepts these file types:

  • Excel workbooks (.xlsx), with one source per sheet.

  • ZIP archives (.zip) containing CSV files, with one source per CSV file.

  • A single CSV file (.csv), whose one source is the model being imported into, whatever the file is called.

A source is named after its model, such as Order; a custom model is named after the custom model. A sheet or CSV whose name is not a model is ignored. In an Excel workbook, a __config__ sheet written by the exporter maps shortened sheet names back to the full ones.

Standard export produces sources for the selected model and related models. One-to-many children get a source of their own, which names its parent. A many-to-many field, or a collection custom field, is one column of its owner that lists the related records — see Many-to-many columns. Flat mode keeps the main model’s many-to-many columns and omits one-to-many fields and related sources.

The importer ignores empty rows and imports sources in dependency order: a source loads after the sources its references name. A row that references a record it cannot find — a missing source, row or identifier — is reported as a "Relation not found." error in the result workbook; a link sheet row whose owner is not found is reported as "Record not found."

Mapped columns are checked against the file’s source model as soon as the file is read: without write and import access to the model, or import access to a mapped field, the file is refused.

Records the same file creates

A row can name a record created later in the same sheet, or two sheets can name each other — a contact its primary address, and the address its contact. The importer leaves such references out of the first pass, and sets them in a second pass once every source has loaded. A reference that still names no record then is reported in the Errors sheet; its record is kept without it.

A cycle made only of required references — each record needing the other to exist before it can be saved — has no order that works. The import is refused before any record is written, with an error naming the references in the cycle.

Files exported by earlier versions may contain link sources, named after the field they fill (OrderLine.taxes), with one row per link. They still import after the main sources, and only add links.

Record identity

The importer first uses a model’s required unique field to find an existing record — preferring code, email, emailAddress or a field ending in Seq. A model with none has no business key, so its key is importId, which an export with Allow re-import fills with a generated value such as contact-42 where it is empty. If that lookup fails, it can use importId and then id when those technical columns are present. This permits an export-edit-import workflow where a business key changes without duplicating the record.

For relationship fields, the same rule applies to the referenced record. Include the relationship’s stable identifier when editing a referenced record’s unique value.

Permissions

Export requires read and export access to every model included in the export. The current security filter limits the records that can be exported, including the related records written to their own sources.

Import requires write and import access to each imported model, and import access to every mapped field. Grant the least access required for the data-exchange job; the existing Security guide describes model and field permissions.

Field-level permissions apply to import only — every mapped field is checked individually. Export enforces permissions at the model level.

Configuration

The following axelor-config.properties settings apply to advanced exchange:

Setting Description Default

data.export.max-size

Maximum number of main records in one export. Use -1 for no export cap. An export of the main records stops at the cap; related data that exceeds it fails the export with "Related data too large to export."

-1

data.export.fetch-size

Number of records fetched per export batch. Tune this for large exports without exceeding database limits.

500

data.import.max-size

Maximum advanced-import file size, in KB. Leave unset to disable this additional server-side limit.

The general upload limit and temporary-file location are configured separately by data.upload.max-size and data.upload.temp-dir. They affect the upload pipeline and disk space available for generated files; see Files Storage.

Operational limits

The browser import dialog rejects files larger than 5 MiB before upload. Server upload policy or data.import.max-size can impose a lower limit.

Export and import both run inside the request, with the dialog open; there is no background job or progress report. The generated file is a temporary file on the server, downloaded once the request completes. For very large data sets split the export with filters, and import in several files.

When data.export.max-size is set, verify that the limit is appropriate for the business task before a user exports. Related data can make a standard relationship export considerably larger than its number of main records suggests.