Co je to?

Poznámka pro administrátory: Toto je systém používaný pro jednorázové vkládání velkého množství dat do vašeho e-shopu. Nejčastěji se používá pro počáteční nastavení, aktualizaci cen tisíců produktů nebo synchronizaci zásob s externím skladem.

Pro koho je to určeno? Administrátoři by si měli přečíst tento článek, aby porozuměli možnostem platformy pro hromadné zpracování dat, jako jsou automatické výpočty cen nebo podpora více jazyků. Vytváření samotných souborů a nastavení technického připojení je však úkolem pro vývojáře nebo datové specialisty.

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

• Masivní úspora času: Aktualizujte tisíce produktů, cen nebo úrovní zásob během několika sekund namísto ručního zadávání.
• Chytré výpočty: Během procesu importu automaticky vypočítávejte konečné ceny (například přidání DPH) nebo generujte popisy produktů.
• Bezpečné a spolehlivé: Systém kontroluje vaše data na chyby před uložením, což zajišťuje, že váš e-shop zůstane přesný a profesionální.
• Připraveno pro více jazyků: Snadno importujte překlady pro všechny podporované jazyky v jediném průchodu.

Systém importu

Mechanismy importu dat, formáty a pravidla validace

Přehled

Třída Importer zpracovává data ve formátu JSON nebo stream, spravuje entity, pole, relace a různé možnosti importu. Importovaná data jsou strukturována jako objekt, kde každý klíč je název entity (např. produkty, uživatelé) a hodnota je pole položek k importu pro danou entitu.

Klíčové funkce

Struktura založená na entitách Data organizovaná podle typů entit s flexibilními operacemi a mapováním polí

Podpora výrazů Dynamické výpočty, interpolace proměnných a komplexní transformace

Atomické operace Importy typu „všechno nebo nic“ s komplexní správou chyb a vrácením změn

Kompletní příklad importu

{
  "@atomic": "batch",
  "@requireChangeSet": true,
  "products": [
    {
      "@operation": "upsert",
      "code": "WIDGET-001",
      "name": "Smart Widget",
      "basePrice": 100,
      "vatRate": 0.21,
      "price": { "e": "${basePrice} * (1 + ${vatRate})" },
      "category": { "e": "code:${categoryCode}" },
      "categoryCode": "ELECTRONICS", 
      "description": { "e": "${name} - Premium quality widget" },
      "validFrom": "today",
      "validTo": { "e": "${validFrom} + 1y" },
      "attributes": [
        {
          "key": "weight",
          "value": { "e": "${baseWeight} + 0.1" },
          "baseWeight": 2.5
        }
      ],
      "@action": "sync"
    }
  ],
  "categories": [
    {
      "@operation": "update",
      "@where": "status = 'active'",
      "status": "archived",
      "archivedAt": "now()"
    }
  ]
}

Tento příklad demonstruje:

• Import atomicity ‘Batch’ se sledováním sady změn
• Dynamický výpočet cen pomocí výrazů
• Vyhledávání kategorií s proměnnými
• Interpolace řetězců pro popisy
• Aritmetika dat pro období platnosti
• Vnořené výrazy ve vícenásobných relacích
• Hromadné operace s podmínkami @where
• Spuštění serverové akce po importu

Podporované typy polí

Řetězec

Textové hodnoty s podporou výrazů

Příklady:

"name": "Widget"
"description": { "e": "Hello ${world}" }

Funkce:

• Přímé řetězcové hodnoty
• Proměnné výrazy
• Šablonování

Číslo/Celé číslo

Číselné hodnoty s podporou kalkulačky

Příklady:

"price": 123.45
"amount": "100+200"
"discount": "3.5%"
"total": { "e": "${price} * 1.21" }

Funkce:

• Aritmetické operace
• Procenta
• Funkce (abs, sqrt atd.)
• Interpolace proměnných

Boolean

Hodnoty true/false s více formáty

Příklady:

"active": true
"enabled": "yes"
"visible": "ano"

Funkce:

• Podpora více jazyků
• Různé formáty (1/0, yes/no)
• Nerozlišuje velká a malá písmena

