Příklad z praxe - definovatelná agenda Reklamace

Ostatní návody ze skupiny o definovatelných objektech (viz seznam na konci stránky) popisují jednotlivé obecné mechanismy odděleně - jak založit business objekt, jak přidat položku, jak udělat tiskovou sestavu apod. Tento návod je oproti tomu jeden souvislý, konkrétní příběh od úplného začátku až po nasazení do produkce a úklid: dokladová agenda Reklamace, na které si ukážeme prakticky všechny důležité možnosti definovatelných business objektů pohromadě. Používejte jej jako referenční scénář - jednotlivé kroky odkazují na obecné návody, kde najdete detailní vysvětlení dané dílčí techniky.

Cíl příkladu

Vytvoříme dokladovou agendu Reklamace:

• na hlavičce dokladu se zadává firma (to je u dokladového business objektu k dispozici automaticky, viz krok 1) a osoba - vlastní položka s odkazem do číselníku, na které si ukážeme obecnou techniku tvorby referenčních položek s cizím klíčem,
• vedle toho založíme i samostatný definovatelný číselníkový objekt Typy reklamací, který demonstruje, že business objekty lze kombinovat,
• řádky mohou být trojího druhu - volný text, text doplněný počtem, nebo skladová karta se skladem a počtem - podle toho, jaký typ řádku si uživatel zvolí (mechanismus "Seznam layoutů pro multigrid"),
• nad agendou existuje vlastní tisková sestava, která u řádku se skladovou kartou navíc zobrazí aktuální stav dané karty na všech skladech,
• celé řešení lze přenést z testovacího prostředí do produkce přes instalační sadu,
• a nakonec si ukážeme, jak systém brání nekonzistentnímu smazání souvisejících definic.

1. Hlavičkový business objekt Reklamace

Podle kapitoly Vytvoření definovatelného business objektu založte v agendě Definice business objektů nový objekt:

• Typ: Doklad
• Název třídy: Complaint
• Popisek: Reklamace
• Název tabulky a API endpoint se předvyplní automaticky podle názvu třídy - ponechte je. Protože je Název třídy anglický, výsledek dává smysl i jazykově: tabulka Complaints, endpoint complaints (viz vysvětlení principu v kapitole Vytvoření definovatelného business objektu).

Definici uložte a poznamenejte si vygenerované CLSID - budete jej potřebovat v dalších krocích.

2. Definovatelný číselník Typy reklamací

Ukážeme si, že business objekty lze kombinovat - vedle dokladu vytvoříme ještě samostatný definovatelný číselníkový business objekt:

• Typ: Číselníkový objekt
• Název třídy: ComplaintType
• Popisek: Typ reklamace

Uložte a podle kapitoly Vytvoření definovatelné agendy nad ním rovnou vytvořte i jednoduchou číselníkovou agendu Typy reklamací. Po restartu (viz krok 5) do ní naplňte několik základních záznamů, např. Vada zboží, Nedodání, Jiné.

3. Vlastní položka hlavičky s odkazem do číselníku (Osoba)

Podle kapitoly Doplnění vlastních položek doplňte na objekt Complaint položku s odkazem do číselníku osob - na tomto konkrétním případě je vidět obecná technika, kterou použijete pro odkaz do jakéhokoli systémového číselníku (firmy jsou bohužel výjimka, viz poznámka níže):

