Čo je to?

Poznámka pre administrátora: Toto je „prekladový nástroj“ pre vaše dáta. Umožňuje systému porozumieť súborom z rôznych zdrojov (ako je XML vášho dodávateľa alebo CSV vášho starého systému) a namapovať tieto informácie do správnych polí vo vašom novom e-shope.

Pre koho je to určené? Administrátori by si to mali prečítať, aby pochopili, ako platforma dokáže spracovať komplexné dáta od mnohých rôznych dodávateľov alebo systémov. Avšak, písanie týchto mapovacích súborov si vyžaduje technické znalosti dátových štruktúr (ako XML alebo JSON) a malo by byť riešené vývojárom alebo technickým konzultantom.

Kľúčové výhody pre e-shop:

Bezproblémová integrácia: Pripojte sa k dátovému kanálu akéhokoľvek dodávateľa, bez ohľadu na to, ako štruktúruje svoje súbory.
Čistenie dát: Automaticky opravte alebo transformujte dáta pri ich príchode (napr. zmena „1“ na „Aktívne“ alebo „Y“ na „Áno“).
Inteligentné vzťahy: Automaticky prepojte produkty so správnymi kategóriami alebo výrobcami na základe informácií v súbore.
Automatizovaný pracovný postup: Po vytvorení „mapy“ ju môžete opätovne použiť vždy, keď dostanete nový súbor, čím sa aktualizácie stanú procesom na jedno kliknutie.

Dokumentácia Mapovača

Formát ParseMapper pre Mapovač a transformáciu dát z rôznych zdrojov

Prehľad

Formát ParseMapper ‘import’ je konfiguračná syntax pre Mapovač a transformáciu dát z rôznych štruktúrovaných zdrojov (ako sú XML, JSON, CSV atď.) do normalizovanej internej reprezentácie. Tento formát sa používa na definovanie toho, ako sú polia zo zdrojových dát mapované, transformované a vzťahujúce sa k cieľovým entitám.

Kľúčové komponenty

Definície premenných Voliteľné deklarácie premenných pomocou direktívy @variable

Deklarácia typu Špecifikuje typ zdrojových dát (XML, JSON, CSV atď.)

Globálne direktívy Voliteľné nastavenia, ktoré ovplyvňujú správanie pri parsovaní

Mapovanie entít Definície pre extrakciu a mapovanie entít a polí

Štruktúra súboru

Typický súbor mapovania importu pozostáva z definícií premenných, deklarácie typu, globálnych direktív a mapovania entít:

@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 ...
}

Syntax cesty

Jednoduchá bodková cesta

Priama bodková notácia bez úvodného $ alebo @.

LOGISTIC.WEIGHT

Používa sa pre priamy, statický prístup k poľu

JSONPath

Výkonná syntax pre navigáciu v štruktúrach JSON. Označuje sa úvodným $ alebo @.

$.SHOP.SHOPITEM[*]

Podporuje pokročilé selektory, zástupné znaky a prístup k poliam

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

Prístup k poliam z rodičovského objektu v vnorených štruktúrach pomocou predpony $parent.

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

Príklad použitia:

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

Užitočné, keď podradené záznamy potrebujú odkazovať na informácie na úrovni rodiča

Viacnásobné alternatívy cesty

Použite operátor || na určenie záložných ciest. Použije sa prvá cesta, ktorá vráti hodnotu.

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

Referencia syntaxe

1. Deklarácia typu

Definuje typ zdrojových dát:

type XML

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

2. Globálne direktívy

Ovládanie správania parsera:

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

@atomic: Či má byť import atomický
@strict: Či vynútiť prísne mapovanie
@language: Predvolený jazyk pre importy
@xml-const: Konštantný XML uzol alebo atribút pridaný pri exporte (iba XML, pozri smernicu @xml-const nižšie)
Akýkoľvek iný @name = "value" (napríklad @flavour, @name alebo @delimiter) sa uchováva ako metadáta

3. Definície premenných

Definujte premenné pre konfigurovateľné parametre importu:

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

Typy premenných

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

Preložiteľné polia

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

4. Mapovanie entít

Definujte, ako extrahovať entity zo zdrojových dát:

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

Špeciálne funkcie

Vyhľadávacie polia: field[key] = ‘SOURCE’
Statické hodnoty: field = “static”
Vnorené entity s @removeAll
Tabuľky nahradenia polí
Tabuľky nahradenia špecifické pre cestu

Výrazy

total = ${price + vat}

Príklady