Datum/Čas

Hodnoty data s podporou aritmetiky

Příklady:

"date": "2024-06-26"
"date": "1.1.2025"
"dueDate": { "e": "${createdDate} + 30d" }
"validTo": "today + 1y"

Funkce:

• Více formátů
• Relativní výrazy
• Aritmetika dat
• České/evropské formáty

Enum

Výčtové hodnoty s lokalizací

Příklady:

"status": "active"
"priority": "Vysoká"

Funkce:

• Klíč nebo lokalizovaný název
• Nerozlišuje velká a malá písmena
• Podpora aliasů

Přeložitelné

Vícejazyčná pole se třemi režimy operací a kontrolou překladu

Příklady:

"name": "Value" (merge mode)
"name": {"en": "English", "cs": "Czech"} (replace mode)
"name": [{"language": "en", "value": "English"}] (array mode)
"name@removeAll": false (preserve other translations)

Funkce:

• Aktualizace specifická pro jazyk (sloučení)
• Asociativní pole (nahrazení)
• Formát pole (nahrazení)
• Ovládání @removeAll
• Podpora direktivy @language

Binární/Blob

Binární data s více formáty kódování

Příklady:

"content": { "base64": "SGVsbG8gV29ybGQ=" }
"content": { "hex": "48656c6c6f20576f726c64" }
"content": { "gzip-base64": "H4sIAAAAAAAA..." }
"content": "SGVsbG8=", "content@encoding": "base64"

Funkce:

• Kódování Base64
• Hexadecimální kódování
• Komprese Gzip
• Podpora přípony kódování
• Formáty objektů a řetězců

Operace importu

@operation: create

Vždy vytvořit nový záznam

Příklad:

{ "@operation": "create", "name": "New Product" }

@operation: update

Aktualizovat existující záznam (vyžaduje primární klíč)

Příklad:

{ "@operation": "update", "id": 123, "name": "Updated Product" }

@operation: upsert

Vytvořit, pokud nenalezeno, jinak aktualizovat (výchozí)

Příklad:

{ "@operation": "upsert", "code": "ABC", "name": "Product ABC" }

@operation: delete

Smazat zadaný záznam (záznamy)

Příklad:

{ "@operation": "delete", "id": 123 }

Řízení chování Upsert (@update a @create)

Tyto direktivy poskytují podrobnou kontrolu nad chováním upsertu tím, že určují, co by se mělo stát, když záznam existuje (@update) nebo neexistuje (@create). Obvykle se používají s @operation: “upsert”.

@update

Řídí, co se stane, když záznam již existuje během operace upsert.

Hodnoty:

• ok – Aktualizovat existující záznam (výchozí)
• ignore – Přeskočit aktualizaci, ponechat beze změny
• fail – Vyvolat chybu, pokud záznam existuje

@create

Řídí, co se stane, když záznam neexistuje během operace upsert.

Hodnoty:

• ok - Vytvořit nový záznam (výchozí)
• ignore - Přeskočit vytváření, žádný nový záznam
• fail - Vyvolat chybu, pokud záznam neexistuje

Příklady

Přeskočit aktualizace pro existující záznamy

{
  "products": [
    {
      "@operation": "upsert",
      "@update": "ignore",
      "code": "EXISTING-PRODUCT",
      "name": "Updated Name"
    }
  ]
}

Pokud produkt s kódem “EXISTING-PRODUCT” již existuje, bude přeskočen (nebude aktualizován).

Zabránit vytváření nových záznamů

{
  "users": [
    {
      "@operation": "upsert",
      "@create": "fail",
      "email": "user@example.com",
      "status": "active"
    }
  ]
}

Pokud uživatel s daným e-mailem neexistuje, import selže s chybou namísto vytvoření nového uživatele.

Vytvářet pouze nové záznamy

{
  "categories": [
    {
      "@operation": "upsert",
      "@update": "fail",
      "@create": "ok",
      "code": "NEW-CATEGORY",
      "name": "New Category"
    }
  ]
}

