Mapování na externí aplikace

Dle principů mapování je základem každé mapy kmenová struktura mapp-to-app uváděná u interních typů dokumentů. Pokud je mapovací struktura součástí některé šablony prvku či oblasti, je třeba uvést substrukturu mapp-to-app uvést i tam. Jde skutečně o substrukturu, neboť sama o sobě má řadu vlastností a dokonce i dalších substruktur.

Výchozí substruktura

Specifické vlastnosti pro mapp-to-app

Společné vlastnosti pro různé mapovací substruktury

Kmen mapy v definici mapp-to-app

Každé mapování začíná výchozím uzlem, kterým je substruktura daná tagem mapp-to-app. Výskyt tohoto uzlu ve finální definici dokumentu zakládá jednu mapu. Jeden dokument může mít několik map. Ke kmeni každé mapy se vztahují další mapovací informace u jednotlivých segmentů dokumentů, které mají formu substruktury mapp-to, které společně s kmenem a tvoří celou mapu. Pro specifikaci kmene slouží jednak vlastnosti a jednak další substruktury (přehled viz. níže).

Díky mapovacím kmenům má každý interní typ definovaný v XDS jasně dáno, na které externí typy a aplikace může být převáděn. Platí to ovšem i opačně. Sestavením všech map k určité externí aplikaci a typu eterního dokumentu ze všech typů interních získáme přehled převoditelnosti typu externího na interní typy. Samotné možnosti použitelnosti mapy pro import či export dat řídí nastavení vlastnosti mode. Více o mapách viz. též principy mapování.

Nastavitelné vlastnosti uzlu mapp-to-app

Substrukturu mapp-to-app je možné specifikovat následujícími vlastnostmi:

• application - Jméno aplikace (token) jako názvu pro získání správného schematu pro přípravu XML ko ...

• autocomplete - Volba ;

• comment - Pracovní komentář segmentu pro účely popisu defince. Nezobrazuje se finálnímu uživateli.;

• custom-x-common - Zapíná změnu šablony x-common (obecné oblasti každého dokumentu) dle použitého ú ...

• discarted - Pomůcka VYŘAZENÍ (tj. "odpoznámkování" v kódu definice). Je-li uzel označen touto vlas ...

• document - Jméno typu dokumentu (token) určené aplikace jako názvu pro získání správného schematu ...

• input-on - Nepovinná vlastnost. Stanovuje podmínku, při které je segment z externího XML načítán.;

• input-params - Umožňuje vložit jeden nebo více parametrů pro mapování vstupních dat.;

• label - Určuje název (štítek), který se objevuje u definovaného segmentu;

• mode - Možnost použít strukturu jen pro určitý režim.;

• output-on - Nepovinná vlastnost. Stanovuje podmínku, při které je segment exportován do externího ...

• output-params - Umožňuje vložit jeden nebo více parametrů pro mapování výstupních dat.;

• pair-according-to - Solitérní výraz pro připárování externích instancí na interní při vstupním pro ...

• purpose - Pojmenování tohoto konkrétního namapování aplikace a typu pro účely snadnějšího použití ...

• release-level - Specifikace bezpečnostní úrovně, která již danou substrukturu pro určitý okruh uži ...

• release-section - Specifikace oddělení a bezpečnostní úrovně pro tato oddělení, kde se již daná su ...

• root-area - Odkaz na oblast interní struktury dokumenu. Pokud je odkaz uveden, tvoří odkazovaná ob ...

• secrecy-lev - Specifikace bezpečnostní úrovně, která je zapotřebí pro zpřístupnění segmentu určité ...

• section - Specifikace oddělení a bezpečnostní úrovně pro tato oddělení, která jsou zapotřebí pro z ...

Potenciální vlastnické uzly

Substrukturu mapp-to-app je možné uvést u následujících uzlů:

• ElementDef - šablona prvku (kmenová definice);

• AreaDef - šablona oblasti (kmenová definice);

• DocumentDef - dokument nebo šablona d. (kmenová definice);

• services - obal služeb dokumentu či rozhraní (substruktura definice);

Možní potomci uzlu mapp-to-app

Substrukturu mapp-to-app je možné rozšířovat o následující potomky:

• join-mapp - propojení map dokumentů;

• pack - obal mapovaných dat;

• unmapped - ošetření nemapovaných prvků;

• xml-ns - přiřazení jmenného prostoru;

Potenciální vlastnické uzly

Substrukturu mapp-to je možné uvést u následujících uzlů:

• ElementDef - šablona prvku (kmenová definice);

• AreaDef - šablona oblasti (kmenová definice);

• element - prvek (segment uvnitř definice);

• area - oblast (segment uvnitř definice);

Práce s metodou mapování (in i out)

Metoda nabízí rozsáhlý soubor nástrojů pro přesnější řízení vstupně/výstupních operací pro konkrétní uzly. Metodu tedy nemůžeme hledat v kmenu mapp-to-app, ale pouze v mapovacích instrukcích mapp-to. Metoda je uplatňována především na prvky, ale je možné pomocí metody nastavit i vlastní šablonu pro tvorbu uzlu oblasti, jak ukazuje algoritmus uplatnění definované metody. V následujících částech projdeme jednotlivé nástroje metody a jejich možnosti. Mezi nejdůležitější parametry metod patří relation-of-maps a relation-of-repeats, které určují vztahy mezi více mapami a vztahy v případě opakovatelnosti uzlů. Vezměme to však dle abecedy:

Algoritmus metody

Zpracování metody do mapovacích procesů má svůj přesně daný postup. Ten je významný zejména v případě, že kombinujeme více mapovacích metod v jedné mapě. Postup zachycuje následující schema:

algorit

**) Uplatnění only-part-after, only-part-before, only-part-between, translate, vložení pre a post fixu (v tomto pořadí);

***) Přepis (type:replace) hodnoty prvku nebo její doplnění. V případě použití left či right-join je aplikován rovněž znak ze zadání parametru delimiter, pokud již jiná hodnota existuje.

Agregace opakovatelných uzlů (aggregation)

Je-li výskyt některého uzlu s hodnotou možné opakovat, automaticky tak vzniká potřeba v některých případech tyto hodnoty např. sčítat či provádět jiné agregace. Nástroj aggregation umožňuje tyto funkce:

• sum - součet číselných hodnot;

• count - určení počtu uzlů;

• avg - sestavení průměrné hodnoty z čísel;

• min - určení nejnižší číselné hodnoty ze všech opakování;

• max - určení nejvyšší číselné hodnoty ze všech opakování;

• list - sestavení seznamu s možným oddělovačem ze všech opakování;

Agregace je prováděna ze všech položek vstupního uzlu, pokud není zadána podmínka pomocí input/output-on. Pokud dána je, pak se agregace provede jen z položek, které podmínce odpovídají. Spolu s možností vytvářet více mapovacích instrukcí pro jeden uzel a s možností nastavit jejich vzájemný vztah (viz. relation-of-maps), získáváme možnost skládat výsledné hodnoty do téměř libovolných skupin či částí.

Vlastní provedení agregace je realizováno pomocí základních funkcí dostupných v jazyku XPath, které jsou využívány v XSLT v 1.0. Tím je také dán jejich omezený výčet. Jedinou výjimkou je sestavování řetězcového seznamu agregační metodou list, kde je využíváno speciálně k tomu účelu generované šablony.

Specifické možnosti agregace list viz. separator-aggregation.

Použití vlastní šablony pro určení hodnoty (value-template)

Pokud rozsáhlé možnosti mapování nebudou dostačující pro velmi specifický způsob transformace, je tu pro sestavení textového obsahu možnost využití vlastní šablony. Tato vlastnost je použitelná pouze pro datový prvek, pro komplexní typ (tj. oblast uzlů) je ale možné využít podobné možnosti nastavením parametru node-template. Pro využití vlastní šablony je třeba v parametru value-template metody zadat obsah atributu name cílové šablony (tedy uzlu xsl:template) a tuto šablonu umístit do souboru custom-mapp-temps ve složce aplikace. Pozor! Tato šablona nesmí obsahovat žádnou tvorbu uzlů! Zápis vlastnosti v metodě pak bude prostý:

Vámi dodaná šablona by měla, disponovat parametrem value, který volající struktura napňuje dosavadní hodnotou po příp. agregaci a výpočtu - viz. algoritmus použití metod.

Doporučení: Před tím, než použijete vlastní šablonu, prověřte jednak, zda skutečně není způsob, jak danou potřebu realizovat implementovanými nástroji mapování a zda zamýšlený záměr není přespříliš komplikovaný a není nějaké jiné jednodušší cesty. Pokud však přesto dospějete k závěru, že šablona je jediná možnost, jejího použití se obávat nemusíte.

Použití vlastní šablony pro celý uzel (node-template)

Pokud rozsáhlé možnosti mapování nebudou dostačující pro velmi specifický způsob transformace, je tu pro sestavení celého výstupního či vstupního uzlu možnost využití vlastní šablony. Tato vlastnost je použitelná jak pro datový prvek tak pro celou oblast (tj. komplexní typ). Potřebujete-li však pomocí vlastní šablony upravovat pouze textový obsah použijte parametru value-template. Pro použití vlastní šablony uzlu je třeba v parametru node-template metody zadat obsah atributu name cílové šablony (tedy uzlu xsl:template) a tuto šablonu umístit do souboru custom-mapp-temps ve složce aplikace. Pozor! Tato šablona musí obsahovat tvorbu uzlu segmentu i všech příp. povinných potomků! Zápis vlastnosti v metodě pak bude prostý:

Doporučení: Před tím, než použijete vlastní šablonu, prověřte jednak, zda skutečně není způsob, jak danou potřebu nerealizovat implementovanými nástroji mapování a zda zamýšlený záměr není přespříliš komplikovaný a není nějaké jiné jednodušší cesty. Pokud však přesto dospějete k závěru, že šablona je jediná možnost, jejího použití se obávat nemusíte.

Jen část řetězce (only-part-...)

Možnost vyjmout jen určitou část řetězce nalézající se za (only-part-after), před (only-part-before) nebo mezi (only-part-between) uvedeným znakem nebo znaky. Vedle běžných znaků, jako jsou písmena, číslice a jiné, které je třeba uvést do apostrofů, je možné použít i speciální znak zadáním jednoho ze tří klíčových slov (bez apostrofů) space, tab, apostrophe či line-end. Syntaxe je tedy následující:

Všechny tři varianty mají shodnou syntaxi a mohou být uváděny zároveň, pak je však třeba pamatovat na pořadí, v jakém jsou uplatňovány:

Pro složitější kombinace je doporučováno použití výrazu v parametru xpath-count. Zadání parametru tedy může vypadat takto:

• vše umístěné za první mezerou;

• vše umístěné před prvním výskytem čárky;

• první text umístěný v uvozovkách;

Při zadání jednoho ze tří výrazů, ale neuvedení klíčového slova a ani znaků v apostrofech se použije výchozí hodnota tohoto parametru, kteou je space, tedy vše umístěné za, před či mezi mezerou/mezerami.

Specifikace operace pro slučování map (operation)