Import XML pre e-shop

Komplexný import XML s vnorenými entitami a vyhľadávacími poľami:

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"
    }
}

Príklad nahradenia poľa

Mapujte špecifické zdrojové hodnoty na rôzne cieľové hodnoty:

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

Tabuľky nahradenia špecifické pre cestu [badge:New|secondary|right]

Použite tabuľky nahradenia na jednotlivé cesty vo viacnásobných výrazoch cesty:

// 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']

Zmiešané globálne/lokálne Použite nahradenie len pre špecifické cesty, zatiaľ čo ostatné zostanú nezmenené

Tabuľky pre jednotlivé cesty Každá cesta môže mať vlastné transformačné pravidlá

Spätne kompatibilné Existujúca syntax na úrovni poľa naďalej funguje

Preložiteľné polia s dynamickými jazykovými kľúčmi [badge:New|secondary|right]

Mapujte viacjazyčný obsah s dynamickým rozlíšením jazykového kľúča

Preložiteľné polia môžu dynamicky určiť cieľový jazyk zo zdrojových dát, čo umožňuje efektívne viacjazyčné importy z jedného zdrojového záznamu.

Kľúč jazyka pre jednoduchú cestu

name['LANG'] = 'TEXT'

Jazykové pole v rovnakom zázname určuje jazyk

Kľúč jazyka JSONPath

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

Použite komplexné výrazy cesty na nájdenie identifikátora jazyka

Kľúč statického jazyka

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

Explicitne mapujte na konkrétny jazyk so záložným riešením

Kľúč jazyka výrazu

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

Vypočítaný kľúč jazyka pomocou výrazov

Kompletný prí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'
}

Direktíva @loop [badge:New|secondary|right]

Iterujte cez polia na vytvorenie viacerých záznamov alebo prekladov

Direktíva @loop vám umožňuje iterovať cez polia alebo kolekcie v zdrojových dátach a vytvárať tak viacero záznamov, prekladov alebo hodnôt polí.

Základná syntax

fieldName = 'PATH' @loop 'ITERATION_PATH'

S preložiteľnými poľami

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

Vytvorte viacero jazykových prekladov z poľa

Vytvorenie poľa

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

Vytvorte pole z poľa zdroja

Vnorené vzťahy s @loop

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

Iterujte cez pole obrázkov na vytvorenie viacerých záznamov obrázkov, každý s preloženými popismi

Kompletný prí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 preložiteľných polí [badge:Important|secondary|right]

Dva podporované formáty pre výstup preložiteľných polí

Mapovač podporuje dva výstupné formáty pre preložiteľné polia, v závislosti od toho, ako štruktúrujete svoje mapovanie.

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á štruktúra ✅ Lepší výkon pri vyhľadávaní ✅ Jednoduchšia práca v používateľskom rozhraní ✅ Odporúčané pre väčšinu prípadov použitia

Formát poľa (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"}
  ]
}

• Štruktúrovaný formát metadát • Môže obsahovať dodatočné polia • Používa sa pre systémy založené na poliach • Kompatibilita so staršími verziami

Kompletný prí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'
    }
}

Kedy použiť ktorý formát

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

Najbežnejší scenár – čisté preklady
Lepšia integrácia a výkon používateľského rozhrania
Štandardný prístup pre nové projekty

Použite formát poľa (vnorený):

Potreba ukladať metadáta s prekladmi
Migrácia zo systémov založených na poliach
Dodatočné polia nad rámec jazyka/hodnoty

Direktíva @if [badge:New|secondary|right]

Podmienečne zahrňte polia na základe podmienok za behu

Direktíva @if vám umožňuje podmienečne zahrnúť polia alebo vzťahy na základe podmienok za behu vyhodnotených zo zdrojových dát.

Základná syntax

fieldName = 'PATH' @if ${condition}

Jednoduchá podmienka

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

Zahrňte zľavu iba vtedy, ak ju produkt má

Komplexná podmienka

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

Viacero podmienok s operátormi AND/OR

Podporované operátory

Porovnanie ==, !=, >, <, >=, <=

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

Typy reťazce, čísla, booleany

Podmienečné vnorené vzťahy

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

Kompletný prí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'
    }
}

Kombinácia @loop a @if [badge:Advanced|secondary|right]

Skombinujte direktívy pre výkonné podmienečné spracovanie polí

Direktívy @loop a @if môžete kombinovať pre sofistikované podmienečné spracovanie a filtrovanie polí.