Tím se vytvoří kategorie, pokud neexistuje, ale selže, pokud již existuje (zajišťuje se tak, že se vytvářejí pouze nové kategorie).

Klíčové body

• Výchozí chování je “ok” pro @update i @create
• Tyto direktivy fungují pouze s @operation: “upsert”
• “ignore” tiše přeskočí operaci
• “fail” vyvolá chybu a může narušit atomické importy
• Užitečné pro synchronizaci dat a zabránění přepisům

Režimy transakcí (@atomic)

Direktiva @atomic řídí chování transakcí a strategii zpracování chyb během importu. Vyberte vhodný režim na základě velikosti dat, tolerance chyb a požadavků na výkon.

@atomic: true (Výchozí)

Všechny importy jsou atomické – buď se celý soubor potvrdí, nebo žádný. Nejbezpečnější, ale u velkých importů může být pomalejší.

Charakteristiky:

• ✓ Všechno nebo nic – Kompletní integrita transakce
• ✓ Vrácení zpět při chybě – Jakákoli chyba zruší všechny změny
• ⚠ Omezené chyby – Maximálně 100 nahlášených chyb

@atomic: false

Každý prvek je importován nezávisle. Jsou možné částečné importy – některé záznamy mohou uspět, zatímco jiné selžou.

Charakteristiky:

• ✓ Nezávislé záznamy – Každý záznam ve vlastní transakci
• ✓ Částečný úspěch – Importovat co nejvíce dat
• ⚠ Izolace chyb – Chyby neovlivňují ostatní záznamy

@atomic: “batch” (Doporučeno)

Nejrychlejší a nejefektivnější režim. Importy jsou zpracovávány v dávkách pro optimální výkon při zachování rozumné izolace chyb.

Charakteristiky:

• 🚀 Vysoký výkon – Optimalizováno pro velké datové sady
• ⚖️ Vyvážený přístup – Výkon s izolací chyb
• 📦 Vrácení dávky zpět – Neúspěšná dávka neovlivní ostatní

Příklady

Přísný import všechno nebo nic

{
  "@atomic": true,
  "products": [
    { "code": "P001", "name": "Product 1" },
    { "code": "P002", "name": "Product 2" },
    { "code": "INVALID", "name": "" }
  ]
}

Pokud některý produkt selže při validaci, žádný z produktů nebude importován. Všechny změny jsou vráceny zpět.

Import jednotlivých záznamů

{
  "@atomic": false,
  "products": [
    { "code": "P001", "name": "Product 1" },
    { "code": "P002", "name": "Product 2" },
    { "code": "INVALID", "name": "" }
  ]
}

Platné produkty (P001, P002) budou úspěšně importovány, zatímco neplatný bude přeskočen s chybovou zprávou.

Optimalizované dávkové zpracování

{
  "@atomic": "batch",
  "products": [
    { "code": "P001", "name": "Product 1" },
    { "code": "P002", "name": "Product 2" },
    { "code": "P003", "name": "Product 3" }
  ]
}

Produkty jsou zpracovávány v optimalizovaných dávkách. Pokud jedna dávka selže, ostatní dávky mohou stále uspět, což poskytuje nejlepší rovnováhu výkonu a spolehlivosti.

Volba správného režimu

• Použijte true pro kritická data, kde by jakákoli chyba měla zastavit import
• Použijte false pro importy s nejlepším úsilím, kde je částečný úspěch přijatelný
• Použijte “batch” pro velké datové sady vyžadující optimální výkon
• Výchozí hodnota je true pro maximální integritu dat
• Zvažte svou strategii zpracování chyb a požadavky na výkon

Velikost dávky (@batchSize)

Direktiva @batchSize přepíše počet položek zpracovaných v jedné databázové transakci. Výchozí hodnota je 50; maximální povolená hodnota je 1000 (vyšší hodnoty jsou tiše omezeny, aby se zabránilo chybám nedostatku paměti). Nulové a záporné hodnoty jsou odmítnuty s chybou.

Tato direktiva nemá žádný účinek, pokud je použito @atomic: false, protože každá položka je vždy zabalena do vlastní individuální transakce.

