Jak vytvořit definovatelnou agendu

Definovatelná agenda umožňuje vytvořit vlastní evidenci, která není součástí standardně dodávaných agend. Její záznamy se ukládají do samostatné databázové tabulky a lze s nimi pracovat ve vizuální agendě, pomocí skriptování i prostřednictvím API. V tomto návodu si ukážeme vytvoření definovatelného business objektu, doplnění vlastních položek a vytvoření agendy, ve které budou uživatelé data evidovat.

Celkový koncept a přehled toho, co všechno definovatelné objekty umožňují, popisuje úvodní kapitola Definovatelné objekty - úvod - tento návod už se věnuje jen konkrétnímu postupu založení.

Vizuální přístup k definovatelným agendám je dostupný pouze při licencování na pojmenované uživatele.

Definice nejprve vytvořte a ověřte v testovacím spojení. Odstraněním definice business objektu se odstraní také jeho databázová tabulka a všechna data, která obsahuje. U objektu s řádky se odstraní také závislé definice řádků a jejich tabulky.

Definovatelný business objekt a definovatelná agenda

Vytvoření vlastní agendy se skládá ze dvou navazujících částí:

V agendě Definice business objektů vytvoříte datový objekt a jeho databázovou tabulku. Zde určíte typ objektu, interní názvy a případné vlastní položky.
V agendě Definice agend vytvoříte nad business objektem vizuální agendu a určíte její název a umístění v nabídce agend.

Vytvoření definovatelného business objektu

Otevřete agendu Definice business objektů ve složce Nástroje přizpůsobení → 1 - Definice a zvolte funkci Nový.

Nejprve vyberte vhodný Typ business objektu:

Prázdný objekt - obsahuje v základu pouze položku Název.
Číselníkový objekt - obsahuje v základu položky Kód a Název a výsledná agenda se chová jako číselník.
Doklad - generický dokladový objekt, pro který lze vytvořit dokladovou agendu.
Řádek - podřízený objekt navázaný na hlavičkový business objekt. Řádkový objekt nemá samostatnou agendu.

Dále vyplňte základní údaje:

Název třídy - unikátní interní název business objektu bez mezer a diakritiky, například ServiceRecord. Volte anglický název - automaticky se z něj odvozuje název tabulky i API endpoint podle anglické konvence množného čísla (viz níže), takže u anglického názvu bude výsledek dávat smysl i jazykově. Název nesmí kolidovat se systémovým ani jiným definovatelným business objektem.
Popisek - srozumitelný název business objektu zobrazovaný uživatelům, například Servisní záznam. Na rozdíl od Názvu třídy jej pište přirozeně česky. Popisek je povinný.
Název tabulky - interní název databázové tabulky. Po zadání názvu třídy se předvyplní názvem třídy s písmenem s na konci - jde o automatické tvoření anglického množného čísla (např. ServiceRecord → ServiceRecords), proto viz doporučení anglického Názvu třídy výše. Systém k názvu při vytvoření tabulky automaticky přidá prefix ET$, proto jej nezadávejte. Celý název včetně prefixu může mít nejvýše 31 znaků.
API endpoint - unikátní název, pod kterým bude objekt dostupný v API. U objektů s výjimkou typu Řádek je povinný. Po zadání názvu třídy se automaticky předvyplní malými písmeny a s písmenem s na konci - stejná konvence anglického množného čísla jako u názvu tabulky (např. servicerecords), odpovídající tvaru, v jakém API endpointy pojmenovávají i systémové objekty.
CLSID - jednoznačný identifikátor business objektu. Při založení záznamu jej systém vygeneruje automaticky.

Typ objektu, název tabulky a CLSID lze nastavit pouze při založení definice. Před prvním uložením proto jejich hodnoty pečlivě zkontrolujte.

U typu Doklad můžete zatrhnout volbu Doklad s doručovací a korespondenční adresou, pokud má doklad obsahovat doručovací a korespondenční adresu.

Pole Identifikace příloh je na formuláři k dispozici u všech typů business objektu, nejen u typu Doklad - včetně typu Prázdný objekt a Číselníkový objekt. Výjimkou je typ Řádek, který se do registru vazeb na přílohy nezahrnuje. Pokud pole ponecháte nulové, systém při uložení přidělí volné číslo automaticky.