1. V editoru položky zadejte Název položky: PERSON - technický název pište anglicky, stejně jako u business objektu v kroku 1.
2. Popis a Popisek položky naopak zadejte česky: Osoba. Tyto texty totiž vidí přímo uživatelé v aplikaci.
3. Datový typ nastavte na Identifikátor - ne na Znaky! Právě datový typ Identifikátor je jediný, u kterého se v poli Způsob editace vůbec nabídne volba Číselník - u datového typu Znaky je k dispozici jen Adresářová cesta a Volby, žádný číselník. (Sloupec "Databázový typ" v přehledu položek pak u takové položky nadále ukazuje "Identifikátor", zatímco obecný "Datový typ" v API se stále jmenuje podle staršího názvosloví "Znaky" - jde o dva různé, historicky oddělené popisy typu položky v ABRA Gen, nenechte se zmást tím, že oba používají podobná slova pro různé věci.)
4. Způsob editace nastavte na Číselník - zadání hodnot(y).
5. Do pole Číselník zadejte přesně Číselník osob. Toto pole nefiltruje našeptáváním podle části textu - buď zadáte přesný název číselníku (Popisek), a systém jej sám dosadí, nebo otevřete rozbalovací seznam (Alt+šipka dolů) a v abecedně řazeném seznamu (řazeném podle znaku, ne podle české abecedy - takže "Č" je hned za "C", ne až za "Z") jej najdete ručně. Nepřesný nebo částečný text se může tiše navázat na jiný, podobně pojmenovaný číselník (např. zadání "firmy" se místo číselníku firem napojí na první číselník, který slovo "firmy" obsahuje kdekoli v názvu) - po zadání si proto vždy zkontrolujte, že se v poli Číselník zobrazuje přesně očekávaný název.
6. Zatrhněte Extra a poté Cizí klíč (viditelné a zaškrtnutelné až pro datový typ Identifikátor se způsobem editace Číselník) - v tomto pořadí, protože jakmile je Cizí klíč jednou uložený, pole Číselník se uzamkne a nejde už dodatečně změnit ani opravit (zkusíte-li to, systém nahlásí, že položku "Třída číselníku" nelze měnit). Pokud se spletete, položku smažte a založte znovu, oprava už nejde.

Po uložení systém automaticky přejmenuje položku na X_PERSON_ID - u datového typu Identifikátor se za název položky vždy automaticky přidá přípona _ID, navíc k obvyklé předponě X_ pro Extra položky.

4. Řádkový objekt se třemi typy řádků

Podle kapitoly Vytvoření řádkového objektu založte objekt typu Řádek s Názvem třídy ComplaintLine, Popiskem Řádky reklamace, Třídou hlavičky nastavenou na Complaint a zatrženou volbou Kolekce řádků (hlavní kolekce).

Řádky reklamace mají být trojího druhu - typ 1 (Text) pro volnou textovou poznámku, typ 2 (Text s počtem) pro poznámku doplněnou množstvím, a typ 3 (Skladová karta) pro konkrétní reklamovanou položku se skladem a počtem. Na řádkový objekt doplňte tyto vlastní položky (u všech zatrhněte Extra a pište technický Název anglicky, Popis/Popisek naopak česky - viz krok 3):

4a. Rozhodná položka ROWTYPE

1. Založte položku ROWTYPE (Popisek Typ řádku) s Datovým typem Celé číslo a Způsobem editace Skrytý seznam (combo box) - volbu Seznam layoutů pro multigrid lze zatrhnout až u položky typu Celé číslo se způsobem editace Skrytý seznam, Svislý přepínač nebo Vodorovný přepínač; u výchozího způsobu editace (Výchozí) zůstane needitovatelná. Teprve po nastavení Skrytého seznamu ji zatrhněte - tato položka se tak stane rozhodnou položkou pro layout multigridu (na jeden hlavičkový objekt lze mít takto označenou jen jednu položku).
2. Do pole Počítat od zadejte 1 - tím určíte, že první řádek seznamu voleb bude odpovídat hodnotě 1, ne výchozí 0.
3. Do pole Volby (víceřádkové pole, technicky vlastnost Enumeration) zadejte na tři samostatné řádky:
   1. Text
   2. Text s počtem
   3. Skladová karta

4b. Položky pro jednotlivé typy řádku