Příklad

{
  "@atomic": "batch",
  "@batchSize": 200,
  "products": [
    { "code": "P001", "name": "Product 1" },
    { "code": "P002", "name": "Product 2" }
  ]
}

Produkty budou potvrzeny po 200 najednou v rámci jedné transakce.

Kdy upravit výchozí nastavení

• Zvýšit (např. 200–500) při importu jednoduchých, plochých entit bez vnořených vztahů pro zlepšení propustnosti
• Snížit (např. 10–20) při importu entit s mnoha vztahy MANY nebo náročnými automatizacemi pro snížení tlaku na paměť
• Výchozí hodnota 50 je dobrá rovnováha pro většinu případů použití

Spuštění automatizace (@automation)

Spouštět předdefinované automatizace pro aplikaci komplexních transformací a obchodní logiky během importu

Direktiva @automation umožňuje spouštět předdefinované automatizace na importovaných záznamech. To vám umožní aplikovat komplexní transformace, výpočty nebo obchodní logiku, která je definována v entitách automatizace.

Jak to funguje

1. Výběr záznamů – Záznamy jsou vybrány pomocí @where nebo identifikovány ID
2. Vyhledání automatizace – Automatizace je načtena podle jejího ID nebo vyhledávacího klíče (code:)
3. Spuštění skriptu – importScript automatizace je analyzován a aplikován na každý odpovídající záznam
4. Aktualizace polí – Změny definované v automatizaci jsou aplikovány na záznam
5. Uložení – Aktualizovaný záznam je uložen do databáze

Příklady

Základní spuštění automatizace

{
  "products": [
    {
      "@where": "price < 100",
      "@automation": "code:price-calculation-automation"
    }
  ]
}

Spusťte automatizaci na všech produktech, kde je cena nižší než 100.

Automatizace výpočtu ceny

Krok 1: Vytvořte automatizaci

{
  "automations": [
    {
      "@operation": "create",
      "name": "Apply Standard Markup",
      "code": "price-calculation-automation",
      "type": "massUpdate",
      "importScript": "{\"products\":[{\"price\":{\"e\":\"${cost} * 1.3\"}}]}"
    }
  ]
}

Krok 2: Použijte automatizaci

{
  "products": [
    {
      "@where": "category = 'electronics'",
      "@automation": "Apply Standard Markup"
    }
  ]
}

Podmíněné aktualizace polí

{
  "automations": [
    {
      "name": "Low Stock Alert",
      "type": "massUpdate",
      "importScript": "{\"products\":[{\"@where\":\"quantity < 10\",\"status\":\"low-stock\",\"alertSent\":true}]}"
    }
  ]
}

// Apply to products
{
  "products": [
    {
      "@where": "quantity < 10",
      "@automation": "Low Stock Alert"
    }
  ]
}

Automatizace obsahuje vlastní podmínku @where pro dvojitou kontrolu kritérií.

Kombinace s jinými direktivami

{
  "products": [
    {
      "@where": "status = 'pending'",
      "@automation": "code:calculate-totals",
      "@action": "approve"
    }
  ]
}

Pořadí spuštění: 1) Záznam nalezen, 2) Automatizace spuštěna, 3) Akce serveru vyvolána.

Doporučené postupy

• Používejte popisné názvy: Názvy automatizací by měly jasně naznačovat jejich účel
• Důkladně testujte: Před nasazením do produkce testujte na vzorových datech
• Vyhněte se sebereferencím: Nikdy nevytvářejte automatizace, které odkazují samy na sebe
• Používejte podmínky @where: Zajistěte, aby se automatizace vztahovaly pouze na příslušné záznamy
• Sledujte hloubku: Udržujte vnoření automatizací mělké (max. 5 úrovní)
• Dokumentujte logiku: Dokumentujte komplexní logiku automatizace

Řešení problémů

Automatizace se nespouští

• Ověřte, zda je ID automatizace/vyhledávací klíč správný
• Zkontrolujte, zda je typ automatizace massUpdate nebo aiMassUpdate
• Ujistěte se, že automatizace není zakázána
• Ověřte, zda je pole importScript platný JSON