Na obrázku je ukázka vyplněné definice číselníkového objektu, který byl podle tohoto postupu skutečně vytvořen při ověření návodu. Byl použit typ Číselníkový objekt, název třídy NavodAgenda2608, popisek Ukázková agenda pro návod, tabulka NavodAgenda2608s a API endpoint navodagenda2608s.

Definici uložte. Systém vytvoří databázovou tabulku s primárním klíčem a potřebnými indexy a novou definici zaregistruje.

Doplnění vlastních položek

Pokud má business objekt obsahovat další údaje, označte jeho uloženou definici a spusťte funkci Otevřít def. položky. V otevřené agendě doplňte požadované uživatelsky definovatelné položky.

Při jejich vytváření postupujte podle návodu Jak vytvořit definovatelnou položku. Po uložení ověřte zejména datový typ, délku, povinnost zadání, možnost použití v omezení a možnost řazení.

U položek definovatelného business objektu vždy zatrhněte volbu Extra (podrobný popis v návodu Jak vytvořit definovatelnou položku) - výsledný prefix bude X_. Nezatržená (obyčejná) položka s prefixem U_ se totiž fyzicky neukládá do vlastní tabulky business objektu, ale do společné (starší, EAV) tabulky UserData sdílené napříč celým systémem - u nově vytvořeného definovatelného business objektu, jehož smyslem je mít právě vlastní dedikovanou tabulku, by tím ztratila smysl. Extra položka navíc jako jediná podporuje vytvoření indexu a cizího klíče a nemá omezení délky na 500 znaků, které pro obyčejné položky platí.

Stejně jako u business objektu volte i technický Název položky anglicky (velkými písmeny, bez diakritiky a mezer) - odpovídá to konvenci použité napříč celým systémem pro názvy databázových sloupců. Naproti tomu Popis a Popisek položky, které vidí uživatelé v uživatelském rozhraní, pište přirozeně česky.

Při původním ověření byl takto doplněn údaj Poznámka typu Znaky o délce 100, tehdy ještě s technickým názvem POZNAMKA (uložená položka v systému jako X_POZNAMKA) - v dalších návodech této skupiny (viz níže) už technický název volíme anglicky podle výše uvedeného doporučení, např. NOTE (X_NOTE).

Příklad: položka s odkazem do číselníku

Kromě prostého textu můžete na hlavičkový i řádkový objekt přidat i položku typu odkaz do číselníku - referenci na jiný systémový nebo definovatelný číselník (typicky např. na osobu, skladovou kartu apod.). Postupujte stejně jako u textové položky, ale zvolte datový typ Identifikátor (ne Znaky - u datového typu Znaky se způsob editace Číselník vůbec nenabízí) a způsob editace Číselník - zadání hodnot(y). Do navazujícího pole Číselník zadejte přesný název (Popisek) cílové třídy, např. Číselník osob nebo Číselník skladových karet - pole nefiltruje podle části textu, takže nepřesně nebo jen částečně zadaný název se může tiše navázat na jiný, podobně pojmenovaný číselník; po zadání si proto vždy ověřte, že se v poli zobrazuje přesně očekávaný název, případně cílovou třídu vyberte ručně z rozbaleného seznamu (Alt+šipka dolů). Zatrhněte volbu Extra (viz výše) a teprve poté volbu Cizí klíč, která je dostupná právě jen pro tuto kombinaci (Extra + Identifikátor + Číselník) - v tomto pořadí, protože jakmile je Cizí klíč jednou uložen, pole Číselník se natrvalo uzamkne a nejde jej už dodatečně opravit (při špatně zvoleném číselníku je nutné položku smazat a založit znovu). Cizí klíč zajistí referenční integritu vazby na úrovni databáze - nepůjde uložit hodnotu, která v cílovém číselníku neexistuje, ani smazat záznam z cílového číselníku, je-li touto položkou použit. Po uložení systém k názvu položky automaticky připojí příponu _ID (např. položka OSOBA vznikne v systému jako X_OSOBA_ID).

Takto vytvořenou položku pak na formulář definovatelné agendy přidáte stejně jako kteroukoli jinou vlastní položku, viz výše.

Firmy (agenda Adresář firem) tímto způsobem odkázat nejde - v poli Číselník nejsou k dispozici ani přes GUI, ani přes API (pokus o nastavení firmy jako odkazovaného číselníku skončí chybou "Interface not supported"). Ostatní systémové číselníky (osoby, skladové karty, sklady) tímto postupem fungují bez problémů. U dokladového business objektu navíc pole Firma na hlavičce získáte automaticky bez jakékoli vlastní položky - viz kapitola výše.

