Elbuz imports XML, YML, CSV, XLS or XLSX files of any structure into the base catalog. Map once which column or tag feeds which product field, and same-layout files reuse that mapping.
When you need this:
- Supplier price list in its own format — the next file reuses the saved mapping.
- Flat-table catalog from another system — the section tree comes from the category path column.
- Unfamiliar column names — “Analyze file” shows the contents, AI suggests a mapping.
- Supplier rewrites product names — your own key recognizes products by code, so no duplicates.
Where to start: open the “Универсальный импорт” (Universal import) template and map your columns.
What universal import can do
- Column mapping — you specify which column or tag each product field comes from, and the mapping is saved in the template.
- Hints — “Analyze file” shows the file's columns and tags, and AI suggests a ready mapping.
- Categories — by from the categories block or by a text path like “Section / Subsection”.
- Your own key — a product is recognized by the supplier's code, however its name changes.
- Run log — shows how many rows were read and where the import stopped.
- Units of measurement — “шт.” and “штук” (both “pcs”) from different files are merged into one unit in the directory.
When to use universal import instead of a ready-made template
Use universal import when there is no ready-made template for your file. Ready-made templates — XML/YML, CommerceML (1C), XLSX (Prom/EVO) — expect a standard structure with known column and node names. If your file is standard, a ready-made template is simpler: its columns are already mapped.
Universal import is for non-standard files: a homemade export from another accounting system, a supplier price list in its own format, XML with arbitrary node names. Map it once, and files of the same format are then imported with this template. All import methods compared: which method to choose.
Formats: XML and YML, CSV, XLS and XLSX. You can upload the file from your computer or give a link that Elbuz fetches the file from. You choose the format in the template: in a table (CSV/XLSX) the data is in columns, in XML it is in nodes.
1
Universal template row- Universal template row — the type column reads “Universal (XML/CSV/XLS)”.
How to map the columns of a file
The mapping is a table of matches: on the left is the Elbuz card field, on the right is the source in the file. For each field you need, specify where the value comes from:
- for a table (CSV, XLS, XLSX) — the file column (by header name or number);
- for XML — a node or attribute (for example,
price,vendor,@id), plus the product node: the repeating element that holds one product (for example,//offer).
Unmapped fields are neither filled nor touched, so map only what the file has. Save the mapping in the template with “Save mapping”; you can change any match at any time by editing its row.
1
Mapping row2
File format- Mapping row — the catalog field on the left is filled from the file column or node on the right.
- File format — choose XML / YML, CSV or XLS before mapping.
What you can map
You can map any product card field that is a column in the products grid: name, price, SKU, quantity, availability, manufacturer, description, weight and dimensions, barcode, meta fields and your additional fields. Service fields (internal IDs, dates, system flags) are filled in by Elbuz itself. Separate blocks are used to map:
- Category — by an ID from the file or by the full path (categories).
- Attributes — a separate section for product attributes; its “Unit” field is looked up in the units of measurement directory (units of measurement).
- Photos — a separate field for image links.
What happens to empty values
- An empty value doesn't overwrite a filled one. If a field is mapped but empty in a file row, the card keeps its previous value.
- Quantity is the exception. A mapped empty or zero quantity makes the product “Out of stock”. If quantity isn't mapped at all, the product gets the “In stock” status.
- A row without a name is dropped entirely. Without “Name”, nothing from the row gets into the catalog.
No need to guess column names: file analysis, AI and presets
“Analyze file” reads your file and shows its tags and columns as hints in the mapping fields — just pick the right ones. For XML and CSV it reads the first 512 KB (XLS and XLSX in full), checks at most 50 product nodes in XML, and reads the header row of a table. The catalog doesn't change.
“Fill in with AI” suggests a ready mapping: Elbuz works out where the name, price and SKU are, and you check and correct it. A file sample goes into the request: for XML, the first product node cut to 8,000 characters; for CSV and XLS, the first six rows, with each value cut to 120 characters.
- Start or end
- Action or result
- Decision: the path depends on the answer
For common sources there are presets — saved sets of matches that fill in the mapping in one click.
A preset, AI and replace the mapping rather than add to it:
- choosing a preset replaces the mapping entirely, including the file format and source settings;
- “Fill in with AI” fully replaces the product fields block, plus the photo, attribute, category and tag blocks that AI answered for. Fields you mapped by hand that AI didn't find will disappear. The file format and source settings are taken from the form;
- the “Apply to form” button on the “JSON (advanced)” tab replaces the mapping with what's written in the editor.
The order that keeps your work: first a preset or AI, then manual edits, and only then “Save mapping”.
How to import categories: by ID or by path
Categories in a file come in two kinds:
- A categories block with IDs (as in YML) — Elbuz builds the tree from it and links each product by its categoryId. This block exists only for XML.
- A text path in the product row (“Home appliances / Kitchen / Kettles”) — Elbuz parses the path and creates the nested sections itself. This is the method for flat tables without a separate classifier.
Sections from the file are regular catalog sections: enabled, included in exports, and the section card shows which template created them. A repeat import doesn't create duplicates, but renaming is handled differently:
- a section created by text path is looked up by the pair “parent section + name”. If you rename it on your side, the next run creates a new section next to it with the old name;
- a section created by ID from the categories block is looked up by ID and survives renaming. But each run writes the name from the file back.
Products whose category is missing or not recognized go into the service section “Products - universal”, which is disabled and excluded from exports. If it isn't empty after a run, fix the category mapping. How to move products out of it and why you can't delete the section together with them: service categories.
- Start or end
- Decision: the path depends on the answer
How Elbuz recognizes a product and how to set your own key
The field list has no “key” field: recognition is built in and works in two steps. First, Elbuz looks for a card with the same product ID (a string), if the file passes one. Otherwise it searches by a combination of three fields: “Manufacturer SKU” + “Name” + “External link”, ignoring case and extra spaces.
- Start or end
- Decision: the path depends on the answer
This leads to two consequences that cause most duplicates:
- if the name changes in the next file for the same product (“Чайник біл.” → “Чайник білий”, “White kettl.” → “White kettle”), the combination no longer matches, and a second card appears instead of an update;
- if the file has two different products with the same name and the same (or empty) SKU, the first import creates two cards, but after that only one of them gets updated.
A key of your own is safer. On the “JSON (advanced)” tab, add "uuid": {"from": "Code"} to the product section, where “Code” is the column or tag with a stable product ID in the source (up to 80 characters), and click “Apply to form”. The product is then recognized by this value, and later runs don't overwrite it.
1
Product section2
Apply to form- Product section — the place where a new key is added.
- Apply to form — pushes the edited JSON into the mapping table.
How to run the import and check the result
Start it with the “Import” button in the template window header. The open tab above the mapping sets the file source: “Local file” sends the file you just selected; “External link” makes Elbuz fetch the file from the address in the link field. The run uses the mapping on the screen, even if it isn't saved.
The “Import” button in the template list and the ▶ icon in its row import nothing: the log says “Data import completed!”, but no products appear. This template has no schedule. Start the import from the template's own window.
Do the first run on a small file and check a few cards by eye: are names, prices and categories in the right places? Once you're sure, import the full file.
The “Active / Disabled” switch in the window header only affects the group run “Import all templates” (disable or delete). You can't delete the universal template — it's a system row.
- Start or end
- Action or result
- Decision: the path depends on the answer
What the run log shows
The log opens in the “Notifications and operations” side panel, “Active” tab, and stays there if you close the template window:
- “Reading file (XML)” — the format from the mapping is in brackets. Wrong format? Stop right away;
- “Products saved: N” — after each batch of 2,000 rows;
- “Final catalog processing (markups, sorting, indexing)…” — the file has been read to the end;
- “Total products processed: N”, then “Data import completed!” and “Time spent”.
Both numbers in the log are rows read from the file, not cards in the catalog. A row without a name is dropped after counting. “Total products processed: 4000” with an empty catalog means the “Name” field isn't mapped.
Each run appears as a separate row in “Run history” (the icon in the template window header), and this template's cards appear in the base catalog under the “Source: name”, “Source: code” and “Source: ID” columns. More: how to check that the import worked. Log rows are kept for 14 days, operation cards for 90.
1
Totals for the period2
One import run- Totals for the period — number of runs, average duration, longest run and runs with errors.
- A single run row — start time, status, duration, user and result.
What happens to the catalog on later runs
The general mechanics of a repeat import are the same for all templates and are described in the overview: what a repeat run overwrites. Below is what's special about universal import.
A product disappeared from the file
Universal import doesn't disable, zero out or delete cards that are missing from the new file: this template has no “Delete entries…” checkbox. More: a product disappeared from the source.
The “Categories from the file are the single source of truth” checkbox in the “Categories” section only unlinks products in the file from sections the file doesn't list. Products missing from the file aren't touched. To find outdated items in the base catalog, filter by “Source: name” and sort by “Update date” — an old date means the product no longer comes in the files.
Why a product wasn't updated
Universal import doesn't touch a card marked “Do not update”, and doesn't change the price of a card marked “Fixed price”. Photos are added only to new products. More: how to lock your own value.
If two templates bring the same product, the value from the latest run stays; the “Source” columns show who created the card (two templates for the same product).
If a run created extra cards
Filter this template's cards in the base catalog by “Source: name”, “Source: code” (here universal) and “Date added”. Extra cards are deleted permanently (if you imported the wrong data). Pairs of identical cards are merged in the “Catalog duplicates” window (finding and merging duplicates). To keep duplicates from coming back, set your own key.
If the import broke off
Data goes into the catalog in batches of 2,000 rows, so after a break the catalog keeps what had been saved; the last “Products saved: N” shows where it stopped. The run checks for “Stop” every 200 rows. A repeat run is safe if products are recognized reliably (your own key). More: if a run broke off.
Limits of a single run
There is no row limit: the file is read as a stream, and a run gets 2 hours. If a file won't reach the server through the browser, import it by link. More: limits of a single run.
Scenarios
A supplier price list in its own format
What to turn on: an Excel table with the columns “Code”, “Name”, “Wholesale price”, “Stock”, “Brand”, “Section”. Mapping: “Code” → “Manufacturer SKU”, “Name” → name, “Wholesale price” → price, “Stock” → quantity, “Brand” → manufacturer, “Section” → category by path. Set the same “Code” as your own key: "uuid": {"from": "Code"}.
What you get: the next price list with the same layout is imported with this mapping, and items are recognized even after the supplier rewrites the names.
A supplier price list arrives regularly, and the names in it get rewritten
What to turn on: in the mapping — “Name” and other fields you need; on the “JSON (advanced)” tab, in the product section, the line "uuid": {"from": "Code"} with the column of the supplier's stable code, then “Apply to form” and “Save mapping”. Set the key before the first import of this price list.
What you get: the product is recognized by its code, however its name changes. What won't happen: cards this price list created earlier without a key aren't recognized by code — the run creates second cards next to them.
Move a catalog from another system's flat table together with its section tree
What to turn on: the CSV, XLS or XLSX format; in the “Categories” section — “Category path in product” (a column with a string like Appliances>Kitchen>Kettles), “Levels separator” (> by default) and “Categories separator” (| by default) if a product is in several sections.
What you get: sections are created from the path, the product is linked to all listed ones, and the first path becomes the main one. A repeat run uses the existing section with the same name under the same parent. Products with an empty path column go into the disabled “Products - universal”.
The supplier moves products between sections, but in the catalog they also stay in the old ones
What to turn on: in the “Categories” section, “Replace links” block, the “Categories from the file are the single source of truth” checkbox — and only for a complete file.
What you get: products from the file keep exactly the sections listed in the file; other links are removed, including ones set by hand. Without the checkbox, new sections are only added. The sections themselves aren't deleted — only the product links to them disappear.
An unfamiliar file arrived, and you don't want to guess the column names
What to turn on: select the file on the “Local file” tab, click “Analyze file” and, if needed, “Fill in with AI”; for XML, check the “Product node” field first.
What you get: the columns or tags found become hints in the mapping fields, and AI fills in the product field rows. What won't happen: AI doesn't add to your mapping, it replaces the product field rows — a uuid key you added will disappear, so add the key after AI.
What to do when the import fails
| What you see | Why | What to do |
|---|---|---|
| “Field mapping is not set (mapping_config)” | The mapping is empty or the JSON was broken by an edit | Open the “Field mapping” tab and map at least the name and price (how to map) |
| “Wrong file format. This template expects: .xml, .yml, .csv, .xls, .xlsx” | The selected file's extension isn't on this list | Re-save the file in the right format; renaming the extension isn't enough |
| “The file could not be sent to the server. It may be too large or the connection was lost. Error code” | The file didn't reach the server, so parsing never started | Put the file behind a link and import it from the “External link” tab (run limits) |
| “XLS/XLSX reading is unavailable: OpenSpout library is not connected” | This installation has no Excel spreadsheet reader | Save the file as CSV and set the delimiter, or contact support |
| “Product node not found in the file. Check the “Product node” field.” | The “Product node” field holds a tag the file doesn't have | Click “Analyze file” and see which tags it actually has |
| The wrong data was imported from XML | The wrong repeating element is set as the product node | Set the node that occurs once per product in the file (how to map) |
| Cyrillic in names is “garbled” | The file is in the wrong encoding | Re-save the file in |
| CSV columns were read incorrectly | The delimiter in the template doesn't match the file | Set a comma, semicolon or tab — as in the file |
| “AI returned no answer. Make sure the AI assistant is connected.” | AI isn't connected, or it's a demo plan where AI is off | Map the fields by hand — the mapping loses nothing (hints) |
| “AI could not match any field” | The model answered but recognized no fields; the form didn't change | Click “Analyze file” and map the fields by hand |
| The log shows thousands in “Total products processed”, but the catalog is empty | “Name” isn't mapped: rows without a name are dropped after counting | Add the “Name” field to the mapping and run again (run log) |
| Started from the template list — “Data import completed!”, but no products | The universal template doesn't run from the list | Open the template and click “Import” in its window (running) |
| Duplicates appeared after a repeat import | The product's name, SKU or link changed in the file, and there's no key of your own | Set your own key (product recognition) and remove the extra cards (extra cards) |
| After the import, products ended up in the “Products - universal” section | For these rows the category is missing or not recognized | Check the category mapping and move the products (categories) |
FAQ
Do I have to map the file every time?
No. The mapping is saved in the template, and the next file of the same format is imported with it — you set up the matches only once.
Which formats are supported?
XML, YML, CSV, XLS and XLSX. You can upload the file from your computer or give a link — then Elbuz fetches it itself when you click “Import”.
Can I run universal import on a schedule?
No. This template has no schedule; it runs only manually, with the “Import” button in the template window (running).
Can I undo an import in one click?
No, there's no “roll back” button. You deal with the effects by filtering the base catalog by source and date (extra cards).
Will the import group product variants into a family by attributes?
No. Searching for option products is turned off during universal import; variant links are set up separately.
One supplier writes “шт.”, another “штук”. Can they be one unit of measurement?
Yes: in the “Units of measurement” directory, enter the second spelling in the “Name alias” column (unit aliases).
Where to find it and who has access
- Menu
- Directories → Operations → Data import
- Other entry points
- the “Универсальный импорт” (Universal import) row in the template list opens the mapping window
- Access right
- the “Import” window in “Group permissions”
- Have ready
- an , , , XLS or file, or a link to it
Related topics
- If you need to compare import methods and understand what a repeat run overwrites — Importing data into the base catalog.
- If your files spell units of measurement differently — Units of measurement: aliases and conversion factor.
- If the file is a standard YML feed — Import a catalog from XML / YML.
- If the catalog already has duplicates — Finding and merging duplicates.