Podmienečný viacjazyč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é spracovanie 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'
    }
}

Osvedčené postupy

Použite @if pred @loop, ak je to možné, na včasné filtrovanie
Udržujte podmienky jednoduché a testovateľné
Testujte s reprezentatívnymi vzorovými dátami
Vyhnite sa hlboko vnoreným cyklom (max. 2-3 úrovne)
Dokumentujte komplexnú obchodnú logiku pomocou komentárov

Syntax poľa pre polia kolekcií [badge:New|secondary|right]

Pripojte viacero hodnôt k poliam kolekcií z nezávislých zdrojov

Syntax poľa (fieldName[]) vám umožňuje pripojiť viacero hodnôt k rovnakému poľu kolekcie, namiesto jeho nahradenia. To je obzvlášť užitočné, keď potrebujete naplniť pole z viacerých nezávislých zdrojov alebo podmienok.

Základná syntax

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

Keď použijete príponu [] na názve poľa, každá inštancia sa pripojí ku kolekcii namiesto nahradenia predchádzajúcich hodnôt.

Problém: Viacnásobné priradenia

Bez syntaxe poľa nemôžete priradiť hodnotu k rovnakému poľu viackrá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'}

Riešenie: Syntax poľa

✅ 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ý príklad s @removeAll

Bežným vzorom je najprv vymazať existujúce dáta a potom pripojiť 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'}
}

Syntax poľa 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}
}

Kedy použiť syntax poľa

✅ Použite syntax poľa, keď:

Viacero nezávislých zdrojov
Podmienečné pridávanie
Inkrementálne vytváranie
Zmiešané statické a dynamické dáta

❌ Nepoužívajte, keď:

Jeden zdroj (použite @loop)
Chcete nahradiť namiesto pripojenia
Jednoduché jedno priradenie

Osvedčené postupy

Najprv vymazať, potom pripojiť: Použite @removeAll pri prvom priradení, potom použite [] pre následné pridania
Použite @if pre podmienečné položky: Skombinujte s direktívou @if na pridanie položiek iba vtedy, keď sú splnené podmienky
Zachovať poradie zoradenia: Zvážte pridanie explicitných polí poradia zoradenia pri použití syntaxe poľa s viacerými zdrojmi
Dôkladne testovať: Overte, či sú všetky položky poľa vytvorené správne so vzorovými dátami

Smernice pre vyhľadávacie polia [badge:Nové|secondary|right]

Kontrolujte správanie a zachytávajte chýbajúce dáta pri riešení vyhľadávacích polí

Pri mapovaní vyhľadávacích polí (vzťahov) tieto smernice riadia, čo sa stane, keď odkaz nemožno vyriešiť, a umožňujú vám zbierať dáta na vytváranie chýbajúcich záznamov.

Smernica @if-not-found

Riadi správanie, keď odkaz na vyhľadávacie pole nemožno nájsť v databáze.

preskočiť Preskočiť celý záznam (predvolené)

vytvoriť Zbierať dáta na vytváranie chýbajúcich záznamov

ignorovať Ponechať pole nulové, pokračovať v spracovaní

chyba Vyvolať chybu, zastaviť 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'
}

Smernica @create-as

Pri použití @if-not-found='create' táto smernica určuje, aké dáta sa majú zbierať na vytváranie chýbajúcich vyhľadávacích záznamov.

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é príklady

Alternatívne cesty a náhradné tabuľky

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"
}

Vnorené vzťahy

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"
        }
    }
}

Ako to funguje

Počas importu sa systém pokúsi vyriešiť každý odkaz na vyhľadávacie pole
Ak sa nenájde a @if-not-found='create', dáta sa zbierajú
Zozbierané dáta sú uložené s kľúčom fieldName@create-as
Importná úloha obsahuje importované záznamy aj dáta na vytvorenie
Potom môžete vytvoriť chýbajúce záznamy a znova spustiť import

Osvedčené postupy

Použite create pre kritické odkazy ako kategórie, výrobcovia
Použite ignore pre voliteľné polia, ktoré je možné vyplniť neskôr
Použite skip, keď chýbajúce odkazy naznačujú neplatné dáta
Použite error, keď musí byť zaručená kvalita dát
Poskytnite alternatívne cesty a záložné možnosti v blokoch @create-as
Zahrňte dostatok polí na vytvorenie platných záznamov (skontrolujte požiadavky metamodelu)
Testujte s dátami obsahujúcimi chýbajúce odkazy

Odkaz na rodiča ($parent) [badge:Nové|secondary|right]

