Systém importu

Mechanismy importu dat, formáty a pravidla validace

Přehled

Třída Importer zpracovává data ve formátu JSON nebo streamu, přičemž se stará o 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é vlastnosti

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ím zpracováním chyb a možností vrácení změn (rollback)

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 ukazuje:

Dávkový atomický import se sledováním změn (changeset)
Dynamický výpočet ceny pomocí výrazů
Vyhledávání kategorie pomocí proměnných
Interpolace řetězců pro popisy
Datumová aritmetika 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 (String)

Textové hodnoty s podporou výrazů

Příklady:

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

Vlastnosti:

Přímé řetězcové hodnoty
Výrazy s proměnnými
Šablonování

Číslo/Celé číslo (Number/Integer)

Číselné hodnoty s podporou kalkulačky

Příklady:

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

Vlastnosti:

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

Booleovská hodnota (Boolean)

Hodnoty pravda/nepravda s více formáty

Příklady:

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

Vlastnosti:

Podpora více jazyků
Různé formáty (1/0, ano/ne)
Nerozlišuje velikost písmen

Datum/Datum a čas (Date/Datetime)

Datumové hodnoty s podporou aritmetiky

Příklady:

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

Vlastnosti:

Více formátů
Relativní výrazy
Datumová aritmetika
České/evropské formáty

Výčtový typ (Enum)

Výčtové hodnoty s lokalizací

Příklady:

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

Vlastnosti:

Klíč nebo lokalizovaný název
Nerozlišuje velikost písmen
Podpora aliasů

Přeložitelné pole (Translatable)

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

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)

Vlastnosti:

Aktualizace pro konkrétní jazyk (sloučení)
Asociativní pole (nahrazení)
Formát pole (nahrazení)
Ovládání pomocí @removeAll
Podpora direktivy @language

Binární data/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"

Vlastnosti:

Kódování Base64
Hexadecimální kódování
Komprese Gzip
Podpora přípony pro kódování
Formáty objektu a řetězce

Operace importu

@operation: create

Vždy vytvoří nový záznam

Příklad:

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

@operation: update

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

Příklad:

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

@operation: upsert

Vytvoří, pokud nenalezen, jinak aktualizuje (výchozí)

Příklad:

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

@operation: delete

Smaže zadaný záznam (záznamy)

Příklad:

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

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

Tyto direktivy poskytují jemnou kontrolu nad chováním operace upsert tím, že specifikují, co se má 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 během operace upsert již existuje.

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 během operace upsert neexistuje.

Hodnoty:

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

Příklady

Přeskočení aktualizací 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ánění vytváření nových záznamů

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

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

Pouze vytváření nových záznamů

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

Tímto se kategorie vytvoří, pokud neexistuje, ale selže, pokud již existuje (což zajistí, že se vytvoří 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 přerušit atomické importy
Užitečné pro synchronizaci dat a zabránění přepisování

Režimy transakcí (@atomic)

Direktiva @atomic řídí chování transakcí a strategii zpracování chyb během importu. Zvolte 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 potvrdí celý soubor, nebo nic. Nejbezpečnější, ale může být pomalejší pro velké importy.

Charakteristiky:

✓ Všechno nebo nic - Kompletní integrita transakce
✓ Vrácení změn při chybě - Jakákoli chyba zruší všechny změny
⚠ Omezený počet chyb - Hlášeno maximálně 100 chyb

@atomic: false

Každý prvek se importuje 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 - Importuje se 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í změn dávky - Neúspěšná dávka neovlivní ostatní

Příklady

Striktní 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ů se neimportuje. 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 chybovým hlášením.

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 mezi výkonem a spolehlivostí.

Výběr 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 přijatelný částečný úspěch
Použijte “batch” pro velké datové sady vyžadující optimální výkon
Výchozí 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 předešlo 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 své vlastní individuální transakce.

Příklad

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

Produkty budou potvrzovány po 200 v rámci jedné transakce.

Kdy ladit výchozí hodnotu

Zvýšit (např. 200–500) při importu jednoduchých, plochých entit bez vnořených relací pro zlepšení propustnosti
Snížit (např. 10–20) při importu entit s mnoha relacemi MANY nebo náročnými automatizacemi pro snížení zátěže paměti
Výchozí hodnota 50 je dobrým kompromisem pro většinu případů použití

Spouštění automatizací (@automation)

Spouštění předdefinovaných automatizací pro aplikaci složitý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žňuje aplikovat složité transformace, výpočty nebo obchodní logiku, která je definována v entitách automatizací.

Jak to funguje

Výběr záznamů - Záznamy jsou vybrány pomocí @where nebo identifikovány podle ID
Vyhledání automatizace - Automatizace je načtena podle jejího ID nebo vyhledávacího klíče (code:)
Spuštění skriptu - importScript automatizace je analyzován a aplikován na každý odpovídající záznam
Aktualizace polí - Změny definované v automatizaci jsou aplikovány na záznam
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"
    }
  ]
}

Spustí 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: Aplikujte 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) Serverová akce vyvolána.

