Skip to main content

Specifika formulářových akcí

1. Úvod​

Formulářové akce představují zvláštní kategorii akcí systému Flexideo, která se od ostatních typů (zejména tabulkových a služebních) odlišuje svou prací s formulářovým draftem – rozpracovaným dokumentem uživatele. Tento dokument nemusí být nutně uložen v databázi a může se jednat i o nově vytvářený, dosud neuložený dokument. Existují tři základní druhy akcí:

  • Akce přehledu

  • Formulářové akce

  • Webové služby

První dvě z uvedených jsou akce nativního charakteru s předepsaným vstupem i výstupem.

Zatímco akce přehledu pracuje s daty tabulky, formulářová akce pracuje s jediným formulářovým draftem dokumentu.

2. Vstupní struktura formulářové akce​

2.1. Povaha vstupu​

Formulářová akce má vždy povinný vstup typu act:form-draft.

Tento draft obsahuje aktuální stav formuláře, tak jak jej má uživatel právě rozpracovaný – buď nově vytvářený, nebo načtený z databáze. Na rozdíl od tabulkových akcí, které mohou mít na vstupu seznam více položek ( pdk-list), formulářová akce vždy pracuje s jedním konkrétním dokumentem jednoho typu.

2.2. Více typů draftů​

Jedna akce může být vytvořena pro více typů draftů, ale v jednom okamžiku je na vstupu právě jeden. Zdrojem dat bývá otevřený pdk-list s volbou "dok", která umožňuje přístup k celému rozpracovanému draftu.

3. Průběh zpracování a návrat hodnot​

3.1. Zpracování draftu​

Po spuštění akce se draft přenáší z klientské části (Comex/Intranet) na server, kde může být:

  • použit k provedení operací na straně serveru,

  • upraven a vrácen zpět do formuláře,

  • nebo zpracován bez vrácení.

3.2. Možnosti návratu​

  • Vrácení draftu zpět – úprava se okamžitě projeví ve formuláři.

  • Nevrácení draftu – klientská část označí dokument jako vyřízený.

  • Uložení do databáze – využitím požadavku save-document.

4. Ukládání a práce s dokumentem​

4.1. Save-document​

Nejjednodušší způsob zpracování je použití požadavku save-document.

Pokud je:

  • zdrojem pdk-list otevřený s volbou "dok",

  • typ dokumentu v obálce totožný s typem draftu,

  • a primární klíč odpovídá pořadníku draftu,

dochází k úpravě existujícího dokumentu.

4.2. Kombinace více typů dokumentů​

V rámci jedné akce lze v obálce save-document kombinovat více typů (např. kontakt a osoba).

Každý typ odpovídá svému zdroji a ukládání probíhá samostatně.

Poznámka: Na vstupu formulářové akce může být pouze jeden typ dokumentu, tedy i ukládání probíhá pouze pro tento typ.

5. Vrácení draftu do formuláře​

Pokud je v obálce save-document aktivována volba „do formuláře“, nedochází k uložení do databáze, ale k vrácení úprav do klientského formuláře.

Na výstupu se pak objeví uzel form-draft.

5.1. Kopírování uzlů​

Každý „šedivý“ uzel (oblast, prvek) představuje kopii stejnojmenného uzlu ze vstupu na výstup.

Jakmile začneme v uzlu plnit hodnoty, nastavuje se atribut changed="true", aby formulář věděl, že se hodnota změnila.

5.2. Metadata​

Kromě obsahu draftu je nutné pracovat i s metadaty:

  • primární klíče,

  • atributy automatizace výpočtů,

  • atribut deleted ( true/false),

  • a další atributy dle [stránky metadat dokumentů].

Všechny tyto atributy lze měnit v rámci formulářové akce.

6. Porovnání s tabulkovými akcemi​

Typ akce Vstup Výstup Charakteristika

Tabulková pdk-list (více záznamů) dílčí výstup / redirect nevrací data do tabulky

Formulářová form-draft (1 dokument) draft (upravený / uložený) vrací nebo ukládá formulářová data

7. Práce s víceúrovňovou strukturou dokumentu​

Formulářové akce často pracují s více větvenou strukturou (např. faktura › položky faktury).

7.1. Relativní zdroj​

Každá položka (např. polozka-faktury) se zpracovává pomocí relativního zdroje, který určuje konkrétní uzel položky.

Tím lze:

  • přenášet položky na výstup,

  • filtrovat, přidávat nebo mazat položky podle podmínek.

7.2. Typické příklady​

  • Odstranění položek › nastavení deleted="true".

  • Nově přidané položky › primární klíč začíná znakem #.

  • Přenos existujících položek › zachování klíče a případná úprava hodnot (např. cena).

8. Oblasti s cizím zdrojem​

8.1. Initial a Foreign oblasti​

  • initial – funguje obdobně jako vlastní prvky dokumentu.

  • foreign – zobrazuje cizí data, ale při úpravě je třeba ošetřit indikátor změny ( changed="true").

8.2. Disketka​

U cizích prvků lze použít symbol disketky, který vypíná indikátor změny, aby nedošlo k nechtěnému přepisu zdrojových dat.

9. Kopírování oblastí a varianty uzlů​

