Co je to?

Poznámka pro administrátory: Toto je „překladový modul“ pro vaše data. Umožňuje systému rozumět souborům z různých zdrojů (jako je XML vašeho dodavatele nebo CSV vašeho starého systému) a mapovat tyto informace do správných polí ve vašem novém e-shopu.

Pro koho je to určeno? Administrátoři by si to měli přečíst, aby pochopili, jak platforma dokáže zpracovávat komplexní data od mnoha různých dodavatelů nebo systémů. Nicméně, psaní těchto mapovacích souborů vyžaduje technické znalosti datových struktur (jako XML nebo JSON) a mělo by být řešeno vývojářem nebo technickým konzultantem.

Klíčové výhody pro e-shop:

Snadná integrace: Připojte se k datovému kanálu libovolného dodavatele, bez ohledu na to, jak strukturoval své soubory.
Čištění dat: Automaticky opravujte nebo transformujte data, jakmile přicházejí (např. změna „1“ na „Aktivní“ nebo „Y“ na „Ano“).
Chytré vztahy: Automaticky propojujte produkty se správnými kategoriemi nebo výrobci na základě informací v souboru.
Automatizovaný pracovní postup: Jakmile je „mapa“ vytvořena, můžete ji znovu použít, kdykoli obdržíte nový soubor, což z aktualizací činí proces na jedno kliknutí.

Dokumentace Mapovače

Formát ParseMapper pro Mapovač a transformaci dat z různých zdrojů

Přehled

Formát ‘importu’ ParseMapper je konfigurační syntaxe pro Mapovač a transformaci dat z různých strukturovaných zdrojů (jako je XML, JSON, CSV atd.) do normalizované interní reprezentace. Tento formát se používá k definování toho, jak jsou pole ze zdrojových dat mapována, transformována a vztahována k cílovým entitám.

Klíčové komponenty

Definice proměnných Volitelné deklarace proměnných pomocí direktivy @variable

Deklarace typu Určuje typ zdrojových dat (XML, JSON, CSV atd.)

Globální direktivy Volitelná nastavení, která ovlivňují chování parsování

Mapování entit Definice pro extrahování a mapování entit a polí

Struktura souboru

Typický soubor mapování importu se skládá z definic proměnných, deklarace typu, globálních direktiv a mapování entit:

@variable default_vat_rate = {
    name: "Default VAT Rate"
    type: "number"
    defaultValue: "21"
}

type XML

@atomic = "false"
@strict = false
@language = "en"

products = '$.SHOP.SHOPITEM[*]' {
    id[code] = 'CODE'
    name = 'NAME'
    // ... more field mappings ...
    variants = 'VARIANTS.VARIANT' {
        code = 'CODE'
        // ... nested field mappings ...
        @removeAll = "true"
    }
    // ... more nested entities ...
}

Syntaxe cesty

Jednoduchá tečková cesta

Přímá tečková notace bez úvodního $ nebo @.

LOGISTIC.WEIGHT

Používá se pro přímý, statický přístup k polím

JSONPath

Výkonná syntaxe pro navigaci v JSON strukturách. Označeno úvodním $ nebo @.

$.SHOP.SHOPITEM[*]

Podporuje pokročilé selektory, zástupné znaky a přístup k polím

Odkaz na rodiče ($parent) [badge:New|secondary|right]

Přístup k polím z nadřazeného objektu ve vnořených strukturách pomocí předpony $parent.

$parent.orderId                 // Access parent field
$parent.customer.name           // Access nested parent field
$parent["field-name"]           // With special characters

Příklad použití:

orders = '$.orders[*]' {
    orderId = '$.id'
    items = '$.items[*]' {
        productName = '$.name'
        orderId = '$parent.id'
        orderDate = '$parent.date'
    }
}

Užitečné, když podřízené záznamy potřebují odkazovat na informace na úrovni rodiče

Více alternativních cest

Použijte operátor || k určení záložních cest. Použije se první cesta, která vrátí hodnotu.

name = '$.NAME' || '$.ALT_NAME' || "STATIC"

Referenční syntaxe

1. Deklarace typu

Definuje typ zdrojových dat:

type XML

Podporované typy: XML, JSON, CSV, YAML, XLSX, XLS

2. Globální direktivy

Ovládání chování parseru:

@atomic = "false"
@strict = false
@language = "en"