Po uložení změn v definici položek ukončete klienty ABRA Flores na všech počítačích a restartujte aplikační server.

Vytvoření řádkového objektu

Pokud má doklad nebo jiný business objekt obsahovat vlastní řádky, vytvořte nejprve jeho hlavičkový objekt. Poté založte další definici s typem Řádek a nastavte položku Třída hlavičky.

Pokud je hlavičkou definovatelný doklad, můžete volbou Kolekce řádků určit, že se má řádkový objekt zpřístupnit jako jeho hlavní kolekce řádků. Jeden doklad může mít pouze jednu takovou kolekci. Pokud jako kolekci nastavíte jiný řádkový objekt, systém příznak u původní kolekce odebere.

Řádkový objekt můžete doplnit vlastními položkami stejným způsobem jako ostatní typy business objektů, tedy podle kapitoly Doplnění vlastních položek. Samostatnou definici agendy pro něj nevytváříte, protože jeho záznamy se zobrazují v rámci rodičovského objektu.

Na rozdíl od hlavičkového objektu se ale řádkový objekt v agendě nezobrazuje na samostatném detailu s variantním vstupním formulářem, ale jako řádek multigridu kolekce v rámci hlavičky. Nově založená vlastní položka se proto do zobrazených sloupců nemusí promítnout automaticky - je potřeba ji přidat přes Editor rozložení sloupců (vyvoláte pravým tlačítkem myši na libovolném řádku kolekce). Obecný postup práce s tímto editorem popisuje návod Jak používat editor rozložení sloupců nad editovatelnými seznamy.

Pokud mají mít různé řádky kolekce různou sadu sloupců podle svého typu (např. jeden řádek jen text, jiný odkaz na skladovou kartu), založte na řádkovém objektu položku typu Celé číslo se způsobem editace Skrytý seznam (combo box), Svislý přepínač nebo Vodorovný přepínač - u výchozího způsobu editace zůstane následující volba needitovatelná. V definici položky pak zatrhněte volbu Seznam layoutů pro multigrid (technický název pole IsMultigridLayoutIdent, popisováno také jako identifikace layoutu pro multigrid - viz popis pole). Podle hodnoty této položky pak systém pro daný řádek zobrazí odpovídající sloupcový layout. Na jeden hlavičkový objekt lze takto označit jen jednu položku.

Vytvoření definovatelné agendy

Otevřete agendu Definice agend ve složce Nástroje přizpůsobení → 1 - Definice a zvolte funkci Nový.

Vyplňte následující údaje:

Třída def. BO - vyberte dříve vytvořený business objekt. Nabízejí se prázdné, číselníkové a dokladové objekty; řádkové objekty samostatnou agendu nemají.
Interní název - unikátní technický název agendy bez mezer a diakritiky.
Zobrazovací název - název, pod kterým uživatelé agendu uvidí.
Popis - stručné vysvětlení účelu agendy.
Cesta - pomocí tlačítka Nastavit vyberte místo, ve kterém se agenda zobrazí v nabídce agend.

Ostatní technické identifikátory, například CLSID agendy, ID DynSQL a ID prog. bodu, systém vytvoří automaticky. Pro číselníkovou agendu automaticky vygeneruje také CLSID číselníku.

Na obrázku je ukázka vyplněné definice agendy nad business objektem Ukázková agenda pro návod. Byly použity hodnoty NavodAgenda2608 pro interní název, Ukázková agenda pro návod pro zobrazovací název a popis Číselník vytvořený podle návodu.

Při nastavení cesty byla při ověření použita větev Uspořádání dle modulů → Nástroje přizpůsobení → 1 - Definice.

Definici uložte. Systém zobrazí upozornění, že agenda bude dostupná až po novém spuštění programu. V ověřovaném klient-server prostředí ale samotný restart klienta nestačil. Bezpečný postup je tento: nastavit práva, ukončit klienty ABRA Flores na všech počítačích, restartovat aplikační server a potom klienta znovu spustit.

Řada dokladů jako chráněný objekt

Má-li definovatelná agenda dokladový typ business objektu, založte pro ni ještě odpovídající řadu v agendě Řady dokladů. Při založení řady z definovatelné agendy systém předvyplní typ dokladu - u definovatelných dokladů se používá typ Definovatelné doklady.

