Builder dynamických podmínek

Builder dynamických podmínek je vizuální nástroj, ve kterém můžete bez psaní kódu nastavit, jak se mají proměnné na úkolu chovat – kdy se schovají, kdy se přepočítají, kdy mají být povinné nebo jen pro čtení. Místo skriptu klikáte a TAS si výsledný skript vygeneruje za vás.

Tento článek je technická reference: projde postupně každé nastavení, vysvětlí, kdy ho použít, a uvede několik příkladů od jednoduchých po složitější. Je určený pro konzultanty a administrátory TAS.

Co builder umí

Builder definuje dynamické chování proměnných na úkolu – tedy jak prvky formuláře reagují na hodnoty jiných proměnných. Konkrétně s ním můžete:

• skrývat proměnné podle podmínek,
• měnit hodnotu proměnné – výpočtem, podle data, podle parametru uživatele/role/organizační jednotky nebo podle hodnoty z dynamické tabulky,
• validovat vstup uživatele (e-mail, telefon, délka textu, rozsah hodnot…),
• přepínat proměnnou na pouze pro čtení nebo pro zápis,
• nastavit proměnnou jako povinnou,
• povolit splnění úkolu až ve chvíli, kdy se nějaká proměnná změní.

Dynamické podmínky v TAS existovaly už dřív – ale jen jako skript. Builder nad ten skript přidává vizuální vrstvu: konfiguraci naklikáte a TAS ji obousměrně převádí na spustitelný skript a zpátky. Nemusíte tedy znát jeho syntaxi.

Builder otevřete z definice úkolu v šabloně, v sekci Šablony → úkol → proměnné. Vždy pracuje v kontextu konkrétního úkolu – nastavené podmínky se ukládají k tomuto úkolu a vyhodnocují se nad jeho formulářem za běhu případu.

Jak builder funguje

Stavba z bloků

Celá konfigurace je seznam bloků. Klíčové pravidlo, které drží všechno pohromadě:

Jeden blok se vždy skládá z těchto částí:

• Funkce – co se má stát (Skrýt, Změnit, Validovat…),
• Cílová proměnná – na kterou proměnnou funkce míří,
• Typ změny / typ validace – jen u funkcí Změnit a Validovat,
• Podmínky – za jakých okolností se to má stát (skupiny podmínek spojené přes AND/OR),
• Spustit při změně – které proměnné mají přehodnocení vyvolat,
• Aktivní – jestli blok běží, nebo je vypnutý.

Kdy se podmínky vyhodnotí

Podmínky se vyhodnocují nad formulářem úkolu za běhu – při otevření úkolu a pak pokaždé, když se změní sledovaná proměnná. Ve výchozím stavu se blok přehodnotí při změně té proměnné, která v něm vystupuje. Pokud potřebujete, aby přehodnocení vyvolala i jiná proměnná, použijete volbu Spustit při změně (viz dále).

Když máte víc bloků, vyhodnocují se shora dolů. To je důležité hlavně u funkce Změnit: pokud do stejné proměnné zapisuje víc pravidel, vyhraje poslední splněné pravidlo podle pořadí v konfiguraci.

Všechno se odvíjí od typu proměnné

Builder je úzce provázaný s typem cílové proměnné. Typ proměnné totiž rozhoduje o tom, které operátory nabídne v podmínkách, které typy změn dovolí u funkce Změnit a které validace u funkce Validovat. Když vám někde chybí očekávaná možnost, příčinou je skoro vždycky typ proměnné.

Tahle tabulka je klíč k celé referenci – řada omezení níže je popsaná právě těmito kódy:

Builder versus Skript

Modal má dvě záložky. Builder je vizuální konfigurace pomocí bloků – to je výchozí a doporučený způsob. Skript ukazuje textovou podobu podmínek, tedy vygenerovaný skript.