@atomic: Zda má být import atomický
@strict: Zda má být vynuceno striktní mapování
@language: Výchozí jazyk pro importy
@xml-const: Konstantní XML uzel nebo atribut přidaný při exportu (pouze XML, viz níže direktiva @xml-const)
Jakýkoli jiný @name = "value" (například @flavour, @name nebo @delimiter) je uchován jako metadata

3. Definice proměnných

Definujte proměnné pro konfigurovatelné parametry importu:

@variable default_vat_rate = {
    name: "Default VAT Rate"
    description: "Variable description"
    type: "number"
    defaultValue: "21"
}

Typy proměnných

“number” - Číselné hodnoty
“string” - Textové hodnoty
“boolean” - Pravda/nepravda
“relation” - Odkazy na entity

Přeložitelná pole

name:
  - en: "English Name"
  - cs: "Czech Name"

4. Mapování entit

Definujte, jak extrahovat entity ze zdrojových dat:

entityName = 'jsonpath' {
    field1 = 'SOURCE_FIELD'
    field2 = 'NESTED.PATH'
    manufacturer[code] = 'MANUFACTURER'
    status = "active"
    // ... more fields ...
}

Speciální funkce

Vyhledávací pole: field[key] = ‘SOURCE’
Statické hodnoty: field = “static”
Vnořené entity s @removeAll
Tabulky nahrazení polí
Tabulky nahrazení specifické pro cestu

Výrazy

total = ${price + vat}

Příklady

Import XML pro e-shop

Komplexní import XML s vnořenými entitami a vyhledávacími poli:

type XML

@atomic = "false"
@strict = false

products = '$.SHOP.SHOPITEM[*]' {
    id[code] = 'CODE'
    name = 'NAME'
    description = 'DESCRIPTION'
    unit[name] = 'UNIT'
    manufacturer[code] = 'MANUFACTURER'
    variants = 'VARIANTS.VARIANT' {
        code = 'CODE'
        priceWithVat = 'PRICE_VAT'
        @removeAll = "true"
    }
    images = 'IMAGES.IMAGE' {
        url = '_'
        description = '$["$"].description'
        @removeAll = "true"
    }
    categories = 'CATEGORIES' {
        category[id] = 'CATEGORY.$.id'
        category[name] = 'CATEGORY._'
        @removeAll = "true"
    }
}

Příklad nahrazení pole

Mapujte specifické zdrojové hodnoty na různé cílové hodnoty:

taxRateLevel = 'TAX_RATE_LEVEL' ['high' = 'standard', 'low' = 'reduced']
status = 'state' ['active' = 'enabled', 'inactive' = 'disabled']

Tabulky nahrazení specifické pro cestu [badge:New|secondary|right]

Aplikujte tabulky nahrazení na jednotlivé cesty ve výrazech s více cestami:

// Mixed: No replacement on first path, replacement on second path
visibility = 'VISIBILITY' || ('VISIBLE' ['1' = 'visible', '0' = 'hidden'])

// Individual: Different replacement tables for each path
status = ('STATUS' ['A' = 'active', 'I' = 'inactive']) || ('STATE' ['1' = 'enabled', '0' = 'disabled'])

// Backward compatible: Field-level replacement table (existing behavior)
type = 'TYPE' || 'TYPE_CODE' ['premium' = 'PREMIUM', 'basic' = 'STANDARD']

Smíšené globální/lokální Aplikujte nahrazení pouze na specifické cesty, zatímco ostatní ponechejte beze změny

Tabulky jednotlivých cest Každá cesta může mít svá vlastní pravidla transformace

Zpětně kompatibilní Stávající syntaxe na úrovni polí nadále funguje

Přeložitelná pole s dynamickými jazykovými klíči [badge:New|secondary|right]

Mapujte vícejazyčný obsah s dynamickým rozlišením jazykového klíče

Přeložitelná pole mohou dynamicky určovat cílový jazyk ze zdrojových dat, což umožňuje efektivní vícejazyčné importy z jednotlivých zdrojových záznamů.

Klíč jazyka jednoduché cesty

name['LANG'] = 'TEXT'

Jazykové pole ve stejném záznamu určuje jazyk

Klíč jazyka JSONPath

name['$.language.code'] = 'TEXT'

Použijte složité výrazy cesty k nalezení identifikátoru jazyka

Klíč statického jazyka

name["en"] = 'NAME_EN' || 'NAME'

Explicitně mapujte na konkrétní jazyk s náhradním řešením