Při výskytu více map u jednoho uzlu je několik způsobů jak s nimi naložit. Tento způsob je specifikován pomocí parametru relation-of-maps metody dané mapy. Jednou z možností vztahu je použití operace (tedy nastavení relation-of-maps: operation. V takovém případě je třeba specifikovat i o jaký druh operace se jedná. To se určuje pomocí parametru operation metody téže mapy:

Zatímco první operace je řetězcová a provádí spojování řetězcových výsledků jednotlivých mapování v daném okamžiku a uzlu, ostatní jsou matematické a umožňují např. nasčítávat hodnoty z jednotlivých uzlů do jediného. Principem je, že jde o výsledné hodnoty jednotlivých map přiřazených k jednomu uzlu, jinak operace nemají uplatnění. Jde tedy o hodnoty, které již mohou být předpočítané jinými možnostmi map, jako jsou například aggregation, postfix, prefix, only-part-..., round, translate nebo xpath-count a mohou být ještě odděleny pomocí separator-operation (oddělovačem pro operace). Takže například zatímco nastavení:

připojí řetězcově (textově) hodnotu namapovanou tímto mapovacím uzlem za hodnotu z mapy předchozí, nastavení

získanou hodnotu matematicky přičte k doposud získané.

Předpona, přípona (pre/post-fix)

Toto nastavení jednoduše umožňuje zadat znak(y), které mají být řetězcově (textově) buď předřazeny (prefix) před či přidány za získanou hodnotu (postfix). Zadání je obdobné jako u parametru only-part-... a mají následující syntaxi:

S parametry only-part-... metody je možné parametry prefix a postfix kombinovat, jen je třeba pamatovat na pořadí, v jakém jsou uplatňovány:

Při zápisu parametru prefix nebo postfix a neuvedení hodnoty, je použito hodnoty výchozí, tedy space a je předřazena či připojena mezera.

Parametry mohou mít následující podobu:

• zajistí, že hodnota bude začínat na novém řádku (např. při operaci spojování za pomoci více map)

• zajistí, že za získanou hodnotou má být údaj o měně.

Parametry pro přípony a předpony mají za úkol jednoduhé připojování potřebných znaků. Složitější způsoby je možné řešit pomocí xpath-count či za pomoci vlastní šablony.

Změna výchozího relačního bodu (relative-to)

Uváděno pouze v případě jiné relativní závislosti tohoto mapování než k odpovídajícímu rodičovskému mapování či kmeni, není-li žádné rodičovské mapování uvedeno.

Každý odkaz v mapování je replikátorem při tvorbě převáděn na relativní vzhledem k mapování nadřazenému. Nadřazené mapování je nejbližší rodičovské mapování v rámci daného účelu. Není-li nad určitým segmentem již žádné nadřazené mapování uvedeno, je tímto nadřazeným mapováním kmen mapy daného účelu (více též viz. vlastnost ref struktury mapp-to). Jednoznačný převod na relativní odkazy nám šetří mnoho starostí při opakovatelných strukturách v dokumentech, kdy např. namapujeme určitou opakovatelnou oblast a všechny mapy uvedené u potomků vztahujících se do stejné cílové oblasti jsou převedeny na relativní a jsou tak zahrnuty do správných instancí dat. Někdy však je třeba zahrnout uzel do jiného opakování nebo např. u agregačních funkcí zahrnovat více úzlů z jiných instancí nadřazené oblasti. Pro tyto účely můžeme relativitu změnit z výchozí - tedy uzel opakování nadřazené oblasti na např. kmen dokumentu a zahrnout tak i jiné instance oblasti a provést např. součet určitého prvku ze všech oblastí (nebo oblastí omezených pomocí in/output-on.

Poznámka: Odkaz je možné uvádět v absolutní i relativní formě.

Nastavení vztahu více map segmentu (relation-of-maps)

Indikace způsobu zařazení hodnoty vzhledem k ostatním mapováním daného uzlu.

Vyskytne-li se pro jeden segment interní či externí více mapování pro shodný účel, může být účelné explicitně stanovit jejich vzájemný vztah pomocí části relation-of-maps v mapovací metodě. Na výběr jsou následující možnosti:

• auto - (výchozí) replikátor určí dle okolností některou z následujících možností;

• stock - pro každou vyhovující mapu bude v cíli vytvořen nový uzel; možné použít pouze při opakovatelnosti uzlů v cílové struktuře;

• alternate - dle podmínek in/output-on bude zvolena max. jedna vyhovující mapa a vytvořen max. jeden odpovídající segment v cílové struktuře;

• operation - pouze pro mapování prvku (neplatí pro komplexní typy - oblasti); hodnoty mapované vyhovujícími mapami budou sloučeny za použití zvolené operace;

Většinou je možné vztah více map ponechat na replikátoru a ten zejména s ohledem na opakovatelnost cílového segmentu a uvedení podmínek u jednotlivých map sestaví potřebné mapování. Například pokud mapujeme neopakovatelný zdroj za použití více mapovacích struktur mapp-to na opakovatelný cíl a chceme jej tak rozložit do více opakování s různými hodnotami, zvolí replikátor automaticky vztah stock nebo naopak při cílové neopakovatelnosti segmentu zvolí alternate pro ochranu před vytvořením více segmentů a vybere tak pouze mapu jednu.

Viz. též vícenásobné mapování v popisu mapovacích principů.

**Tip:**Pokud potřebujete neopakovatelnou strukturu propojit na strukturu s více různými opakováními, je možné jednotlivá opakování v cíli uměle vytvořit více mapami (pro každé opakování jedno). Pak se vám může hodit nastavení parametrů pro odlišení jednotlivých map a jejich správné propojení.

Nastavení vztahu zdrojových opakování (relation-of-repeats)

Indikace způsobu zařazení hodnoty vzhledem k jiným zdrojovým opakováním (vzhledem k opakovatelnosti cíle a typu segmentu).

Pokud je mapován opakovatelný segment jako zdrojový, může být někdy žádoucí explicitně určit, co má být s jeho instancemi provedeno, tj. jaký mají vzájemný vztah. Je však důležité upřesnit, co je míněno pojmem "zdrojové opakování". Při exportu dat do externí aplikace je zdrojem uzel interního dokumentu systému flexideo. Při importu je zdrojem naopak externí XML a tedy i příp. externí opakovatelný uzel. Vyskytne-li se tedy ve zdrojovém uzlu, který je mapován na cílový, schopnost opakovatelnosti, pak je možné využít části relation-of-repeats v mapovací metodě pomocí některého z následujících nastavení:

• auto - (výchozí) replikátor určí dle okolností některou z následujících možností;

• stock - pro každé vyhovující opakování zdroje bude v cíli vytvořen nový uzel; možné použít pouze při opakovatelnosti uzlů v cílové struktuře;

• alternate - dle podmínek in/output-on bude zvoleno max. jedno vyhovující zdrojové opakování a vytvořen max. jeden odpovídající segment v cílové struktuře;

• aggregation - pouze pro mapování prvku (neplatí pro komplexní typy - oblasti); hodnoty vyhovujících opakování budou sloučeny za použití zvolené agregace;

Většinou je možné vztah zdrojových opakování ponechat na replikátoru a ten zejména s ohledem na opakovatelnost zdrojového a cílového segmentu a uvedení podmínek u jednotlivých map sestaví potřebné mapování. Například pokud mapujeme neopakovatelný zdroj na opakovatelný cíl a chceme vytvořit více opakování s různými hodnotami, zvolí replikátor automaticky vztah stock nebo naopak při cílové neopakovatelnosti segmentu zvolí alternate pro ochranu před vytvořením více segmentů.

Viz. též vícenásobné mapování v popisu mapovacích principů.

**Tip:**V některých případech přesnějšího rozlišení opakovatelných zdrojových struktur lze s výhodou též využít nastavení parametrů jednotlivých map pro jejich správné propojení.

Oddělovače pro operaci či agregaci (separator-...)

V rámci metody existují nastavení separator-aggregation a separator-operation, které slouží pro stanovení oddělovače pro řetězcové operace spojování (join) a pro stanovení oddělovače položek seznamové (řetězcové) agregace. Obojí mají shodnou syntaxi:

Vlastnosti klíčovým slovem pojmenovávají znak nebo přímo do apostrofů uvádějí řetězec znaků, jež má či mají být použity jako oddělovač. Tedy vloženy mezi hodnoty získané operací či agregací z více uzlů. Jsou tedy použity pouze pokud existuje více hodnot a tedy i potřeba oddělení, což je rozdíl oproti pre/post-fixu. Je-li uvedeno některé z klíčových slov span|tab|line-end|apostrophe (tj. bez uvední v apostrofech), je vložen znak mezery, tabelátoru či konce řádku. Je-li však naopak uvedeno např. 'space', bude za oddělovač sloužit slovo space jako řetězec sestávající se z pěti znaků bez mezery.

Zaokrouhlování (round)

Jednou z nejčastějších numerických funkcí je zaokrouhlování. Pomocí části round můžete snadno nastavit zaokrouhlování použité hodnoty:

Číslo v round obsahuje počet desetin, na které má být hodnota zaokrouhlena. Při minusové hodnotě čísla jde o počet před nulou (desítky, stovky atd.). Jde o rozšíření možností zaokrouhlování, ktere je jinak také přístupné v rámci možností xpath-count, ale pouze pro zaokrouhlení na celá čísla.

Převod znaků na jiné (translate)

Záměna jednotlivých znaků (v apostrofech) či zvolený spec. symbol mezery, tabelátoru či konce řádku za jiné znaky či znak.

Vlastnost v první části klíčovým slovem pojmenovává znak nebo přímo do apostrofů uvádějí řetězec znaků, které mají být nahrazeny znakem nebo řetězcem znaků v druhém argumentu (za čárkou) uvedeným na stejné pozici. Je-li uvedeno některé z klíčových slov span|tab|line-end|apostrophe (tj. bez uvední v apostrofech), je to chápáno jako znak mezery, tabelátoru či konce řádku. Je-li však naopak uvedeno např. 'space', bude nahrazován každý z pěti nalezených znaků space samostatně jeden po druhém.

Jde o přímou implementaci stejnojmenné funkce z XPath a je tedy dostupná i prostřednictvím xpath-count.

Výpočet hodnoty pomocí XPath (xpath-count)

Možnost získanou hodnotu upravit pomocí XPath výrazu či funkcí. Získaná mapovaná hodnota je pro účely výpočtu uložena v proměnné $sValue.

Pomocí části xpath-count je možné za využití výrazových prostředků a funkcí XPath a XSLT 1.0 provést s mapovanou hodnotou určitou operaci. Vedle vstupních hodnot je možné využívat i odkazy do zdrojové struktury. Při používání odkazů do zdrojové struktury je třeba pamatovat na to, že v případě exportu je zdrojovou strukturou interní dokument systému flexideo převáděný na typ externí a při importu dat je tomu naopak, tedy zdrojem je dokument externí a je třeba používat externí odkazy. Použijete-li, absolutní odkaz, neuvádějte již jméno dokumentu, ale za prvním lomítkem uveďte rovnou kmenovou oblast nebo (u externích struktur) i prvek. Je rovněž možno používat i odkazy relativní z aktuální pozice danou umístěním interního segmentu nebo hlavním odkazem ref dané mapy. Více viz. též absolutní a relativní odkazy.

Podmínka pro výstup či výstup dat

Výrazy uváděné ve vlastnostech output-on a input-on mají společný význam, ale liší se v jedné podstatné a logické "maličkosti". Zadávané odkazy mohou být směrovány buď jen do externích struktur input-on nebo naopak jen do struktur interních output-on. Výrazy, jsou-li zapotřebí, musí být tedy zadávány odděleně v samostatných vlastnostech. Jinak mohou ale využívat stejných funkcí, neboť jsou založeny na možnostech XPath a XSLT v 1.0, čímž jsou dána i jejich omezení. Výsledkem výrazu podmínky je logická hodnota, která říká, zda určitá instance má či nemá být zahrnuta pro datový přenos, tj. kdy má být mapovaný uzel vytvořen a při více mapováních jednoho zdrojového uzlu může podmínka rozhodovat i o výběru určitého zdroje. Viz. též relation-of-maps nebo také relation-of-repeats v mapovacích metodách. Pro rozšíření močností podmínek a tedy i výběrů určitého mapování mohou být někdy velmi užitečné vlastnosti pro nastavení parametrů.

Poznámka: V odkazech výrazu je možné uvádět absolutní i relativní odkazy.

Nastavení parametrů mapování

Pomocí vlastností output-params a input-params je možné zadávat přiřazení hodnot určitým jménům pro jejich další využití. Obě uvedené vlastnosti mají společný význam, ale liší se v jedné podstatné a logické "maličkosti". Zadávané odkazy ve výrazech na pravé straně přiřazení mohou být směrovány buď jen do externích struktur input-params nebo naopak jen do struktur interních output-params. Výrazy, jsou-li zapotřebí, musí být tedy zadávány odděleně v samostatných vlastnostech. Jinak mohou ale využívat stejných funkcí, neboť jsou založeny na možnostech XPath a XSLT v 1.0, čímž jsou dána i jejich omezení.

Vložením hodnoty do určitého parametru získáváte možnost ji kdykoli v dané větvi srovnávat ve výrazech podmínek pro použití mapy a tím i zdrojových dat pomocí výrazů in/output-on. Je tak možné lépe řídit kdy která mapa a tím i data mají být použita.

Poznámka: V odkazech výrazu je možné uvádět absolutní i relativní odkazy.