Konfigurace z builderu se automaticky převádí na skript a uloží. Převod je obousměrný (skript ↔ bloky). Má to ale jeden háček: pokud někdo skript ručně upraví do podoby, kterou builder neumí zpětně rozparsovat, modal zůstane na záložce Skript a vizuální builder pro něj nebude dostupný.

Typický postup

1. Otevřete definici úkolu v šabloně a zobrazte jeho proměnné.
2. Otevřete Builder dynamických podmínek.
3. Přidejte blok a zvolte funkci (co se má stát).
4. Vyberte cílovou proměnnou.
5. U funkce Změnit / Validovat nastavte typ změny nebo typ validace.
6. Nadefinujte podmínky (proměnná → operátor → hodnota), případně je seskupte přes AND/OR.
7. Volitelně nastavte Spustit při změně.
8. Uložte a otestujte v běžícím případu – otevřete úkol, změňte vstupní proměnné a ověřte chování.
9. Pro ladění mrkněte na záložku Skript.

Reference nastavení

Tahle část projde systematicky každé nastavení builderu.

Záložky modalu

Přepínají mezi vizuální (blokovou) a textovou (skriptovou) podobou. Hodnoty: Builder (blokový editor) a Skript (textový editor vygenerovaného skriptu). Výchozí je Builder. Pokud uložený skript nejde převést na bloky, je dostupná pouze záložka Skript.

Aktivní všechny (globální přepínač)

Hromadně aktivuje nebo deaktivuje všechny bloky najednou. Výchozí stav je zapnuto (builderBlocksGloballyActive = true). Když přepínač vrátíte zpět do polohy „Aktivní", aktivují se jen bloky, které byly aktivní původně – individuální stav jednotlivých bloků se neztratí.

Hledat proměnnou (filtr bloků)

Filtruje zobrazené bloky podle cílové proměnné (usingTvarId) – hodí se u úkolů s velkým množstvím bloků. Výchozí stav je prázdný (zobrazí se vše).

Tlačítko Nápověda

Otevírá kontextovou nápovědu k builderu s popisem funkcí a interaktivními příklady.

Nastavení bloku

Funkce

Výběr v hlavičce bloku, který určuje, co se má stát s cílovou proměnnou (nebo úkolem) při splnění podmínek. Funkci si volíte jako první krok. Možnosti:

Pár závislostí, které stojí za zapamatování: change zpřístupní sekci Typ změny, validate zpřístupní sekci Typ validace a navíc nepoužívá seskupení AND/OR mezi skupinami (globalJunction je null) – validace pracuje s jedinou podmínkovou skupinou.

Cílová proměnná

Výběr v hlavičce bloku (v UI jen Proměnná), který určuje, na kterou proměnnou se funkce aplikuje. Vybrat lze libovolnou proměnnou úkolu. U většiny funkcí je povinná; výjimkou je script, který cílovou proměnnou nemá (tvar_id = null). Typ vybrané proměnné rozhoduje o dostupných typech změn a validací.

Aktivní (přepínač bloku)

Zapíná a vypíná jednotlivý blok (isActive). Výchozí stav je zapnuto.

Ovládací akce bloku

• Převést na skript – převede blok z vizuální podoby na skript (a zpět).
• Kopírovat blok – vytvoří kopii bloku.
• Smazat blok – blok odebere.
• Táhlo (drag handle) – přeuspořádání bloků přetažením. Pořadí má vliv u funkce Změnit.

Spustit při změně

Určuje, změna kterých proměnných na formuláři má vyvolat opětovné vyhodnocení bloku. Zapnete volbu (useWatchVars) a vyberete proměnné (watchVars, klidně více). Výchozí stav je vypnuto. Hodí se vždy, když podmínka závisí na proměnné, jejíž změna by jinak přehodnocení nevyvolala – tím zařídíte okamžitou reakci formuláře.

Nastavení podmínek

Jeden řádek podmínky

Podmínka má tři části:

• Proměnná (tvar_id) – proměnná, jejíž hodnota se testuje.
• Operátor (operator) – způsob porovnání. Nabídka operátorů závisí na typu proměnné (viz sekce Operátory).
• Hodnota / Proměnná – pravá strana porovnání. V režimu hodnota (conditionAgainst = 'value') porovnáváte proti zadané hodnotě (againstValue), v režimu proměnná (conditionAgainst = 'variable') proti hodnotě jiné proměnné (againstTvarId). Mezi režimy přepínáte ikonovým tlačítkem u řádku.

Nová podmínka začíná v režimu value s prázdným operátorem i hodnotou. U operátorů isn (je prázdný) a isnn (není prázdný) se pravá strana nevyplňuje. U proměnných typu datum můžete jako hodnotu zvolit i „rychlé datum" (Dnes, Zítra…) nebo konkrétní datum.

Spojka uvnitř skupiny (AND/OR)

Přepínač mezi podmínkami v rámci jedné skupiny (internalJunction). Určuje, jestli musí platit všechny podmínky (and), nebo alespoň jedna (or). Výchozí hodnota je and.

Spojka mezi skupinami (AND/OR)

Přepínač mezi celými skupinami podmínek (globalJunction). Díky němu poskládáte složené výrazy typu (A AND B) OR (C). Výchozí hodnota je and.

Přidání a odebrání podmínky a skupiny

• Přidat podmínku – přidá další řádek do skupiny.
• Přidat skupinu podmínek – přidá další skupinu (spojenou přes globalJunction).
• Odebrat – odebere řádek nebo skupinu.
• Táhlo – přeuspořádání podmínek přetažením.

Funkce „Změnit" – Typ změny

Funkce change (Změnit) zpřístupní výběr typu změny – tedy odkud se má nová hodnota cílové proměnné vzít. Nabídka závisí na typu cílové proměnné.

Výchozí typ změny je constant.

Konstanta (constant)

Zadáte přímo hodnotu (constantValue). Typ hodnoty odpovídá cílové proměnné – text, číslo, výběr, u checkboxu true/false, u vícehodnotové proměnné seznam.

Operace s čísly (operationWithNumbers)

Vyberete první proměnnou (operationWithNumbersTvarId1), operaci (operationWithNumbersOperation) a druhou proměnnou (operationWithNumbersTvarId2). Vstupní proměnné musí být čísla N (kromě checkboxu) nebo LN (bez vícehodnotovosti).

Dynamický odkaz (dynamicLink)

Vyberete entitu (dynamicLinkEntity) a proměnnou s ID (dynamicLinkIdVariableTvarId). Proměnná s ID musí být celé číslo N (0 desetinných míst, ne checkbox). Entity: case (případ), task (úkol), overview (přehled).

Dynamické datum (dynamicDate)

Nejdřív zvolíte typ data (dynamicDateType): quickDate (Rychlé datum) nebo relativeDate (Relativní datum).

U rychlého data (dynamicDateQuickDateValue) vybíráte z hodnot: today (Dnes), yesterday (Včera), tomorrow (Zítra), prevWorkDay (Předchozí pracovní den), monthStart (Začátek měsíce), monthEnd (Konec měsíce), yearStart (Začátek roku), yearEnd (Konec roku).

U relativního data skládáte výraz {datumová proměnná} +/- X dnů:

• datumová proměnná (dynamicDateRelativeDateTvarId) – typ D nebo LD (bez vícehodnotovosti),
• operátor (dynamicDateRelativeDateOperator): plus (+) nebo minus (-),
• počet dnů (dynamicDateRelativeDateAmount).

Parametry entit (userParameter / orgUnitParameter / roleParameter)

Vždy vyberete proměnnou s ID entity a název parametru:

• userParameter: userParameterUserIdTvarId + userParameterName,
• orgUnitParameter: orgUnitParameterOrgUnitIdTvarId + orgUnitParameterName,
• roleParameter: roleParameterRoleIdTvarId + roleParameterName.

Nabídka názvů parametrů závisí na typu cílové proměnné – textová proměnná nabízí textové vlastnosti, číselná nabízí ID a podobně. Příklady dostupných parametrů:

• uživatel: celé jméno, zobrazované jméno, uživatelské jméno, jméno, příjmení, status, e-mail, titul před/za, ID, ID org. jednotky;
• org. jednotka: název, manažer (uživatelské jméno), typ, externí ID, IČ nadřízené, dodatečné ID, externí status, IČ společnosti, status, ID, ID manažera, ID nadřízené jednotky;
• role: název role, kategorie, popis, omezení přiřazení role, ID, max. počet přiřazení, ID org. jednotky.

Hodnota z dynamické tabulky (valueFromDynTable)

Vyberete dynamickou tabulku (valueFromDynTableDynTableId), sloupec s hodnotou (valueFromDynTableDynTableColumnIndex) a filtr řádků (valueFromDynTableRowsFilter). Filtr řádků má vlastní vnořený builder podmínek (skupiny i spojky AND/OR), kde porovnáváte sloupce tabulky proti hodnotám nebo proměnným. Tím vyberete řádek, ze kterého se hodnota přebírá.

Hodnota proměnné (variableValue)

Vyberete zdrojovou proměnnou (variableValueTvarId). Zdrojová a cílová proměnná musí být kompatibilní – text ↔ text/výběr, číslo ↔ číslo/číselný výběr/datum-typ, datum ↔ datum, checkbox jen s checkboxem, a se stejným nastavením vícehodnotovosti.

Funkce „Validovat" – Typ validace

Funkce validate (Validovat) zpřístupní výběr typu validace. Nabídka opět závisí na typu cílové proměnné.

U každé validace můžete nastavit chybovou hlášku pro každý jazyk instance (interně errorMessage_{jazyk}), která se uživateli ukáže, když validace neprojde. Výchozí stav je nevyplněno (null) – pak se použije systémová hláška.

Operátory v podmínkách

Operátory se používají v podmínkách a jejich nabídka závisí na typu testované proměnné.

Krátké vodítko, kdy který sáhnout:

• Rovnost (eq/ne) – pro výběrové (LT) a textové proměnné, když kontrolujete konkrétní zvolenou hodnotu.
• Porovnání velikosti (gt/ge/lt/le) – pro čísla a data: limity, rozsahy, termíny.
• Obsahuje / neobsahuje (like/nlike) – pro hledání podřetězce v textu nebo prvku ve vícehodnotové proměnné.
• Prázdnost (isn/isnn) – nejčastější operátor pro řízení viditelnosti a povinnosti (např. „skryj, dokud není vyplněno").

Příklady použití

Příklad 1 (jednoduchý) – skrýt proměnnou, dokud není vyplněn předpoklad

Cíl: Skrýt proměnnou „Celková cena objednávky bez DPH", dokud je proměnná „Výběr čísla objednávky" prázdná.

Nastavení bloku:

• Funkce: Skrýt
• Cílová proměnná: Celková cena objednávky bez DPH
• Podmínka: proměnná „Výběr čísla objednávky" → operátor „je prázdný" (isn)

Cena se tak schová pokaždé, když není vybrané číslo objednávky.

Příklad 2 (střední) – automatický výpočet operací s čísly

Cíl: Spočítat „Projektová rezerva v %" jako procentuální podíl proměnných „Projektová rezerva" a „Celková nabízená cena", ale jen pokud je cílová proměnná zatím prázdná.

Nastavení bloku:

• Funkce: Změnit
• Cílová proměnná: Projektová rezerva v %
• Podmínka: proměnná „Projektová rezerva v %" → operátor „je prázdný" (isn)
• Typ změny: Operace s čísly
  • 1. proměnná: Projektová rezerva
  • operace: „kolik % tvoří z" (percentPortionOf)
  • 2. proměnná: Celková nabízená cena

Jakmile je cílová proměnná prázdná, hodnota se dopočítá automaticky z obou vstupů.

Příklad 3 (složitější) – podmíněná povinnost a validace s kombinací podmínek

Cíl: Proměnná „Důvod zamítnutí" má být povinná, když je „Výsledek schvalování" = „Zamítnuto", a zároveň chceme omezit délku odůvodnění. Řešíme to dvěma bloky nad stejnou proměnnou.

Blok A – podmíněná povinnost:

• Funkce: Povinná proměnná
• Cílová proměnná: Důvod zamítnutí
• Podmínka: proměnná „Výsledek schvalování" → operátor „rovná se" (eq) → hodnota „Zamítnuto"

Blok B – validace délky:

• Funkce: Validovat
• Cílová proměnná: Důvod zamítnutí
• Typ validace: Maximální délka textu (maxTextLength), hodnota 200
• Chybová hláška: „Odůvodnění může mít nejvýše 200 znaků."

Tipy a časté chyby

Doporučení

• Začněte funkcí, ne podmínkou. Nejdřív si ujasněte, co se má stát (funkce) a na čem (cílová proměnná), a teprve potom řešte, kdy (podmínky).
• Operátory „je prázdný" / „není prázdný" jsou nejuniverzálnější pro řízení viditelnosti a povinnosti – fungují na všech typech proměnných.
• Víc pravidel pro jednu proměnnou je v pořádku; jen pamatujte, že u funkce Změnit rozhoduje pořadí bloků (platí poslední splněné pravidlo).
• Spustit při změně využijte, když podmínka závisí na proměnné, jejíž změna by jinak přehodnocení nevyvolala.
• Pro složené výrazy kombinujte skupiny podmínek (spojka mezi skupinami) se spojkami uvnitř skupiny – tím získáte logiku typu (A AND B) OR C.
• Vždy otestujte v běžícím případu: otevřete úkol, měňte vstupní proměnné a sledujte chování. Pro ladění nahlédněte do záložky Skript.
• U validací vyplňte srozumitelnou chybovou hlášku pro všechny jazyky instance.

Časté chyby

• Funkce versus výchozí oprávnění proměnné. makeReadOnly zabere jen u proměnné výchozím stavem W (k zápisu), makeWritable jen u R (ke čtení) a makeMandatory jen u proměnné se zápisem (W). Při špatném oprávnění to vypadá, že se „nic neděje".
• Nabídka operátorů a typů závisí na typu proměnné. Pokud očekávaný operátor, typ změny nebo validace chybí, příčinou je skoro vždy typ cílové (nebo testované) proměnné – zkontrolujte ho. Omezení mají hlavně checkbox, seznam dokumentů, vícehodnotová proměnná a dynamické řádky.
• Většina typů změn potřebuje jednohodnotovou proměnnou (tvar_multi = null). U vícehodnotových máte prakticky jen Konstantu.
• Porovnání proti proměnné funguje jen mezi kompatibilními typy. Když cílová proměnná není v nabídce, nejde o chybu, ale o nekompatibilní typ (text vs. číslo, checkbox vs. necheckbox, rozdílná vícehodnotovost).
• Aktivní hledání proměnné blokuje přidání podmínky. Když nejde přidat podmínka, nejdřív zrušte filtr „Hledat proměnnou".
• Globální přepínač „Aktivní všechny" může vypnout všechny podmínky najednou. Pokud „nic nefunguje", zkontrolujte, jestli je zapnutý – a nezapomeňte, že i jednotlivé bloky mají vlastní přepínač Aktivní.
• Validace nepoužívá seskupení AND/OR – pracuje s jedinou podmínkovou skupinou. Pro složitější logiku rozdělte chování do více bloků.
• Ručně upravený skript může znemožnit vizuální builder. Pokud skript nejde převést zpět na bloky, modal zůstane na záložce Skript a dál konfigurujete jen textově.
• Pořadí bloků u funkce Změnit. Když do téže proměnné zapisuje víc pravidel, výsledek určuje poslední splněné pravidlo – při neočekávané hodnotě zkontrolujte pořadí.