Klíč jazyka výrazu

name[${LOWER(langCode)}] = 'TEXT'

Vypočítaný jazykový klíč pomocí výrazů

Kompletní příklad

products = '$.items[*]' {
    code = 'CODE'
    
    // Dynamic language keys from source data
    name['LANG'] = 'TEXT' @loop '$.TEXTS[*]'
    description['LANG'] = 'DESCRIPTION' @loop '$.TEXTS[*]'
    
    // Static language keys with fallback
    shortName["en"] = 'SHORT_NAME_EN' || 'NAME'
    shortName["cs"] = 'SHORT_NAME_CS' || 'NAME'
}

Direktiva @loop [badge:New|secondary|right]

Iterujte přes pole pro vytvoření více záznamů nebo překladů

Direktiva @loop umožňuje iterovat přes pole nebo kolekce ve zdrojových datech a vytvářet tak více záznamů, překladů nebo hodnot polí.

Základní syntaxe

fieldName = 'PATH' @loop 'ITERATION_PATH'

S přeložitelnými poli

name['lang'] = 'text' @loop '$.translations[*]'

Vytvořte více jazykových překladů z pole

Vytvoření pole

tags = 'tag' @loop '$.tags[*]'

Vytvořte pole z pole zdroje

Vnořené relace s @loop

images = '$.images[*]' @loop '$.images[*]' {
    url = 'url'
    description['lang'] = 'alt' @loop '$.alts[*]'
    sortOrder = 'position'
}

Iterujte přes pole obrázků a vytvořte více záznamů obrázků, každý s přeloženými popisy

Kompletní příklad

products = '$.products[*]' {
    code = 'sku'
    
    // Multi-language from translations array
    name['languageCode'] = 'title' @loop '$.translations[*]'
    description['languageCode'] = 'desc' @loop '$.translations[*]'
    
    // Simple array creation
    tags = 'tag' @loop '$.tags[*]'
    
    // Nested relations
    variants = '$.options[*]' @loop '$.options[*]' {
        code = 'optionSku'
        name['lang'] = 'optionName' @loop '$.optionTranslations[*]'
        priceWithVat = 'optionPrice'
    }
}

Formáty výstupu přeložitelných polí [badge:Important|secondary|right]

Dva podporované formáty pro výstup přeložitelných polí

Mapovač podporuje dva výstupní formáty pro přeložitelná pole, v závislosti na tom, jak strukturováte své mapování.

Formát objektu (s @loop) [badge:Recommended|default|right]

// Mapper syntax
name['LANG'] = 'TEXT' @loop 'TEXTS.ITEM'

// Output
{
  "name": {
    "en": "English Name",
    "cs": "České jméno",
    "de": "Deutscher Name"
  }
}

✅ Čistá, plochá struktura ✅ Lepší výkon pro vyhledávání ✅ Snadnější práce v uživatelském rozhraní ✅ Doporučeno pro většinu případů použití

Formát pole (bez @loop) [badge:Alternative|outline|right]

// Mapper syntax
name = 'TEXTS.ITEM' {
    language = 'LANG'
    value = 'TEXT'
}

// Output
{
  "name": [
    {"language": "en", "value": "English Name"},
    {"language": "cs", "value": "České jméno"},
    {"language": "de", "value": "Deutscher Name"}
  ]
}

• Strukturovaný formát metadat • Může obsahovat další pole • Používá se pro systémy založené na polích • Zpětná kompatibilita

Kompletní příklad: Oba formáty

type XML

products = '$.SHOP.PRODUCT[*]' {
    code = 'CODE'
    
    // Object format - recommended
    name['$.language'] = 'title' @loop 'DESCRIPTIONS.DESC'
    description['$.language'] = 'text' @loop 'DESCRIPTIONS.DESC'
    
    // Array format - alternative
    alternativeName = 'DESCRIPTIONS.DESC' {
        language = '$.language'
        value = 'title'
    }
}

Kdy použít který formát

Použijte formát objektu (@loop):

Nejběžnější scénář – čisté překlady
Lepší integrace uživatelského rozhraní a výkon
Standardní přístup pro nové projekty

Použijte formát pole (vnořený):

Je třeba ukládat metadata s překlady
Migrace ze systémů založených na polích
Další pole nad rámec jazyka/hodnoty

Direktiva @if [badge:New|secondary|right]

Podmíněné zahrnutí polí na základě podmínek za běhu