• TEXT (Popisek Text) - Datový typ Znaky - pole Datový typ není při založení položky předvyplněné, hodnotu je nutné vždy vybrat explicitně (jinak systém při uložení nahlásí "Položka 'Datový typ' není nastavena."). Použije se u řádků typu 1 (Text) a typu 2 (Text s počtem).
• QUANTITY (Popisek Počet) - Datový typ Celé číslo - použije se u řádků typu 2 (Text s počtem) a typu 3 (Skladová karta).
• STORE (Popisek Sklad) - Datový typ Identifikátor, Způsob editace Číselník - zadání hodnot(y), Číselník = Číselník skladů, s cizím klíčem - postup zadání stejný jako u položky PERSON v kroku 3. Použije se u řádků typu 3 (Skladová karta).
• STORECARD (Popisek Skladová karta) - Datový typ Identifikátor, Způsob editace Číselník - zadání hodnot(y), Číselník = Číselník skladových karet, s cizím klíčem - postup zadání stejný jako u položky PERSON v kroku 3. Na rozdíl od firem jsou oba tyto systémové číselníky jako odkazovaný cíl k dispozici a fungovaly bez problémů. Použije se u řádků typu 3 (Skladová karta).

4c. Příprava layoutů v editoru rozložení sloupců

Nově založená kolekce řádků se na záložce Obsah agendy zobrazí zcela bez sloupců, dokud jí layout ručně nepřipravíte - obecný postup popisuje návod Editor rozložení sloupců multigridu, zde je konkrétní postup pro všechny tři typy řádku reklamace. Editor rozložení sloupců vždy pracuje s layoutem, který odpovídá aktuálně vybranému/otevřenému řádku v mřížce (dialog to potvrzuje popiskem "Aktivní pro aktuální data") - proto je potřeba mít pro každý typ řádku napřed alespoň jeden skutečný řádek s danou hodnotou položky Typ řádku:

1. V agendě Reklamace založte nebo otevřete zkušební záznam a na záložce Obsah přidejte nový řádek (funkce Přidat). Do pole Typ řádku vyberte hodnotu Text a řádek uložte.
2. Klikněte pravým tlačítkem myši na mřížku řádků a zvolte Editor rozložení sloupců. Dialog by měl ukazovat Rozložení: 1 (odpovídá právě přidanému řádku typu Text).
3. Klikněte pravým tlačítkem myši do plochy editoru a zvolte Přidat sloupec. V otevřeném stromu položek řádkového objektu Řádky reklamace zatrhněte položku TEXT a potvrďte OK.
4. V hlavním dialogu potvrďte tlačítkem OK a na dotaz, zda chcete uložit změnu (projeví se u ostatních uživatelů při dalším načtení rozložení sloupců), odpovězte Ano. Tím vznikne Globální rozložení sloupců pro hodnotu 1, platné pro všechny uživatele agendy.
5. Přidejte druhý řádek, tentokrát s hodnotou Typ řádku Text s počtem, a řádek uložte. Znovu otevřete Editor rozložení sloupců - tentokrát by měl ukazovat Rozložení: 2. Stejným postupem přidejte položky TEXT a QUANTITY a uložte (OK → Ano).
6. Přidejte třetí řádek s hodnotou Typ řádku Skladová karta, a řádek uložte. Znovu otevřete Editor rozložení sloupců - tentokrát by měl ukazovat Rozložení: 3. Přidejte postupně položky STORE, STORECARD a QUANTITY a uložte (OK → Ano).

Od této chvíle mřížka na záložce Obsah automaticky nabízí jiné sloupce podle toho, jakou hodnotu Typ řádku má právě otevřený/editovaný řádek - to je přesně mechanismus "Seznam layoutů pro multigrid", který měl podle zadání produktového vlastníka demonstrovat, že jeden řádkový objekt může mít podle rozhodné položky různé sloupcové rozložení.

5. Definice agendy Reklamace a restart

