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í.
Zakládání nových definic v agendách Definice business objektů a Definice agend vyžaduje licenci na pojmenované uživatele i při vytváření přes API. Již vytvořenou definovatelnou agendu lze používat a zadávat do ní datové záznamy bez tohoto omezení tvorby definic.
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.
Formulář má skupiny Struktura business objektu, Technické údaje a Vizuální nastavení business objektu. Pole, která nejsou pro zvolený typ použitelná, zůstávají viditelná, ale jsou neaktivní. Úplný popis polí v pořadí výchozího formuláře najdete na záložce Detail.
Ve skupině Technické údaje vyplňte:
- Interní 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 připojením koncovky s (viz níže). Navržené hodnoty zkontrolujte. Název nesmí být shodný s jiným definovatelným business objektem. Systém jej zaregistruje s automatickým prefixem DefBO_, v příkladu jako DefBO_ServiceRecord. Prefix do pole nezadávejte.
- Zobrazovaný název - srozumitelný název business objektu zobrazovaný uživatelům, například Servisní záznam. Na rozdíl od interního názvu třídy jej pište přirozeně česky. Je povinný a nezávislý na názvu samostatné agendy.
- 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 prosté připojení koncovky (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). Systém přidá prefix defbo_, který se do definice nezadává. Pro práci s daty tedy použijte endpoint defbo_servicerecords.
- CLSID - jednoznačný identifikátor business objektu. Při založení záznamu jej systém vygeneruje automaticky.
Rozdíl mezi zadaným a úplným názvem třídy, tabulky, endpointu a agendy shrnuje kapitola Technické názvy a prefixy.
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 propojení s přílohami 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.
Příklad hodnot zadávaných do definice: typ Číselníkový objekt, Interní název třídy NavodAgenda2608, Zobrazovaný název Ukázková agenda pro návod, Název tabulky NavodAgenda2608s a API endpoint navodagenda2608s. Technické názvy se zadávají bez příslušných prefixů.
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.
V poli Číselník vybírejte registrovaný číselník. U vlastního business objektu typu Číselníkový objekt nejprve vytvořte jeho agendu typu Číselník. Při zadávání přes API rozlišujte CLSID business objektu a CLSID číselníku: vlastnost fieldrollclsid vyžaduje CLSID číselníku, nikoli CLSID jeho business objektu. U definovatelné agendy jde o hodnotu CLSID číselníku. Dokladový business objekt má standardní pole Firma již na hlavičce.
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 jednu třídu řádkového objektu lze takto označit jen jednu položku.
V seznamu hodnot této celočíselné položky nastavte jednotlivé typy řádků. Potom otevřete Editor rozložení sloupců a připravte sloupce pro odpovídající rozložení. Pokud mají mít rozložení rozdílné sloupce, vypněte při jejich úpravě volbu Editovat společně. Na zkušebních řádcích změňte hodnotu položky a ověřte, že se zobrazí zamýšlené sloupce.
Definovatelný doklad může mít i pouze hlavičku. Pokud nepotřebujete řádky, řádkový objekt nezakládejte; hlavní kolekce Rows je součástí struktury až po připojení odpovídajícího řádkového objektu.
Vytvoření definovatelné agendy
Otevřete agendu Definice agend ve složce Nástroje přizpůsobení → 1 - Definice a zvolte funkci Nový.
Ve skupině Business objekt vyberte třídu a zkontrolujte odvozený typ agendy. Poté doplňte skupinu Technické údaje. Pořadí a popis všech polí uvádí záložka Detail:
- 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í.
- Typ agendy - doplní se podle vybrané třídy, ručně jej nezadáváte.
- Interní název - unikátní technický název agendy bez mezer a diakritiky, například ServiceRecords. Prefix DefSite_ doplní systém automaticky; registrovaný název bude DefSite_ServiceRecords.
- Zobrazovaný 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.
Pro business objekt Ukázková agenda pro návod lze použít Interní název agendy NavodAgenda2608, Zobrazovaný název Ukázková agenda pro návod a Popis Číselník vytvořený podle návodu. Registrovaný interní název agendy pak bude DefSite_NavodAgenda2608.
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. Nabídka agend se po změně definice obnoví při novém spuštění klienta. Nastavte práva a klienta znovu spusťte. Obnova nabídky agend a načítání změněných definic jsou odlišné kroky; podrobnosti uvádí Obnovení definic.
Řada dokladů jako chráněný objekt
Pro business objekt typu Doklad založte řadu v agendě Řady dokladů funkcí Nový. Vyberte typ Definovatelné doklady (ZZ) a v poli Třída def. business objektu příslušný business objekt. Při založení řady z jeho agendy se vazba předvyplní. Hromadná funkce Generovat definovatelné doklady vynechává; řadu jim založte jednotlivě.
Ř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).
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.
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.
Po novém spuštění programu otevřete agendu z místa, které jste nastavili v položce Cesta.
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, použijte endpoint včetně automatického prefixu defbo_. Konkrétní požadavky uvádí návod Použití nového endpointu.
Obnovení definic
Uložení nebo smazání definice agendy vyvolá nové sestavení nabídky agend při příštím spuštění klienta. Již otevřené výběrové seznamy a formuláře nemusí novou definici převzít; zavřete je a znovu otevřete, případně znovu spusťte klienta. Z dostupnosti objektu v API proto nelze vyvozovat, že je již aktualizované i otevřené okno desktopového klienta.
V API se změny podporovaných metadat při zapnutém automatickém přenačítání projeví bez restartu serveru. Při vypnutém přenačítání je nutné cache obnovit správcem.
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:
- Definovatelné objekty - úvod
- Jak vytvořit definovatelnou agendu
- Jak připojit definovatelnou kolekci k existující agendě
- Tisková sestava nad definovatelnou agendou
- Definovatelný formulář a definovatelné panely na definovatelné agendě
- Přenos definovatelného řešení mezi spojeními pomocí instalační sady
- Příklad z praxe - definovatelná agenda Reklamace
- Přílohy definovatelného business objektu přes API a skriptování
- Definovatelný business objekt kompletně přes REST API
- Definovatelný business objekt přes OLE