Direktiva @if umožňuje podmíněně zahrnout pole nebo relace na základě podmínek za běhu vyhodnocených ze zdrojových dat.

Základní syntaxe

fieldName = 'PATH' @if ${condition}

Jednoduchá podmínka

discount = 'DISCOUNT' @if ${hasDiscount == 'true'}

Zahrnout slevu pouze v případě, že ji produkt má

Složitá podmínka

price = 'BULK_PRICE' @if ${isB2B == 'true' && price > 100}

Více podmínek s operátory AND/OR

Podporované operátory

Porovnání ==, !=, >, <, >=, <=

Logické && (AND), || (OR)

Typy řetězce, čísla, booleany

Podmíněné vnořené relace

// Only create images if product has them
images = '$.images[*]' @loop '$.images[*]' @if ${hasImages == 'true'} {
    url = 'url'
    description = 'alt'
    sortOrder = 'position'
}

Kompletní příklad

products = '$.products[*]' {
    code = 'sku'
    name = 'title'
    basePrice = 'price'
    
    // Conditional fields
    discount = 'discountPercent' @if ${hasDiscount == 'true'}
    weight = 'weightKg' @if ${isPhysical == 'true'}
    downloadUrl = 'fileUrl' @if ${isDigital == 'true'}
    
    // Extended description only for premium products
    extendedDesc = 'detailedText' @if ${productType === 'premium'}
    
    // Conditional relations
    variants = '$.options[*]' @loop '$.options[*]' @if ${isConfigurable == 'true'} {
        code = 'optionSku'
        priceWithVat = 'optionPrice'
    }
}

Kombinace @loop a @if [badge:Advanced|secondary|right]

Kombinujte direktivy pro výkonné podmíněné zpracování polí

Direktivy @loop a @if můžete kombinovat pro sofistikované podmíněné zpracování a filtrování polí.

Podmíněný vícejazyčný import

products = '$.items[*]' {
    code = 'CODE'
    
    // Import translations only if available
    name['LANG'] = 'TEXT' @loop '$.TEXTS[*]' @if ${HAS_TRANSLATIONS == 'true'}
    description['LANG'] = 'DESC' @loop '$.TEXTS[*]' @if ${HAS_TRANSLATIONS == 'true'}
    
    // Fallback if no translations
    name = 'NAME' @if ${HAS_TRANSLATIONS != 'true'}
    description = 'DESCRIPTION' @if ${HAS_TRANSLATIONS != 'true'}
}

Filtrované zpracování polí

products = '$.products[*]' {
    code = 'sku'
    name['lang'] = 'title' @loop '$.translations[*]'
    
    // Only import images if product has them
    images = '$.images[*]' @loop '$.images[*]' @if ${hasImages == 'true'} {
        url = 'url'
        description['lang'] = 'alt' @loop '$.alts[*]'
        sortOrder = 'position'
    }
    
    // Specifications only for electronics
    specifications = '$.specs[*]' @loop '$.specs[*]' @if ${category === 'electronics'} {
        name['lang'] = 'specName' @loop '$.nameTranslations[*]'
        value = 'specValue'
        unit = 'specUnit'
    }
}

Osvědčené postupy

Použijte @if před @loop, pokud je to možné, pro včasné filtrování
Udržujte podmínky jednoduché a testovatelné
Testujte s reprezentativními vzorovými daty
Vyhněte se hluboce vnořeným smyčkám (max. 2-3 úrovně)
Dokumentujte složitou obchodní logiku pomocí komentářů

Syntaxe pole pro pole kolekcí [badge:New|secondary|right]

Připojte více hodnot k polím kolekcí z nezávislých zdrojů

Syntaxe pole (fieldName[]) umožňuje připojit více hodnot ke stejnému poli kolekce, namísto jeho nahrazení. To je zvláště užitečné, když potřebujete naplnit pole z více nezávislých zdrojů nebo podmínek.

Základní syntaxe

fieldName[] = 'PATH' {
    // field mappings
}

Když použijete příponu [] u názvu pole, každá událost se připojí ke kolekci, namísto nahrazení předchozích hodnot.

Problém: Vícenásobné přiřazení

Bez syntaxe pole nelze přiřadit stejnému poli vícekrát:

❌ Not Supported - Parser Error