Podle kapitoly Vytvoření definovatelné agendy vytvořte nad objektem Complaint dokladovou agendu se zobrazovacím názvem Reklamace.

Po každé změně definic (business objekt, položky, agenda) systém upozorní, že je potřeba restartovat aplikační server - v tomto příkladu jsme restart museli provést celkem třikrát (po založení business objektů a položek hlavičky, po založení agendy Typy reklamací, po založení agendy Reklamace) a pokaždé to bylo skutečně potřeba - bez restartu se nové/změněné definice v běžícím spojení neprojeví. Počítejte tedy s více restarty, ne jen s jedním na konci.

Po restartu a přihlášení agendu Reklamace otevřete - v seznamu uvidíte sloupce Číslo dokladu, Stav, Datum, Firma, Vytvořil, Opravil a v detailu záložky Hlavička / Firma / Obsah přesně jako u systémové dokladové agendy.

Založte i odpovídající řadu dokladů a nastavte její ochranu jako chráněný objekt podle kapitoly Řada dokladů jako chráněný objekt, a nastavte práva k oběma novým agendám podle kapitoly První spuštění a kontrola agendy.

6. Procesní řízení

Jak je uvedeno v poznámce u kroku 1, dokladový business objekt má procesní řízení (pole Stav, Zodpovědná role, Zodpovědná osoba, záložka Historie změn stavu) k dispozici bez jakéhokoli dalšího nastavení. Otevřeli jsme detail nového záznamu a sekci Procesní řízení jsme v hlavičce viděli rovnou.

7. Zkušební záznam

Založte zkušební reklamaci - na hlavičce vyberte firmu (standardní pole) a osobu (naši vlastní položku), přidejte alespoň jeden textový řádek (typ 1), jeden textový řádek s počtem (typ 2) a jeden řádek se skladem, skladovou kartou a počtem (typ 3). Ověřte uložení, správné zobrazení sloupců podle typu řádku a funkčnost omezení a třídění.

8. Tisková sestava se stavy skladu

Podle návodu Tisková sestava nad definovatelnou agendou si nejprve uděláme základní sestavu průvodcem a poté ji rozšíříme o vlastní dataset se stavy zásob - konkrétní příklad použití obecného postupu z kapitoly Rozšíření o data mimo automaticky generovaný DynSQL.

8a. Základní sestava průvodcem

1. V agendě Reklamace spusťte průvodce tiskovou sestavou přímo nad automaticky generovaným DynSQL - jako zdroj dat vyberte toto DynSQL a ve stromu polí přidejte položky z větve Main (hlavička) a z podřízené větve Rows (řádková kolekce).
2. Dokončete průvodce. Výsledná sestava zvládne vytisknout hlavičku i všechny tři typy řádků (jejich společné i specifické sloupce), ale u řádků se skladovou kartou (typ 3) zatím nezobrazí nic navíc - to doplníme v dalším kroku.

8b. Rozšíření o stav skladových karet na jednotlivých skladech

U řádku se skladovou kartou (typ 3) chceme navíc zobrazit, kolik kusů dané karty je aktuálně na kterém skladu - tento údaj automaticky generované DynSQL neobsahuje, protože leží mimo agendu Reklamace. V systému jej ale najdeme v tabulce StoreSubCards ("dílčí skladové karty") - to je stejná tabulka, ze které čerpá stav zásob na skladech i standardní agenda Skladové karty. Její klíčová pole jsou StoreCard_ID (odkaz na skladovou kartu), Store_ID (odkaz na sklad) a Quantity (množství na daném skladu) - jeden řádek této tabulky odpovídá jedné kombinaci karta/sklad.

1. Otevřete nástroj DynSQLEditor.exe a najděte automaticky generované DynSQL agendy Reklamace (v seznamu Dynamické SQL příkazy se jmenuje podle interního názvu agendy s příponou Site, např. ReklamaceSite).
2. Uložte si z něj vlastní upravitelnou kopii, napojenou na stejný programový bod. Na subzáložce Datasety uvidíte dva existující datasety - MAIN (hlavička, s automaticky přidanými joiny na řadu dokladů, firmu, období, procesní stav a uživatele) a ROWS (řádková kolekce, s polem Master nastaveným na MAIN a napevno napsanou podmínkou WHERE A.Parent_ID = :ID).
3. V seznamu datasetů klikněte pravým tlačítkem myši a zvolte Nový - vznikne dataset s výchozí šablonou SELECT {FIELDS} FROM {WHERE}, kterou přepíšete. Vyplňte:
   • Název: STORESUBCARDS
   • Popiska: Stav skladové karty na skladech
   • Master: ROWS (do tohoto textového pole název datasetu napíšete ručně, nejde o výběr ze seznamu) - tím se nový dataset stane podřízeným datasetu s řádky.
   • SQL dotaz:

     SELECT {FIELDS} FROM StoreSubCards A {JOIN} WHERE A.StoreCard_ID = :X_STORECARD_ID {ANDWHERE}

4. Na subzáložce Rozšířené fieldy tohoto nového datasetu (ne na subzáložce Aliasy - ta je pro JOIN na tabulky odpovídající existující business třídě, což tabulka stavů zásob není) doplňte dvě položky, každou s vlastním SQL výrazem: Store_ID (výraz A.Store_ID) a Quantity (výraz A.Quantity, popiska "Množství"). U položky Store_ID vyplňte i Packed CLSID business třídy skladu, abyste v sestavě mohli použít tečkovou notaci Store_ID.Code.

U řádků typu 1 a 2, kde položka STORECARD není vyplněná, dotaz logicky nevrátí žádný řádek - v sestavě se tedy pod nimi žádný stav zásob nezobrazí.

4. Dotaz uložte a v editoru tiskové sestavy nad touto vlastní kopií DynSQL přidejte vnořený pás (band) napojený na nový dataset STORESUBCARDS, umístěný pod pásem datasetu ROWS - obdobně jako je popsáno v kapitole Popis jednotlivých funkcí editoru pro vkládání vnořených dat.
5. Do nového pásu vložte pole Quantity (množství) a pole identifikující sklad. Pokud jste u rozšířené položky Store_ID v předchozím kroku vyplnili Packed CLSID business třídy skladu, můžete konkrétní kód nebo název skladu zadat tečkovou notací přes ID, stejně jako je obecně popsáno v kapitole Dynamické SQL - subzáložka Datasety (tam na příkladu MAIN.Currency_ID.Code): zde tedy Store_ID.Code, případně Store_ID.Name. Bez vyplněného Packed CLSID budete mít k dispozici jen samotnou hodnotu identifikátoru skladu, bez možnosti se přes ni dostat k jeho kódu či názvu.

Výsledná sestava pak pro každou reklamaci vytiskne hlavičku, pod ní všechny řádky (s jejich sloupci podle typu) a u každého řádku se skladovou kartou navíc jeden dílčí řádek za každý sklad, na kterém se daná karta nachází, s jeho kódem a aktuálním množstvím.

9. Přenos do produkce

Až je celé řešení v testovacím prostředí hotové a ověřené, přeneste je podle návodu Přenos definovatelného řešení mezi spojeními pomocí instalační sady do produkčního spojení. Konkrétně pro tento příklad do instalační sady přidejte tyto položky (typy objektů v Průvodci přidáním položek, viz odkazovaný návod pro plné vysvětlení každého typu):