Chyba překročení hloubky automatizace

• Zkontrolujte kruhové reference automatizace
• Snižte úroveň vnoření automatizace
• Zkontrolujte řetězec automatizace na smyčky

Změny nebyly použity

• Ověřte, zda podmínka @where v importScript odpovídá záznamu
• Zkontrolujte, zda jsou názvy polí ve skriptu automatizace správné
• Ujistěte se, že importScript je správně formátován

Vztahy a vyhledávání

Podle primárního klíče

Odkazujte pomocí primárního klíče související entity

"category": 123

Podle vyhledávání

Odkazujte pomocí typu a hodnoty vyhledávání

"category": "code:ELECTRONICS"

Podle externího ID (ext:)

Odkazujte pomocí externích identifikátorů uložených v extIds (podporuje dvojtečky v hodnotě). Externí ID jsou definována jako páry klíč-hodnota v poli extIds entity, což umožňuje flexibilní odkazování bez spoléhání na interní ID. Doporučujeme použít předponu jako ext:SYSTEM:, abyste se vyhnuli konfliktům s jinými integracemi.

"category": "ext:SYSTEM:CATEGORY:123"

Použití výrazů

Dynamické vyhledávání pomocí proměnných

"category": { "e": "code:${categoryCode}" }

Vytvořit s dodatečnými poli

Automatické vytvoření související entity s více poli pomocí @create-as

"category_id": "code:ELEC",
"category_id@if-not-found": "create",
"category_id@create-as": {
  "name": "Electronics",
  "code": "ELEC"
}

Více hodnot

Vyzkoušejte více metod řešení

"category": [123, "code:FALLBACK"]

Vícenásobné vztahy

Pole vztahů jedna k mnoha

"items": [
  { "name": "Item 1", "quantity": 10 },
  { "name": "Item 2", "quantity": 5 }
]

Speciální přípony polí

@atomic

Řídí chování transakcí a strategii zpracování chyb

Hodnoty:

• true (všechno, nebo nic)
• false (nezávislé záznamy)
• batch (dávkové zpracování)

@operation

Řídí akci pro položku

Hodnoty:

• create
• update
• upsert
• delete

@where

Definuje podmínky pro hromadné operace

Hodnoty:

• Formát objektu
• Formát výrazu

@m

Určuje autora/zdroj změny

Hodnoty:

• api/a
• human/user/u
• default/d
• import/i
• ai

@if-not-found

Řídí chování, pokud vyhledávání selže

Hodnoty:

• fail
• null
• create
• skip

@create-as

Určuje dodatečná pole při vytváření související entity s @if-not-found=create

Hodnoty:

• Objekt s názvy polí a hodnotami

@action

Vyvolá akci serveru na importovaném záznamu

Hodnoty:

• merge
• sync
• vlastní akce

@automation

Spustí předdefinovanou automatizaci na importovaném záznamu

Hodnoty:

• ID automatizace
• název/vyhledávání automatizace

@batchSize

Nastaví počet položek zpracovaných v jedné transakci (výchozí: 50, maximum: 1000)

Hodnoty:

• Kladné celé číslo (1–1000)

@requireChangeSet

Vyžaduje sledování změn v sadě změn

Hodnoty:

• true
• false

@removeAll

Odstraní všechny existující související položky, které nejsou v importu

Hodnoty:

• true
• false

@update

Řídí chování, když záznam existuje během upsertu

Hodnoty:

• ok
• ignore
• fail

@create

Řídí chování, když záznam neexistuje během upsertu

Hodnoty:

• ok
• ignore
• fail

Řetězcové výrazy

Výkonný šablonovací jazyk pro dynamické generování řetězců s proměnnými, funkcemi a podmíněnou logikou

Základní interpolace proměnných

Použijte syntaxi ${variableName} pro vložení hodnot proměnných. Proměnné jsou řešeny z aktuálního kontextu importu.

Příklady:

"name": "Hello ${firstName}!" → "Hello John!"
"description": "${brand} - ${model}" → "Apple - iPhone"
"fullName": "${UPPER(firstName)} ${lastName}" → "JOHN Doe"

Řetězcové funkce

Manipulace s textem

• UPPER(text) – Převést na velká písmena
• LOWER(text) – Převést na malá písmena
• TRIM(text) – Odstranit mezery z obou konců
• LTRIM(text) – Odstranit mezery z levého konce
• RTRIM(text) – Odstranit mezery z pravého konce
• UPPERFIRST(text) – Velké první písmeno
• REPLACE(text, search, replacement) – Nahradit text
• SUBSTR(text, start, length) – Extrahovat podřetězec

Informace a utility pro řetězce

• LEN(text) – Získat délku řetězce
• STRIPHTML(html) – Odstranit HTML tagy
• ADDSLASHES(text) – Escapovat uvozovky
• XMLESCAPE(text) – Escapovat XML znaky
• COALESCE(val1, val2, ...) – První nenulová/neprázdná hodnota
• ENCODE/DECODE(text, format) – Operace kódování (podporované formáty: base64, hex, base64url)

Funkce regulárních výrazů

Použijte regulární výrazy pro porovnávání vzorů a extrakci textu v rámci řetězcových výrazů.

Porovnávání vzorů

REGEXPMATCH(pattern, text)

Testuje, zda text odpovídá vzoru. Vrátí true, pokud vzor odpovídá textu, jinak false.

Příklady:

"${REGEXPMATCH('^[A-Z]', 'Hello')}" → true (starts with capital)
"${REGEXPMATCH('^[0-9]+$', 'Hello')}" → false (not all digits)

Extrakce textu

REGEXP(pattern, text)

Extrahujte text pomocí regulárního výrazu. Vrátí první zachycenou skupinu, pokud existuje, jinak celou shodu. Vrátí null, pokud není nalezena žádná shoda.

Příklady:

"${REGEXP('^([A-Z])[a-z]+', 'Hello')}" → "H" (first capturing group)
"${REGEXP('^[A-Z][a-z]+', 'Hello')}" → "Hello" (full match, no groups)

Běžné případy použití

Validace e-mailu

"${REGEXPMATCH('^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$', email)}"

Extrakce telefonního čísla

"${REGEXP('\\(([0-9]{3})\\) [0-9]{3}-[0-9]{4}', '(555) 123-4567')}" → "555"

Validace dat

"${IF(REGEXPMATCH('^[A-Z]{2}[0-9]{4}$', code), 'Valid format', 'Invalid format')}"

Extrakce ceny

"${REGEXP('Price: \\$([0-9]+\\.[0-9]{2})', 'Price: $19.99')}" → "19.99"

Podmíněná logika

Funkce IF

Použijte IF(condition, trueValue, falseValue) pro podmíněný výběr hodnoty.

Příklady:

"status": "${IF(age >= 18, 'Adult', 'Minor')}" → "Adult"
"message": "${IF(isActive = true, 'Available', 'Unavailable')}" → "Available"

Ternární operátor

Alternativní podmíněná syntaxe: condition ? trueValue : falseValue (stejné jako funkce IF, ale stručnější)

Příklady:

"status": "${age >= 18 ? 'Adult' : 'Minor'}" → "Adult"
"message": "${isActive ? 'Available' : 'Unavailable'}" → "Available"

Vnořené ternární operátory

Ternární operátory lze vnořovat pro komplexní podmíněnou logiku.

Příklady:

"category": "${age > 65 ? 'Senior' : (age > 18 ? 'Adult' : 'Minor')}" → "Adult"
"grade": "${score >= 90 ? 'A' : (score >= 80 ? 'B' : (score >= 70 ? 'C' : 'F'))}" → "A"
"access": "${userRole = 'admin' ? 'Full Access' : (userRole = 'user' ? 'Limited Access' : 'No Access')}" → "Full Access"

Ternární operátor s logickými operátory

Kombinujte ternární operátory s logickými operátory pro komplexní podmínky.

Příklady:

"eligibility": "${age >= 18 && isActive ? 'eligible' : 'not eligible'}" → "eligible"
"access": "${isAdmin || isManager ? 'access granted' : 'access denied'}" → "access granted"
"welcome": "${(age > 18 && status = 'verified') || isVIP ? 'Welcome' : 'Access denied'}" → "Welcome"

Priorita operátorů

Priorita (od nejvyšší po nejnižší)

1. Volání funkcí
2. Seskupování závorkami
3. Násobení a dělení (*, /)
4. Sčítání a odčítání (+, -)
5. Zřetězení řetězců (.)
6. Relační operátory
7. Logické AND (&&)
8. Logické OR (||)
9. Ternární podmíněný operátor (? :)

Pokročilé příklady

Komplexní podmíněná logika

{
  "userStatus": {
    "e": "${(age >= 18 && isVerified = true) || isAdmin = true ? 'Authorized' : 'Unauthorized'}"
  },
  "priceCategory": {
    "e": "${price > 1000 ? 'Premium' : price > 500 ? 'Standard' : 'Budget'}"
  },
  "statusMessage": {
    "e": "${isActive ? (lastLogin ? 'Active User' : 'Inactive User') : 'Disabled Account'}"
  }
}

Vnořování funkcí na více úrovních

{
  "processedName": {
    "e": "${UPPER(TRIM(REPLACE(rawName, '_', ' ')))}"
  }
}

Podmíněné sestavování řetězců

{
  "fullAddress": {
    "e": "${street}${IF(LEN(apartment) > 0, ', Apt ' + apartment, '')}${IF(LEN(city) > 0, ', ' + city, '')}"
  }
}

Validace a formátování

{
  "emailStatus": {
    "e": "${IF(LEN(email) > 0 && email != null, 'Email: ' + LOWER(TRIM(email)), 'No email provided')}"
  }
}

Komplexní obchodní logika

{
  "accessLevel": {
    "e": "${IF((userRole = 'admin' || userRole = 'moderator') && isActive = true && LEN(lastLogin) > 0, 'Full Access', IF(userRole = 'user' && isActive = true, 'Limited Access', 'No Access'))}"
  }
}

Čištění a transformace dat

{
  "cleanDescription": {
    "e": "${TRIM(STRIPHTML(REPLACE(rawDescription, '\\n', ' ')))}"
  }
}

Příklady pro rychlou referenci

Základní operace

"Hello ${world}!"
"${UPPER('hello')} ${LOWER('WORLD')}"
"${IF(isActive, 'Active', 'Inactive')}"
"${isActive ? 'Active' : 'Inactive'}"

Komplexní podmínky

"${IF(age >= 18 && status = 'verified', 'Welcome', 'Access denied')}"
"${price > 100 ? 'Premium' : price > 50 ? 'Standard' : 'Budget'}"
"${COALESCE(nickname, firstName, 'Anonymous')}"

Příklady formátu výrazů

Jakékoli pole může použít formát výrazu poskytnutím objektu s vlastností “e” obsahující řetězec výrazu.

Příklady kalkulátoru čísel

"amount": "100+200" → 300
"amount": "3.5%" → 0.035
"amount": "abs(-100)" → 100
"amount": "(100+50)*2" → 300
"amount": "sqrt(16)" → 4

Příklady kalkulátoru dat

"date": "1.1.2025" → 2025-01-01
"date": "15.6.25" → 2025-06-15
"date": "today + 1y" → one year from today
"date": "1.1.2025 + 5M" → 2025-06-01

Interpolace proměnných

"price": { "e": "${basePrice} * 1.21" }
"fullName": { "e": "Hello ${firstName}!" }
"dueDate": { "e": "${createdDate} + 30d" }

Režimy aktualizace přeložitelných polí

Komplexní průvodce pro práci s vícejazyčnými poli s různými strategiemi aktualizace

Přeložitelná pole podporují více režimů aktualizace s různým chováním pro zpracování existujících překladů.

Tři režimy aktualizace

Režim 1: Aktualizace specifická pro jazyk (režim sloučení)

