↑↓ selectEnter openEsc close

    1. Elbuz

    How to import your own file into the catalog: universal import with manual column mapping

    28 min readUpdated

    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.

    Import window with the list of templates, including a universal template
    1Universal template row
    1. 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.

    Universal import template form with the field mapping table
    1Mapping row
    2File format
    1. Mapping row — the catalog field on the left is filled from the file column or node on the right.
    2. 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.

    The top two refusals happen before any request to AI. All refusals below leave the form as it was; success replaces the product field rows, which get into the template after “Save mapping”
    NoYes, XMLNoYes, CSV or XLSYesNoYesNoYes“Fill in with AI”File selected on the“Local file” tab?“Choose a file first” —no requestProduct nodefound in the file?“Product node … not found in thefile” —no request sent to AIFile sample and field list —one request to the language modelAI answered andthe answer was parsed?“AI returned no answer” or“Could not parse the AI response” —form unchangedAt least onefield recognized?“AI could not match any field” —form unchangedProduct field rows replaced by the AIsuggestion —then “Save mapping”
    • 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.

    Three branches — three ways a category gets into the mapping. The right branch is products that got no section: they wait in the disabled service section
    Categories block with ID(XML only)YesNo“Category path in product”(first path is the main one)YesNoMissingor not recognizedProduct from the fileHow is the categoryset in the mapping?A section with this IDalready in the catalog?Product in this section —section name rewritten from the fileEnabled section created,product in itA section with this nameunder the same parent?Product linkedto the existing sectionSections created from the path,product linked to them“Products - universal” —disabled, excluded from exports
    • 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.

    The left branch works when the row has your own key: then the three-field combination is no longer checked. Both branches meet at “Do not update” — this flag decides whether the found card changes
    NoYesYesNoNoNoYesYesYesNoFile rowIs “Name”filled in?Row dropped —nothing gets into the catalogIs your own uuid keyfilled in the row?Is there a cardwith this key?Is there a card with the same“Manufacturer SKU” + “Name”+ “External link”?New card createdIs the card marked“Do not update”?Card fields unchangedCard updatedwith the mapped fields
    • 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.

    JSON (advanced) tab with the mapping editor and the Apply to form button
    1Product section
    2Apply to form
    1. Product section — the place where a new key is added.
    2. 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.

    The top refusals happen before the file is read, and the catalog stays as it was. After “Stop”, what was saved stays — the run ends with final processing, like a normal one
    “Local file”No“External link”NoYesYes — Elbuz fetchesthe file by linkNoYesYesNo, file read to the end“Import” in the template windowWhich tabis open?Did the file reachthe server?“The file could not be sent to theserver…” —catalog unchangedIs the linkfilled in?Import doesn't start —catalog unchangedIs the mappingset?“Field mapping is not set” —catalog unchangedFile read in batches of 2,000 rows—“Products saved: N” after each“Stop” clicked?checked every 200 rowsWhat was gathered is saved, finalprocessing —“Operation aborted by user!”Final catalog processing —“Data import completed!”
    • 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.

    The Run history window of the universal import template
    1Totals for the period
    2One import run
    1. Totals for the period — number of runs, average duration, longest run and runs with errors.
    2. 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

    Common problems
    What you seeWhyWhat 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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free