flags = 'LABELS.LABEL' {
    flag[code, name] = 'NAME'
}
flags = {
    flag[code] = 'new'
} @if ${NEW_YN === '1'}
flags = {
    flag[code] = 'special'
} @if ${SPECIAL_YN === '1'}

Řešení: Syntaxe pole

✅ Correct - Appends to Collection

// First clear existing flags
flags = 'LABELS.LABEL' {
    flag[code, name] = 'NAME'
    @removeAll = "true"
}

// Then append conditionally
flags[] = {
    flag[code] = 'new'
} @if ${NEW_YN === '1'}

flags[] = {
    flag[code] = 'special'
} @if ${SPECIAL_YN === '1'}

flags[] = {
    flag[code] = 'sellout'
} @if ${SELLOUT_YN === '1'}

Kompletní příklad s @removeAll

Běžným vzorem je nejprve vymazat existující data a poté připojit nové položky:

products = '$.SHOP.SHOPITEM[*]' {
    code = 'CODE'
    
    // First, clear all existing flags and import from primary source
    flags = 'LABELS.LABEL' {
        flag[code, name] = 'NAME'
        @removeAll = "true"
    }
    
    // Then append additional flags based on conditions
    flags[] = {
        flag[code] = 'new'
        flag[name] = 'New Product'
    } @if ${NEW_PRODUCT === 'true'}
    
    flags[] = {
        flag[code] = 'clearance'
        flag[name] = 'Clearance Sale'
    } @if ${CLEARANCE === 'true'}
}

Syntaxe pole s jednoduchými hodnotami

products = '$.products[*]' {
    code = 'id'
    
    // Base tags from primary field
    tags[] = 'primaryTag'
    
    // Add category-based tags
    tags[] = 'electronics' @if ${category === 'ELECTRONICS'}
    tags[] = 'apparel' @if ${category === 'CLOTHING'}
    
    // Add promotional tags
    tags[] = 'featured' @if ${isFeatured == 'true'}
    tags[] = 'bestseller' @if ${salesRank <= 10}
}

Kdy použít syntaxi pole

✅ Použijte syntaxi pole, když:

Více nezávislých zdrojů
Podmíněné doplňky
Inkrementální sestavování
Smíšená statická a dynamická data

❌ Nepoužívejte, když:

Jeden zdroj (použijte @loop)
Chcete nahradit, nikoli připojit
Jednoduché jedno přiřazení

Osvědčené postupy

Nejprve vyčistit, poté připojit: Použijte @removeAll při prvním přiřazení, poté použijte [] pro následné doplňky
Použijte @if pro podmíněné položky: Kombinujte s direktivou @if pro přidání položek pouze tehdy, když jsou splněny podmínky
Udržujte pořadí řazení: Zvažte přidání explicitních polí pro pořadí řazení při použití syntaxe pole s více zdroji
Důkladně testujte: Ověřte, že všechny položky pole jsou správně vytvořeny pomocí vzorových dat

Direktivy pro vyhledávací pole [badge:New|secondary|right]

Ovládejte chování a zachycujte chybějící data při řešení vyhledávacích polí

Při mapování vyhledávacích polí (relací) tyto direktivy řídí, co se stane, když nelze vyřešit odkaz, a umožňují shromažďovat data pro vytváření chybějících záznamů.

Direktiva @if-not-found

Řídí chování, když nelze v databázi najít odkaz na vyhledávací pole.

skip Přeskočit celý záznam (výchozí)

create Shromažďovat data pro vytváření chybějících záznamů

ignore Ponechat pole prázdné, pokračovat ve zpracování

error Vyvolat chybu, zastavit import

products = '$.SHOPITEM[*]' {
    code = 'CODE'
    name = 'NAME'
    
    // Skip entire product if manufacturer not found (default)
    manufacturer[code] = 'MANUFACTURER_CODE'
    
    // Collect data to create missing categories
    category[code]@if-not-found = 'create' = 'CATEGORY_ID'
    
    // Continue even if unit not found (field will be null)
    unit[name]@if-not-found = 'ignore' = 'UNIT_NAME'
}

Direktiva @create-as

Při použití @if-not-found='create' tato direktiva určuje, jaká data se mají shromažďovat pro vytváření chybějících vyhledávacích záznamů.

products = '$.SHOPITEM[*]' {
    code = 'CODE'
    name = 'NAME'
    
    // Collect category data for creation if not found
    category[code]@if-not-found = 'create' = 'CATEGORY_ID'
    category[code]@create-as = {
        code = 'CATEGORY_ID'
        name = 'CATEGORY_TITLE'
        description = 'CATEGORY_DESC' || 'CATEGORY_TITLE'
        sortOrder = 'CATEGORY_ORDER'
    }
}

Pokročilé příklady

Alternativní cesty a nahrazovací tabulky

category[code]@if-not-found = 'create' = 'CATEGORY_ID' || 'CATEGORY_CODE'
category[code]@create-as = {
    code = 'CATEGORY_ID' || 'CATEGORY_CODE'
    name = 'CATEGORY_NAME' || 'CATEGORY_TITLE' || 'CATEGORY_ID'
    type = 'CATEGORY_TYPE' ['MAIN' = 'primary', 'SUB' = 'secondary']
}

Statické hodnoty

manufacturer[code]@if-not-found = 'create' = 'MANUFACTURER_CODE'
manufacturer[code]@create-as = {
    code = 'MANUFACTURER_CODE'
    name = 'MANUFACTURER_NAME'
    country = "CZ"
    isActive = "true"
}

Vnořené relace

products = '$.SHOPITEM[*]' {
    code = 'CODE'
    name = 'NAME'
    
    category[code]@if-not-found = 'create' = 'CATEGORY_ID'
    category[code]@create-as = {
        code = 'CATEGORY_ID'
        name = 'CATEGORY_NAME'
        
        // Nested relations in create-as block
        productPrices = 'PRICES.PRICE' {
            priceWithVat = 'PRICE_VAT'
            priceWithoutVat = 'PRICE_BASE'
            validFrom = 'DATE_FROM'
            @removeAll = "true"
        }
    }
}

Jak to funguje

Během importu se systém pokusí vyřešit každý odkaz na vyhledávací pole
Pokud není nalezen a @if-not-found='create', data se shromáždí
Shromážděná data se uloží s klíčem fieldName@create-as
Importní úloha obsahuje jak importované záznamy, tak data pro vytvoření
Poté můžete vytvořit chybějící záznamy a import znovu spustit

Doporučené postupy

Použijte create pro kritické odkazy, jako jsou kategorie, výrobci
Použijte ignore pro volitelná pole, která lze vyplnit později
Použijte skip, když chybějící odkazy indikují neplatná data
Použijte error, když musí být zaručena kvalita dat
Poskytněte alternativní cesty a záložní možnosti v blocích @create-as
Zahrňte dostatek polí pro vytvoření platných záznamů (zkontrolujte požadavky metamodelu)
Testujte s daty obsahujícími chybějící odkazy

Odkaz na rodiče ($parent) [badge:New|secondary|right]

Přístup k polím rodičovského objektu ve vnořených strukturách

Při práci s vnořenými entitami můžete odkazovat na pole z rodičovského objektu pomocí předpony $parent. To je obzvláště užitečné, když podřízené záznamy potřebují zahrnovat informace z jejich rodičovské úrovně.

Syntaxe

$parent.field                   // Direct parent field
$parent.nested.field            // Nested parent field
$parent["field-name"]           // With special chars

Příklad: Položky objednávky s informacemi o rodičovské objednávce

type JSON

orders = '$.orders[*]' {
    orderId = '$.id'
    orderDate = '$.date'
    customer = '$.customer'
    
    items = '$.items[*]' {
        productName = '$.name'
        price = '$.price'
        quantity = '$.quantity'
        // Reference parent order fields
        orderId = '$parent.id'
        orderDate = '$parent.date'
        orderCustomer = '$parent.customer'
    }
}

Každá položka bude obsahovat orderId, orderDate a orderCustomer z rodičovského objektu objednávky.

Příklad: Varianty Produktu s informacemi o rodičovském Produktu

products = '$.products[*]' {
    productId = '$.id'
    productName = '$.name'
    category = '$.category'
    brand = '$.brand'
    
    variants = '$.variants[*]' {
        variantCode = '$.sku'
        variantSize = '$.size'
        variantColor = '$.color'
        stockLevel = '$.stock'
        // Include parent product information
        productId = '$parent.id'
        productName = '$parent.name'
        category = '$parent.category'
        brand = '$parent.brand'
    }
}

Příklad: Položky faktury