• Definovatelné business objekty - všechny tři: Complaint, ComplaintType i ComplaintLine. Nezaměňte za typ Definovatelné číselníky - přestože ComplaintType má Typ Číselníkový objekt, jde stále o tentýž typ objektu instalační sady jako u ostatních dvou.
• Definovatelné agendy - obě agendy: Reklamace i Typy reklamací. Průvodce by měl při jejich přidání sám nabídnout doplnění chybějících Definovatelných business objektů, na kterých jsou postaveny.
• Definovatelné položky - všechny vlastní položky ze všech tří business objektů (PERSON, ROWTYPE, TEXT, QUANTITY, STORE, STORECARD).
• Rozložení sloupců Editovatelného seznamu - layout multigridu kolekce ComplaintLine vytvořený v kroku 4c (všechny tři hodnoty rozhodné položky ROWTYPE dohromady). Přidejte jej ručně - na rozdíl od agendy a business objektu jej průvodce automaticky nenabídne, i kdybyste na něj v cílovém spojení zapomněli. I po přidání a naimportování se ale reálně neuplatní (viz Přenos definovatelného řešení mezi spojeními pomocí instalační sady) - připravte si layout v produkčním spojení raději rovnou znovu ručně stejným postupem jako v kroku 4c.
• Definovatelné DynSQL k definovatelným agendám - pouze pokud jste v kroku 8b vytvořili vlastní upravitelnou kopii DynSQL s datasetem STORESUBCARDS. Pokud jste zůstali jen u automaticky generovaného DynSQL a sestavy z kroku 8a, tento typ nepotřebujete. Místo instalační sady lze tuto konkrétní kopii DynSQL přenést i přímo z DynSQLEditor.exe (menu Export/Import → Definovatelné agendy → Exportovat, s připojením přímo na produkční spojení) - obě cesty jsou rovnocenné, viz Rozšíření o data mimo automaticky generovaný DynSQL. Tato přímá cesta ale přenáší jen samotné DynSQL - business objekty Complaint/ComplaintType/ComplaintLine a obě agendy musí být v produkčním spojení už vytvořené (instalační sadou nebo ručně), jinak se DynSQL nemá k čemu navázat.
• Tiskové sestavy - vlastní tisková sestava z kroku 8.

Po přidání všech položek zkontrolujte hlášení o chybějících závislých objektech (mělo by se týkat jen business objektů, agend a DynSQL - u rozložení sloupců multigridu na něj nespoléhejte, viz odkazovaný návod), sadu exportujte a v produkčním spojení naimportujte. Po importu znovu restartujte aplikační server a ověřte, že reklamaci lze v produkčním prostředí založit, že multigrid u řádků nabízí stejné layouty podle typu řádku jako v testu, a že jde vytisknout stejná sestava se stavy skladu.

10. Bezpečné rušení definic (validace závislostí)

Na závěr ověřte, že systém nedovolí nekonzistentní smazání provázaných definic a jasně napoví, v jakém pořadí je bezpečné je rušit - zkuste v agendě Definice business objektů smazat definici Complaint, dokud k ní ještě existuje definice agendy, vlastní položky nebo vlastní DynSQL definice tiskové sestavy, a očekávejte, že systém smazání odmítne a validační hláškou upozorní, které závislé definice je potřeba zrušit nejdříve.

Přehled použitých obecných návodů

Tento příklad kombinuje techniky popsané v následujících obecných návodech ze stejné skupiny:

• Jak vytvořit definovatelnou agendu - základní postup, řádkové objekty, řada dokladů.
• Editor rozložení sloupců multigridu - příprava layoutů podle rozhodné položky.
• Definovatelný formulář a definovatelné panely na definovatelné agendě.
• Tisková sestava nad definovatelnou agendou - průvodce sestavou i ruční rozšíření DynSQL o subkolekci.
• Přenos definovatelného řešení mezi spojeními pomocí instalační sady.
• Přílohy definovatelného business objektu přes API a skriptování - pokud byste chtěli k reklamaci připojovat přílohy (fotografie vadného zboží apod.), stačí na hlavičkovém objektu doplnit identifikaci propojení s přílohami.
• Definovatelný business objekt kompletně přes REST API - stejné řešení lze celé založit i čistě přes API.