Prístup k poliam rodičovského objektu vo vnorených štruktúrach

Pri práci s vnorenými entitami môžete odkazovať na polia z rodičovského objektu pomocou predpony $parent. To je obzvlášť užitočné, keď podradené záznamy potrebujú zahrnúť informácie z ich rodičovskej úrovne.

Syntax

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

Príklad: Položky objednávky s informáciami o rodičovskej objednávke

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 obsahovať orderId, orderDate a orderCustomer z rodičovského objektu objednávky.

Príklad: Varianty produktu s informáciami o rodičovskom produkte

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'
    }
}

Príklad: Položky faktúry

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 bezprostredný rodičovský objekt v hierarchii mapovania
Rodičovský kontext je dostupný iba vo vnorených štruktúrach (objekty s vnorenými mapovaniami polí)
Ak sa použije na koreňovej úrovni, kde neexistuje rodič, pole bude nedefinované
V smerniciach @loop sa položka slučky stáva aktuálnym zdrojom a pôvodný zdroj sa stáva rodičom
Môžete pristupovať k vnoreným rodičovským poliam: $parent.customer.name

Prípady použitia

Denormalizácia Zahrňte informácie o rodičovi do podradených záznamov pre jednoduchšie dopytovanie a reportovanie

Obohatenie dát Pridajte kontext z rodičovských entít, aby boli podradené záznamy samostatné

Sledovanie odkazov Udržiavajte odkazy medzi súvisiacimi záznamami pre integritu dát

Auditná stopa Zahrňte časové pečiatky a identifikátory na úrovni rodiča do podradených záznamov

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

Pridajte konštantné XML uzly a atribúty do exportovaných dokumentov

Niektoré formáty XML vyžadujú uzly alebo atribúty, ktoré nemajú ekvivalent vo vašich dátach, napríklad atribút verzie na koreňovom prvku alebo značku s pevným formátom. Smernica @xml-const ich deklaruje v mapovači, aby ich export (reverzné mapovanie) mohol zahrnúť. Import ich ignoruje.

Základná syntax

@xml-const 'path' = "value"

Cesta je bodkovaný zoznam názvov prvkov. Segment začínajúci znakom @ je atribút a musí byť posledným segmentom. Smernica sa môže opakovať a funguje iba s type XML.

Globálne konštanty

Umiestnená za deklaráciou typu, je cesta absolútna od koreňa dokumentu:

type XML

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

Výsledok: <PRODUCTS version="2"> obsahujúci <GENERATOR>{productName}</GENERATOR>

Konštanty vo vnútri bloku entity

Vo vnútri bloku je cesta relatívna k prvku bloku a samotné @name je atribútom 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"
}

Konštanta si zachováva svoju pozíciu medzi poľami, takže FORMAT je umiestnený medzi CODE a NAME. To pomáha pri formátoch, ktoré vyžadujú prísne poradie prvkov.

Pravidlá

Mapované dáta vyhrávajú: konštanta vyplní iba uzol alebo atribút, ktorý mapovanie nevygenerovalo
Konštanty sa nikdy neimportujú a nikdy sa nezobrazujú ako stĺpce
Použitie @xml-const s ne-XML typom, segment atribútu, ktorý nie je posledný, alebo samotné @name mimo bloku je syntaktická chyba
Editor mapovača zobrazuje konštanty ako riadky @xml-const a zachováva ich, keď sa mapovač preformátuje

Tipy a osvedčené postupy

Tipy k syntaxi

Používajte jednoduché úvodzovky pre zdrojové cesty
Používajte dvojité úvodzovky pre statické hodnoty
Používajte vnorené bloky pre polia/objekty
Pridajte @removeAll pre vnorené entity
Používajte syntax JSONPath ($.path[*]) v @loop
Použite $parent na odkazovanie na rodičovské polia vo vnorených štruktúrach
Udržujte podmienky @if jednoduché

Ďalšie kroky

Keď sú vaše šablóny mapovania pripravené, naučte sa, ako naplánovať automatické importy z externých URL adries.

[navigate:/help/en/user-flows/automatic-imports|Pokračovať na Automatické importy|refresh-cw]

Súvisiace články

[navigate:/help/en/api/imports|Dokumentácia importného systému|upload]
[navigate:/help/en/user-flows/data-migration|Sprievodca migráciou dát|upload]
[navigate:/help/en/user-flows/ai-mapping|Automaticky mapovať stĺpce dodávateľa|bot]