invoices = '$.invoices[*]' {
    invoiceNumber = '$.number'
    invoiceDate = '$.date'
    currency = '$.currency'
    customer[code] = '$.customer.code'
    
    lineItems = '$.lines[*]' {
        itemCode = '$.code'
        description = '$.description'
        amount = '$.amount'
        quantity = '$.qty'
        // Reference parent invoice data
        invoiceNumber = '$parent.number'
        invoiceDate = '$parent.date'
        currency = '$parent.currency'
        customerCode = '$parent.customer.code'
    }
}

Důležité poznámky

$parent odkazuje na bezprostřední rodičovský objekt v hierarchii mapování
Rodičovský kontext je dostupný pouze ve vnořených strukturách (objekty s vnořenými mapováními polí)
Pokud je použit na kořenové úrovni, kde neexistuje rodič, pole bude nedefinované
V direktivách @loop se položka smyčky stane aktuálním zdrojem a původní zdroj se stane rodičem
Můžete přistupovat k vnořeným rodičovským polím: $parent.customer.name

Případy použití

Denormalizace Zahrňte rodičovské informace do podřízených záznamů pro snazší dotazování a reportování

Obohacení dat Přidejte kontext z rodičovských entit, aby podřízené záznamy byly soběstačné

Sledování referencí Udržujte reference mezi souvisejícími záznamy pro integritu dat

Auditní záznam Zahrňte časová razítka a identifikátory na úrovni rodiče do podřízených záznamů

Direktiva @xml-const [badge:New|secondary|right]

Přidat konstantní XML uzly a atributy do exportovaných dokumentů

Některé formáty XML vyžadují uzly nebo atributy, které nemají protějšek ve vašich datech, například atribut verze na kořenovém prvku nebo tag s pevným formátem. Direktiva @xml-const je deklaruje v mapovači, aby je export (zpětné mapování) mohl zahrnout. Import je ignoruje.

Základní syntaxe

@xml-const 'path' = "value"

Cesta je tečkovaný seznam názvů prvků. Segment začínající znakem @ je atribut a musí být posledním segmentem. Direktiva může být opakována a funguje pouze s type XML.

Globální konstanty

Umístěná za deklarací typu je cesta absolutní od kořene dokumentu:

type XML

@xml-const 'PRODUCTS.@version' = "2"
@xml-const 'PRODUCTS.GENERATOR' = "{productName}"

Výsledek: <PRODUCTS version="2"> obsahující <GENERATOR>{productName}</GENERATOR>

Konstanty uvnitř bloku entity

Uvnitř bloku je cesta relativní k prvku bloku a samotné @name je atributem samotného prvku bloku:

products = '$.PRODUCTS.PRODUCT[*]' {
    @xml-const '@type' = "full"
    code = 'CODE'
    @xml-const 'FORMAT' = "2"
    name = 'NAME'
    price = 'PRICES.PRICE'
    @xml-const 'PRICES.PRICE.@currency' = "CZK"
}

Konstanta si zachovává svou pozici mezi poli, takže FORMAT je umístěn mezi CODE a NAME. To pomáhá u formátů, které vyžadují striktní pořadí prvků.

Pravidla

Mapovaná data mají přednost: konstanta vyplňuje pouze uzel nebo atribut, který mapování nevygenerovalo
Konstanty se nikdy neimportují a nikdy se nezobrazují jako sloupce
Použití @xml-const s jiným než XML typem, segmentem atributu, který není poslední, nebo samotným @name mimo blok je syntaktická chyba
Editor mapovače zobrazuje konstanty jako řádky @xml-const a zachovává je při přeformátování mapovače

Tipy a doporučené postupy

Tipy pro syntaxi

Použijte jednoduché uvozovky pro cesty ke zdrojům
Použijte dvojité uvozovky pro statické hodnoty
Použijte vnořené bloky pro pole/objekty
Přidejte @removeAll pro vnořené entity
Použijte syntaxi JSONPath ($.path[*]) v @loop
Použijte $parent pro odkazování na rodičovská pole ve vnořených strukturách
Udržujte podmínky @if jednoduché

Další kroky

Jakmile budete mít připravené šablony mapování, naučte se, jak naplánovat Automatický import z externích URL.

[navigate:/help/en/user-flows/automatic-imports|Pokračovat na Automatický import|refresh-cw]

Související články

[navigate:/help/en/api/imports|Dokumentace importního systému|upload]
[navigate:/help/en/user-flows/data-migration|Průvodce migrací dat|upload]
[navigate:/help/en/user-flows/ai-mapping|Automatické mapování sloupců dodavatele|bot]