Při přenášení oblastí mezi vstupem a výstupem se používá volba malé „c“ – kopírování bez modifikace.

Pokud je potřeba provést úpravy, využívá se disketka nebo hodnotové operace. U formulářových akcí musí být vždy zachována kompletní struktura výstupu – i povinné uzly, které nejsou vyplněné, musí být ve výstupu přítomny (pomocí uzlu variant).

10. Opakovatelné segmenty a mazání​

Pokud pracujeme s draftem, který již existuje v databázi:

  • nové opakování se přidává jako nové (s klíčem #),

  • původní opakování zůstává, dokud není odstraněno pomocí atributu deleted="true".

11. Doporučení a upozornění​

?? Upozornění:

Pokud je vstupem nový dokument (s klíčem začínajícím #), není vhodné do něj vkládat klíče existujících dokumentů.

Je nutné zachovat režim přidávání nebo editace po celou dobu průchodu akcí.

Specifik formulářových akcí přinášejí především těchto 5 klíčových bodů, na které je potřeba si dát pozor:

  • Vstupní draft je vždy jen jeden

Formulářová akce pracuje výhradně s jedním dokumentem (form-draftem) – nelze mít více typů nebo více záznamů zároveň.

  • Zachování struktury při vracení draftu

Při vrácení dat do formuláře musí být výstupní struktura kompletní podle definice typu – i povinné uzly, i když jsou prázdné, musí být přítomny.

  • Správná práce s atributem deleted a klíči

Nové položky mají klíč s „#“, mazání se provádí nastavením deleted="true". Při nesprávném použití může dojít ke ztrátě dat nebo duplicitám.

  • U cizích oblastí nepřepisovat zdrojová data

U prvků typu foreign je nutné ošetřit indikátor změny ( changed="true") nebo použít disketku, aby se změna nepropsala zpět do zdrojového dokumentu.

  • Rozlišení režimu uložení vs. vrácení do formuláře

Pokud je aktivní volba „do formuláře“, nedochází k uložení do databáze – pouze k vrácení upraveného draftu. Pro uložení je nutné explicitně použít save-document.

Tyto body jsou kritické pro správné chování akcí a prevenci chyb při práci s formulářovými daty ve Flexideu.

Příklad postupu tvorby formulářové akce: „Aktualizace položek faktury“​

  • Vstup akce

  • Nastav vstup typu act:form-draft pro dokument faktura.

  • Zdroj nastav jako pdk-list otevřený volbou "dok"(rozpracovaný draft faktury).

  • Ve zdroji vyber klíč dokumentu draftu tak, aby byla editována stejná faktura

  • Mazání neplatných položek

  • V obálce akce přidej uzel pro položky s relativním zdrojem polozka-faktury.

  • Použij podmínku (např. podle stavu nebo data) a položkám, které nevyhovují, nastav atribut deleted="true".

  • Přidání nových položek z databáze

  • Připoj zdroj typu sql-query nebo table, který vrací potřebné nové položky.

  • Přenes tyto záznamy do výstupního uzlu položek; novým položkám se automaticky vygeneruje klíč s #.

  • Zachování ostatních oblastí faktury

  • Pro všechny ostatní uzly (např. hlavička, odběratel, souhrny) použij kopírovací režim „c“ – přenášej beze změny ze vstupu na výstup.

  • nebo můžeš i ponechat "šedivé", protože nebudeš ukládat do databáze, ale jen přenášet na výstup;

  • Výstup akce

  • Na konci akce se takto vrátí kompletní form-draft zpět do formuláře s aktualizovanými položkami.

Princip aktualizace položek faktury ve formulářové akci​

V rámci tohoto postupu je důležité zejména správně pojmout tři uzly nastavení položek ve struktuře dokumentu faktury uvnitř save-document obálky akce.

  • Odebrání nevyhovujících položek

Pomocí relativního zdroje polozka-faktury se v akci vybere každá položka faktury a podmínkou (např. podle stavu, data či hodnoty) se určí, zda má být odstraněna.

Pokud položka nesplní kritérium, nastaví se jí atribut deleted="true".

Tím je označena pro odstranění při dalším uložení, avšak jen v případě, že její primární klíč nezačíná znakem # – tedy nejde o nově přidanou, dosud neuloženou položku.

  • Přenesení vyhovujících položek

Položky, které kritéria splní, se přenášejí ze vstupu na výstup beze změny.

Použije se relativní zdroj stejného uzlu ( polozka-faktury) a šedivý segment obálky zajistí jejich kopírování.

Tím se zachová jejich klíč i struktura, takže systém rozpozná, že jde o existující položky určené k ponechání nebo případné editaci.

  • Doplnění nových položek z databáze

Pro doplnění nových položek se použije jiný zdroj, typicky sql-query nebo table, který vrací potřebná data.

Tyto položky se vloží do uzlu položek faktury na výstupu, přičemž každá nová položka je automaticky označena primárním klíčem začínajícím #.

Formulář je následně interpretuje jako nově přidané, a při uložení ( save-document) je systém vloží jako nové záznamy v databázi.

✅ Výsledek: formulářová akce vyčistí fakturu od neplatných položek, doplní nové dle databáze a zachová veškeré ostatní části dokumentu beze změny.