↑↓ selectEnter openEsc close

    1. Elbuz

    How to import a catalog from XML / YML: a standard feed without column mapping

    27 min readUpdated

    Elbuz reads an XML / YML feed from a file or link and maps each offer to card fields itself: name, price, availability, photos, specifications, category. No column mapping needed.

    When you need this:

    • Your catalog is a YML feed (Prom, Rozetka, Hotline, CMS) — products arrive with their categories.
    • The feed is at a link — a scheduled template updates prices and stock.
    • Prices are in another currency — they're converted to your base currency at the feed's rate.
    • Colors and sizes are separate offers — offers sharing a group_id become one product with variants.

    Where to start: an “XML” template with a feed link in the “Import” window.

    What XML / YML import can do

    Which feeds Elbuz reads without mapping

    YML is with a predefined structure. The root is yml_catalog, and inside it is a shop with three blocks: currencies (currencies), categories (categories), and offers (offers). Each offer is one product. Element names are standard, so Elbuz knows on its own where the price, the image, and the category are.

    This template can't read XML with arbitrary node names. Import such a file with universal import, where you define the field mapping yourself.

    YML is an XML product feed format accepted by Rozetka, Prom, and others. Each marketplace describes the format in its own help, for example Prom: YML import — file format. Elbuz reads standard YML elements regardless of the source.

    Import window with the list of templates, filtered to the XML template
    1XML template row
    1. The XML import template (type XML) in the template list.

    How Elbuz recognizes a product from the feed

    The matching key is the offer's id attribute (offer id="…"). Elbuz writes it to the “Product ID (UUID)” field and finds the card by it on every run. With a stable id, a repeat import updates the existing card. An id that changes from one export to the next creates duplicates every time. Details: repeat import without duplicates.

    The group_id attribute links the variants of one product: offers with the same group_id become one product with variants, and the first one in the group becomes the main one.

    The id is taken exactly as written in the file. Two feeds with simple numbering (1, 2, 3…) produce the same keys, and the second template overwrites the first one's cards. The “Check uniqueness of records based on this import source” checkbox keeps them apart. Details: two templates for the same product.

    Duplicates from an unstable id show up in the product grid: the name is the same, “Product ID (UUID)” differs, and “Date added” is the day of the run. Fix the source first, then remove the extras. Details: if you imported the wrong thing.

    Where offer values go

    YML elementCard field in Elbuz
    id attributeUUID (matching key)
    name (or vendor + model for type="vendor.model")product name
    price (+ priceuah/pricerub/priceusd/pricekzt) and currencyIdprice (converted to your base currency at the rate)
    oldpriceold price
    available attribute (true/false), presence, stockstock status
    quantitystock quantity
    vendorCode (or code)part number ()
    vendor (or publisher)manufacturer
    categoryId / category / categories blockproduct category
    picture / image (several)photos (the first is the main one)
    descriptiondescription
    barcode / ISBNbarcode () / ISBN
    param name="…"specifications (attributes); param name="sku" →
    url, keywordsproduct link, keywords (tags)
    manufacturer_warrantywarranty

    For a vendor.model offer, the name is built from the brand and model, sometimes with a type prefix (typePrefix). A param element becomes a product attribute: name is the attribute name, and the content is the value. If an element is missing from the feed, the field on a new card stays empty.

    What a repeat run overwrites

    • Empty values in the feed don't erase yours: part number, model, barcode, ISBN, warranty, tags, product link, manufacturer, and category are updated only when the feed has something for them.
    • Price, old price, quantity, name, and description are written as is: no quantity means zero on the card, no name means an empty name.
    • Photos are added: the existing card gets the images it didn't have yet.

    A run doesn't touch a card with the “Do not update” flag, name and description included. With “Fixed Price”, it updates everything except the price and old price. After writing, the run also executes the field formulas marked for import, and their result stays on the card. Details: how to lock your own value, what happens after a run.

    The path of one offer during a run. The “no” branch from the first diamond is a new item: without a category it won't become a card. The “yes” branch is an existing card, and here two flags on the card itself decide everything.
    noyesnoyesyesnoyesnoOffer from the fileIs there a card with this idamong those the template sees?Does categoryId matcha catalog category?A new card is addedNo card is createdDoes the card havethe “Do not update” flag?Fields, price, name, and descriptionstay as they wereFields, name, and description areupdatedDoes the card havethe “Fixed Price” flag?Your price staysPrice and old price come from thefeed
    • Start or end
    • Action or result
    • Decision: the path depends on the answer

    How availability and price are read

    The stock status is taken from whichever comes first in the offer:

    In the feedStatus on the card
    text in presence or stock (в наявності “in stock”, під замовлення “on order”)according to your status detection rules
    available="true" attribute“In stock”
    available="false" attribute“Out of stock”
    nothingthe first status in the directory with the “In stock” classification and its “Default quantity”

    A feed without an availability indicator makes products in stock. If that's not what you want, check the statuses and quantity in the directory before the first run.

    Where the stock status comes from. Text in presence outweighs the available attribute. Status detection rules and the default status also set the quantity, from the directory, not from the feed.
    yesnotruefalseother textyesnoOffer from the fileIs the presenceelement filled?The presence text is usedThe available attribute is used,or the stock element if it's emptyIs the value true or false?Status “In stock”Status “Out of stock”Does the text matchthe status detection rules?Status from the ruleand its quantityFirst status with “In stock”classificationand its default quantity
    • Start or end
    • Action or result
    • Decision: the path depends on the answer

    Currency and price

    The price is taken from the first filled element: price, priceuah, pricerub, priceusd, pricekzt. currencyId sets the currency, and the feed's own currencies block sets the rate:

    • The product currency is in currencies — the price is converted to your base currency at the feed's rate.
    • The product currency's rate in the feed is 1, it isn't your base currency, and the feed has no rate for your base currency — the rate comes from your currency directory.
    • The product currency isn't in currencies — the price is imported without conversion, “as is”.

    How categories are built from the feed

    Elbuz builds the category tree from the categories block: each category with id and parentId attributes defines a category and its parent. A product is linked to a category by its categoryId.

    Without a category, no new card is created. A new offer enters the catalog only when its categoryId matches a category created from this file's categories block or earlier. With no block and no such categories, not a single new product is added, even though the log shows the full “Total items imported”: that's offers read, not cards created.

    Existing cards are updated normally by such a feed and keep their category.

    A run resets feed categories to the file's state. Rename a category in Elbuz, and the next import restores the feed's name. Move a product to another category, and the run moves it back if the feed specifies a category for it. Build your own structure for products the feed doesn't carry, or change it in the source itself.

    Deleting a category deletes the products for which it's the main one, with descriptions, photos, and attributes. The next run adds them again as different cards. Details: service categories and deleting a category with products.

    How to update the catalog from a link

    Once the template with a link is tested, put it on a schedule with the “Schedule setup” button on the template card. Elbuz will fetch the fresh feed and update prices, availability, and stock on its own. Choose the frequency based on the source: a feed that changes once a day doesn't need hourly imports.

    Only a link works on a schedule. The scheduler uses the address saved in the template; a file from your computer is a one-time manual operation. A template with only the file field filled in does nothing on a schedule.

    What the scheduler checks before running a template. If any of the three checks fails, the catalog doesn't change this time.
    yesnonoyesnoyesScheduled time arrivesIs another scheduledimport already running?The log shows “Scheduled importcanceled”Is the template “Active”?Template skippedIs the “Link to product file”field filled in the template?Nothing is importedThe file is fetched from the linkThe run goes the same wayas after the “Import” button
    • Start or end
    • Action or result
    • Decision: the path depends on the answer
    Template header with the run history icon, the state pill and the Import button
    1State pill
    2Run history
    3Import button
    1. Shows whether the template is active; the pill is shown as is.
    2. Opens the history of runs.
    3. Starts the import (not pressed).

    Pausing, run duration, and breaks

    • Pause. The “Disabled” badge in the template header stops the schedule; products and settings stay. Details: disable a template or delete it.
    • Duration. There's no cap on the number of offers; the file is read as a stream. The last run's duration is in the “Last import” column, and “Run history” shows the history. Details: run limits, how to check an import.
    • The log counter updates every thousand offers, so for a small feed the “Products received from file” line may be missing; “Total items imported” shows the total.
    • Break. What was written before the stop stays, and a rerun is safe if the id values in the feed don't change. Don't run two imports at the same time. Details: if a run broke off.

    What happens to a product that's no longer in the feed

    By default, nothing: a missing offer stays in the catalog with the same price, availability, and stock. Mirror mode is turned on by the “Delete entries in the base catalog that are not in the imported file” checkbox. It deletes cards permanently and, when the file has a categories block, also the categories that aren't in it.

    Without the “Check uniqueness of records based on this import source” checkbox, the entire catalog is subject to deletion, not just this template's products. If no products were read from the file, nothing is deleted. Details: a product disappeared from the source.

    The What to import checkboxes and the Schedule setup button
    1Delete entries not in the file
    2Check uniqueness per source
    3Schedule setup
    1. Removes catalog entries that are missing from the imported file.
    2. Checks record uniqueness taking this import source into account.
    3. Opens the schedule settings for this template.
    Three checks before deletion. The bottom fork decides which part of the catalog deletion goes through: without the uniqueness check flag, all of it.
    noyesnoyesnoyesDeletion stepIs “Delete entriesin the base catalog that are notin the imported file” on?Nothing is deletedWas at least one productread from the file?Cards are not deletedIs “Check uniquenessof records based onthis import source” on?The whole catalog is checkedThis template's cards and thoseaddedmanually, from a price list, or by theparser are checkedCards not in the file are deletedwith description, photos, andattributes
    • Start or end
    • Action or result
    • Decision: the path depends on the answer

    Scenarios

    A supplier provides a feed at a link, and prices and stock should update on their own

    What to turn on. In the template: “External link” and the feed address in the “Link to product file (Catalog)” field. Then “Schedule setup” in the “Related settings” block; the badge in the template header is “Active”.

    What you get. At the scheduled time, the scheduler fetches the file and runs the same import as the “Import” button. Products no longer in the fresh feed stay with their previous price and stock. If another scheduled import is running at that moment, the run is canceled with a line about a data processing conflict.

    The catalog must match the feed exactly

    What to turn on. In the “What to import” block: “Delete entries in the base catalog that are not in the imported file” and, together with it, “Check uniqueness of records based on this import source”.

    What you get. On every run, cards not in the file are deleted with description, photos, and attributes. The second checkbox protects products from other import templates; products added manually, from a price list, or by the parser are subject to deletion. Deleted items can't be restored. An inactive delete checkbox means your group lacks the right to it.

    Two suppliers number their products the same way

    What to turn on. “Check uniqueness of records based on this import source” in the templates of both feeds.

    What you get. Each template matches id against its own cards and those added manually, from a price list, or by the parser. An offer with the same id from the second feed is added as a separate card if its categoryId found a category. Cards merged before the checkbox was on won't split: they stay with the template that created them.

    You set the price yourself, and stock and availability come from the feed

    What to turn on. The “Fixed Price” flag on the product card.

    What you get. A run updates stock, stock status, part number, and other fields, but doesn't touch the price and old price. The feed overwrites the name and description. To protect the whole card from the feed, set “Do not update”.

    What to do when the feed didn't import as expected

    Common problems
    What you seeWhyWhat to do
    “The file could not be sent to the server. It may be too large or the connection was lost” The file from your computer didn't reach the server: the server's size limit or a lost connection Import the feed from a link — that limit doesn't apply there (updating from a link)
    “Total items imported: 0” The link returned something other than a feed — an error page or a sign-in form — or the file isn't YML Open the link in a browser and make sure it returns XML. The catalog wasn't affected (gone from the feed)
    The file has hundreds of offers, but no new cards were added No category was found for the new items: there's no categories block, or categoryId doesn't match Check the categories block in the feed (categories)
    Cyrillic text in names is garbled The file isn't in encoding Ask the source to provide the feed in UTF-8
    The price was imported in a foreign currency, without conversion The product currency isn't in the feed's currencies block Add the currency with its rate to the feed (currency and price)
    The XML was imported, but prices, photos, or names are empty The node names in the file aren't standard YML Import the file with universal import and your own mapping
    “Scheduled import canceled due to another template being imported (data processing conflict)” Another import was already running at that moment Spread template schedules apart in time (run breaks)
    “Operation aborted by user!” The stop button was pressed — by you or another employee Run the import again: a rerun is safe (run breaks)

    FAQ

    What's the difference between XML and YML?

    YML is an XML product feed format with a fixed structure, accepted by Rozetka, Prom, and others. A file with the YML structure (yml_catalog, offers, categories) is imported with the “XML” template without mapping. Arbitrary XML is imported with universal import.

    A supplier sent an XML file — should I import it into the catalog or as a price list?

    If the file describes your product range, import it into the catalog with the “XML” template. If it describes a supplier's range whose prices you need to compare and mark up, set up a price list (price list column mapping).

    Why don't the products have a description or specifications?

    Elbuz takes only what's in the feed. If an offer has no description or param, those fields stay empty. You can fill in the cards with the parser from third-party sites.

    How do I stop automatic updates without deleting anything?

    Switch the badge in the template header to “Disabled”. The scheduler skips the template, products, schedule, and settings stay, and the “Import” button keeps working (pause).

    Copies of products appear after every import. Why?

    The source gives offers new id values on every export. Ask the source to make the ids stable, and remove the copies (duplicates).

    Can I export my own catalog in YML format?

    Yes, that's a separate export template — export in YML (XML) format.

    Where to find it and who has access

    Menu
    Directories → Operations → Data import → an “XML” template
    Access right
    the “Import” window in “Group permissions”
    Have ready
    an .xml / .yml file or a direct link to the feed

    The template source is “Local file” or “External link”. Only a link works on a schedule.

    XML import template form with the data source switcher and the file field
    1Local file / External link switcher
    2File or link field
    1. Switch the data source between a local file and an external link.
    2. Pick the file here, or enter the address when the external link is selected.

    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