"name": "Value"

Aktualizuje překlad pouze pro aktuálně vybraný jazyk (@language nebo systémový výchozí)

Používá: nastavení @language v horní části souboru importu (nebo systémový výchozí jazyk)
Výchozí: "name@removeAll": false (zachovává překlady v jiných jazycích)

Příklad: Pokud je aktuální jazyk “en” a existující překlady jsou {"en": "Old", "cs": "Starý"}, pak "name": "New" vede k {"en": "New", "cs": "Starý"}

Režim 2: Přímé asociativní pole (režim nahrazení)

"name": {"en": "English", "cs": "Czech"}

Nahradí všechny překlady zadanými jazyky

Výchozí: "name@removeAll": true (odstraní všechny ostatní existující překlady, které nejsou specifikovány)

Příklad: Pokud existující překlady jsou {"en": "Old", "cs": "Starý", "de": "Alt"}, pak "name": {"en": "New", "fr": "Nouveau"} vede k {"en": "New", "fr": "Nouveau"} (německý překlad je odstraněn)

Režim 3: Přímý formát pole (režim nahrazení)

"name": [{"language": "en", "value": "English"}, {"language": "cs", "value": "Czech"}]
"name": [{"language": "en", "name": "English"}, {"language": "cs", "name": "Czech"}]

Alternativní formát podporující vlastnosti “value” i “name”

Výchozí: "name@removeAll": true (odstraní všechny ostatní existující překlady, které nejsou specifikovány)

Příklad: "name": [{"language": "en", "value": "New"}] odstraní všechny ostatní jazykové překlady a ponechá pouze anglický

Ovládání odstranění překladů

@removeAll: true

Odstranit všechny ostatní překlady, které nejsou uvedeny v aktuální aktualizaci

Upozornění: Tímto budou trvale smazány nespecifikované překlady

@removeAll: false

Zachovat stávající překlady, aktualizovat/přidat pouze ty specifikované

Bezpečné: Stávající překlady jsou zachovány a sloučeny

Shrnutí výchozího chování

• Režim 1 (specifický pro jazyk): @removeAll: false (sloučit)
• Režim 2 a 3 (přímá pole): @removeAll: true (nahradit)

Praktické příklady

Sloučit se stávajícími (zachovává ostatní jazyky)

{
  "@language": "en",
  "products": [
    {
      "code": "WIDGET-001",
      "name": "New English Name",
      "name@removeAll": false
    }
  ]
}

Tímto se aktualizuje pouze anglický překlad, při zachování stávajících českých, německých atd.

Nahradit všechny překlady

{
  "products": [
    {
      "code": "WIDGET-001",
      "name": {"en": "English", "cs": "Czech"}
    }
  ]
}

Automaticky nastaví @removeAll: true, čímž odstraní všechny ostatní jazykové překlady.

Formát pole s selektivním ovládáním odstranění

{
  "products": [
    {
      "code": "WIDGET-001",
      "name": [{"language": "en", "value": "English"}],
      "name@removeAll": false
    }
  ]
}

Přepsat výchozí nastavení pro zachování ostatních jazyků při použití formátu pole.

Osvědčené postupy

• Použijte režim 1 pro inkrementální aktualizace překladů
• Použijte režimy 2/3 pro hromadné importy překladů z externích systémů
• Vždy explicitně specifikujte @removeAll, pokud je chování kritické
• Zvažte použití direktivy @language pro konzistentní zpracování jazyků napříč importem
• Otestujte chování překladů s ukázkovými daty před hromadnými importy

Častá úskalí

Další kroky

Nyní, když rozumíte importnímu systému, naučte se vytvářet šablony mapování pro transformaci vašich dat.

[navigate:/help/en/api/mapper|Pokračovat na Mapování dat|settings]

Související články

• [navigate:/help/en/user-flows/automatic-imports|Pracovní postupy automatického importu|refresh-cw]
• [navigate:/help/en/user-flows/data-migration|Průvodce migrací dat|upload]
• [navigate:/help/en/api/webhooks|Dokumentace k webhookům|webhook]