Doporučené postupy

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

Řešení problémů

Automatizace se nespouští

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

Chyba překročení hloubky automatizace

Zkontrolujte cyklické reference automatizací
Snižte úroveň vnoření automatizací
Zkontrolujte řetězec automatizací na přítomnost smyček

Změny nebyly aplikovány

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

Relace a vyhledávání

Podle primárního klíče

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

"category": 123

Podle vyhledávacího klíče (Lookup)

Odkazování pomocí typu a hodnoty vyhledávacího klíče

"category": "code:ELECTRONICS"

Podle externího ID (ext:)

Odkazování 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 závislosti na interních ID. Doporučujeme používat prefix jako ext:SYSTEM:, aby se předešlo 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ření s další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ší více metod pro nalezení záznamu

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

Vícenásobné relace (Multi-Relations)

Pole pro vztahy jedna-ku-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 danou 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 další pole při vytváření související entity s @if-not-found=create

Hodnoty:

Objekt s názvy a hodnotami polí

@action

Vyvolá serverovou akci 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ávací klíč automatizace

@batchSize

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

Hodnoty:

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

@requireChangeSet

Vyžaduje, aby změny byly sledovány v rámci sady změn (changeset)

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 operace upsert

Hodnoty:

ok
ignore
fail

@create

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

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ínkovou logikou

Základní interpolace proměnných

Použijte syntaxi ${variableName} pro vložení hodnot proměnných. Proměnné jsou získávány 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řevede na velká písmena
LOWER(text) - Převede na malá písmena
TRIM(text) - Odstraní bílé znaky na obou koncích
LTRIM(text) - Odstraní bílé znaky z levého konce
RTRIM(text) - Odstraní bílé znaky z pravého konce
UPPERFIRST(text) - Převede první písmeno na velké
REPLACE(text, search, replacement) - Nahradí text
SUBSTR(text, start, length) - Získá podřetězec

Informace o řetězcích a utility

LEN(text) - Získá délku řetězce
STRIPHTML(html) - Odstraní HTML tagy
ADDSLASHES(text) - Oescapuje uvozovky
XMLESCAPE(text) - Oescapuje XML znaky
COALESCE(val1, val2, ...) - První hodnota, která není null/prázdná
ENCODE/DECODE(text, format) - Operace kódování (podporované formáty: base64, hex, base64url)

Funkce pro regulární výrazy

Používejte 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. Vrací 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)

Extrahuje text pomocí regulárního výrazu. Vrací první zachycenou skupinu, pokud existuje, jinak celý shodný text. Vrací null, pokud není nalezena 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ínková logika

Funkce IF

Použijte IF(podmínka, hodnota_pro_pravdu, hodnota_pro_nepravdu) 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ínková syntaxe: podmínka ? hodnota_pro_pravdu : hodnota_pro_nepravdu (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 složitou podmínkovou 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 složité 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žší)

Volání funkcí
Seskupování v závorkách
Násobení a dělení (*, /)
Sčítání a odčítání (+, -)
Spojování řetězců (.)
Porovnávací operátory
Logické AND (&&)
Logické OR (||)
Ternární podmínka (? :)

Pokročilé příklady

Složitá podmínková 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'}"
  }
}

Vícenásobné vnoření funkcí

{
  "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')}"
  }
}

Složitá 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', ' ')))}"
  }
}

Rychlé referenční příklady

Základní operace

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

Složité 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žívat formát výrazu poskytnutím objektu s vlastností “e”, která obsahuje řetězec výrazu.

Příklady číselné kalkulačky

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

Příklady datové kalkulačky

"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 pro konkrétní jazyk (režim sloučení)

"name": "Value"

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

Používá: nastavení @language na začátku importního souboru (nebo výchozí jazyk systému) Výchozí: "name@removeAll": false (zachovává překlady v ostatní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 výsledku {"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 jsou existující překlady {"en": "Old", "cs": "Starý", "de": "Alt"}, pak "name": {"en": "New", "fr": "Nouveau"} vede k výsledku {"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 překlady v ostatních jazycích a ponechá pouze anglický

Řízení odstraňování překladů

@removeAll: true

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

Varování: Tímto trvale smažete nespecifikované překlady

@removeAll: false

Zachovat existující překlady, pouze aktualizovat/přidat specifikované

Bezpečné: Existují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čení s existují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 a zachovají se stávající český, německý atd.

Nahrazení všech překladů

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

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

Formát pole s selektivním řízením odstraňování

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

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

Doporučené postupy

Používejte režim 1 pro inkrementální aktualizace překladů
Používejte 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ů v rámci celého importu
Otestujte chování překladů na vzorových datech před hromadnými importy

Běžné nástrahy

**Nechtěná ztráta překladu:** Režim 2/3 má výchozí nastavení @removeAll: true
**Zmatek v direktivě jazyka:** Ujistěte se, že @language je správně nastaven pro režim 1
**Použití smíšených režimů:** Buďte konzistentní v rámci jedné importní operace
**Citlivost na velikost písmen:** Kódy jazyků jsou citlivé na velikost písmen