Řady dokladů obecně patří mezi chráněné objekty - obecný bezpečnostní mechanismus ABRA Flores, kterým lze pro jednotlivé role či skupiny rolí omezit, které záznamy dané řady uživatel uvidí (právo Zobrazit) a do kterých smí zapisovat, resp. na které smí vystavovat nové doklady (právo Použít). U definovatelných dokladů to dříve možné nebylo - teprve nedávno byla podpora chráněného objektu doplněna i pro ně (spolu s přejmenováním typu dokladu z pracovního označení Definovatelné objekty na Definovatelné doklady).

Ochranu nastavíte v agendě Role (případně Skupiny rolí) na záložce Práva k objektům. Ve stromu vlevo najděte větev Řady dokladů - pod ní se zobrazí i řada založená pro vaši definovatelnou agendu - a nastavte jí požadovaná práva Zobrazit/Použít. Podrobný obecný postup nastavení hodnot práv (přes místní nabídku nebo dvojklikem) popisuje kapitola Role - záložka Práva k objektům.

Pokud roli, pod kterou pracuje například účetní firmy A, nastavíte právo Použít pouze k řadě patřící "její" definovatelné agendě, nebude moci zakládat ani opravovat záznamy patřící do řady jiné firmy. Přesně tímto způsobem lze u definovatelného dokladu omezit přístup k datům podle firmy nebo uživatele - dříve u definovatelných objektů nešlo nastavit.

První spuštění a kontrola agendy

Ještě před prvním použitím nastavte uživatelům nebo rolím práva k nové agendě. V ověřeném postupu byla agenda zpřístupněna v roli Supervisor v agendě Role (příp. Skupiny rolí) na záložce Práva k funkcím ve větvi Definovatelné agendy. Bez těchto práv se agenda uživatelům nezobrazí.

Nová definovatelná agenda se v tomto stromu chová úplně stejně jako kterákoli výrobcem dodávaná agenda - po rozbalení své větve (pod ní se zobrazí i jednotlivé definovatelné agendy podle jejich zobrazovacího názvu) nabízí celý standardní soubor práv k funkcím, tedy nejen právo agendu vůbec otevřít, ale i jednotlivá dílčí práva jako Opravit, Tisknout, Vymazat, Přidat, Exportovat nebo Exportovat B2B. U dokladové definovatelné agendy s procesním řízením se navíc nabízí i dvojice specifických práv (Procesní řízení) Při opravě umožnit změnu zodpovědné role a osoby a (Procesní řízení) Opravovat doklad mimo zodpovědnost - stejná práva, jaká byste čekali u systémové dokladové agendy s procesním řízením. Žádné z těchto práv tedy není potřeba pro definovatelnou agendu speciálně dopracovávat.

Po novém spuštění programu otevřete agendu z místa, které jste nastavili v položce Cesta. Na obrázku je vidět výsledné umístění v nabídce agend po restartu aplikačního serveru a klienta.

Na detailu agenda používá variantní vstupní formulář. Vlastní položky se na něm po vytvoření nemusí zobrazit automaticky. Pokud v detailu svůj údaj nevidíte, otevřete z kontextové nabídky volbu Upravit variantní vstupní formulář, přepněte formulář do editace a přes volbu Uživatelské položky (přidat/odebrat) položku doplňte. Podrobný postup je součástí návodu Jak vytvořit definovatelnou položku.

Nakonec v agendě vytvořte zkušební záznam a ověřte jeho uložení, zobrazení vlastních položek, omezení, třídění a přístupová práva. Při ověření byl v agendě úspěšně založen záznam s kódem NAVOD a názvem Ukázkový záznam.

Pokud budete agendu používat také prostřednictvím API, ověřte dostupnost endpointu zadaného v definici business objektu.

Příklady použití

Postup popsaný výše je obecný a platí pro libovolný definovatelný business objekt. Kompletní, souvislý příklad, který kombinuje všechny popsané kroky (business objekt, vlastní položky, řádkový objekt s multigrid layouty, agenda, práva, tisková sestava, přenos instalační sadou i bezpečné rušení definic) na jednom reálném scénáři dokladové agendy Reklamace, najdete v samostatném návodu Příklad z praxe - definovatelná agenda Reklamace.

Tento návod je součástí skupiny návodů k definovatelným objektům. Další návody z této skupiny: