Přílohy definovatelného business objektu přes API a skriptování
Definovatelný business objekt může podporovat připojení příloh - stačí mu na definici (viz Jak vytvořit definovatelnou agendu) nastavit pole Identifikace propojení s přílohami. Jakmile je toto číslo přiděleno, objekt získá kolekci AttachedDocuments a chová se z hlediska příloh stejně jako kterýkoli systémový objekt. Tento návod ukazuje, jak s přílohami definovatelného objektu pracovat programově - přes REST API a přes skriptování.
Přes REST API
V cestách k datům definovatelného objektu používejte API endpoint s automatickým prefixem defbo_. Pro hodnotu apinavodagendas uloženou v definici je tedy cesta k přílohám /demodata/defbo_apinavodagendas/<id-zaznamu>/attachments. Viz Technické názvy a prefixy.
Postup je stejný jako u připojení dokumentu k libovolnému systémovému dokladu, viz podrobný obecný příklad vytvoření dokumentu a jeho přiložení k dokladu. Zkráceně:
-
Vytvořte dokument v agendě Dokumenty - POST .../Documents s obsahem souboru zakódovaným do Base64 v poli Contents[].DataAsBytes.
-
Připojte jej k záznamu definovatelného objektu přes endpoint attachments daného objektu - PUT .../<api-endpoint-objektu>/<id-zaznamu>/attachments s tělem požadavku ve tvaru pole ID dokumentů, např. ["5400000101"].
-
Seznam připojených příloh záznamu přečtete přes GET .../<api-endpoint-objektu>/<id-zaznamu>/attachments, odpojíte je přes DELETE se stejným tělem požadavku jako u připojení.
Přes skriptování
Přílohu lze k definovatelnému business objektu připojit i skriptem - v zásadě třemi způsoby, popsanými níže. Vlastní kód skriptu se vytváří a spravuje v agendě Balíčky skriptů (obecný úvod do skriptování viz Definiční a vývojové prostředí - skriptování). Protože jde o obecně použitelné procedury pro práci s přílohami, které chcete volat z různých míst (z různých business objektů, tlačítek apod.), nejpraktičtější je uložit je jako samostatnou knihovnu, na kterou se pak ostatní skripty jen odkáží.
-
Otevřete agendu Balíčky skriptů (najdete ji přes globální hledání, nebo v nabídce Nástroje přizpůsobení).
-
Funkcí Nový založte nový balíček skriptů. Do pole Název zadejte jedinečný technický název bez diakritiky a mezer - např. abraDboPrilohy. Pokud už podobný balíček pro svá vlastní rozšíření máte, můžete samozřejmě přidat skript do něj a nezakládat nový.
-
Na subzáložce Projekt v liště navigátoru pod seznamem skriptů klikněte na Přidat - přidá se nový řádek pro definici skriptu.
-
V přidaném řádku nastavte pole Druh skriptu na Knihovna.
-
Do pole Název knihovny resp. třídy objektu zadejte název knihovny, opět bez diakritiky a mezer - např. PrilohyDefinovatelnychObjektu.
-
Přepněte na subzáložku Zdrojový kód a do editoru zdrojového kódu vložte kód procedury podle jedné z variant níže.
-
Funkcí Zkompilovat (klávesová zkratka Alt+F9) na panelu nástrojů subzáložky Zdrojový kód skript zkompilujte - pokud kód obsahuje chybu, kompilace na ni upozorní a je potřeba ji nejprve opravit.
-
Záznam uložte funkcí Uložit. Zaškrtávátko Zkompilovat dostupné přímo v editačním režimu při ukládání provede totéž, co samostatná funkce Zkompilovat výše, takže obě funkce není nutné volat obě zvlášť.
-
V horní části záložky Detail (hlavička balíčku) nastavte položku Stav na Používat - bez toho se skripty z balíčku nikdy nespustí, viz obecné Podmínky pro spouštění skriptů.
Knihovna sama o sobě nic automaticky nespouští - jde jen o sadu procedur/funkcí připravených k volání odjinud. Jak konkrétně knihovní proceduru AddAttachment zavolat (např. při uložení vašeho definovatelného dokladu), popisuje kapitola Zavolání knihovny z háčku business objektu na konci této části.
1. Nová příloha založená rovnou přes kolekci hlavního objektu
Příloha se vytvoří jako nový záznam přímo v kolekci AttachedDocuments hlavního objektu a uloží se společně s ním v jednom kroku:
Druh skriptu: Knihovna, Název knihovny: PrilohyDefinovatelnychObjektu
procedure AddAttachment(ABO: TNxCustomBusinessObject);
var
mAttachments: TNxCustomBusinessMonikerCollection;
mAttachment: TNxCustomBusinessObject;
begin
// ABO je business objekt, ke kterému přílohu připojujeme (musí mít nastavenou
// Identifikaci propojení s přílohami, viz úvod tohoto návodu)
mAttachments := ABO.GetCollectionMonikerForFieldCode(ABO.GetFieldCode('AttachedDocuments'));
mAttachment := mAttachments.AddNewObject;
mAttachment.Prefill;
// Řadu dokladů, firmu i kategorii dokumentu přizpůsobte svému konkrétnímu řešení
mAttachment.SetFieldValueAsString('DocQueue_ID', 'O700000101');
mAttachment.SetFieldValueAsString('Firm_ID', 'F011000000');
mAttachment.SetFieldValueAsString('Category_ID', '5000000000');
mAttachment.SetFieldValueAsString('Description', 'Založeno spolu s uložením BO');
// Uložením ABO se uloží i nově přidaná příloha v jeho kolekci
ABO.Save;
end;
2. Nová příloha založená samostatně, ale připojená a uložená spolu s hlavním objektem
Druh skriptu: Knihovna, Název knihovny: PrilohyDefinovatelnychObjektu
procedure AddAttachment(ABO: TNxCustomBusinessObject);
var
mAttachments: TNxCustomBusinessMonikerCollection;
mAttachment: TNxCustomBusinessObject;
begin
// Dokument tentokrát vytváříme jako zcela samostatný business objekt
mAttachment := ABO.ObjectSpace.CreateObject(Class_Document);
try
mAttachment.New;
mAttachment.Prefill;
mAttachment.SetFieldValueAsString('DocQueue_ID', 'O700000101');
mAttachment.SetFieldValueAsString('Firm_ID', 'F011000000');
mAttachment.SetFieldValueAsString('Category_ID', '5000000000');
mAttachment.SetFieldValueAsString('Description', 'Založeno samostatně a připojeno jako BO');
// Teprve tady jej připojíme do kolekce příloh hlavního objektu
mAttachments := ABO.GetCollectionMonikerForFieldCode(ABO.GetFieldCode('AttachedDocuments'));
mAttachments.AddObject(mAttachment);
// Uložení ABO uloží i takto připojenou přílohu
ABO.Save;
finally
mAttachment.Free;
end;
end;
3. Příloha uložená samostatně, propojená dodatečně přes záznam relace
V tomto případě je potřeba znát číslo vazby (číslo relace) hlavního objektu - tedy hodnotu pole Identifikace propojení s přílohami z jeho definice. Nově k tomu slouží skriptovací funkce CFxDocuments.GetRelationType (vrací číslo relace podle CLSID třídy), případně QR funkce GetBO2DocumentRelation se stejným účelem pro použití v tiskových sestavách/QR výrazech - není tedy potřeba znát ani opisovat konkrétní číslo z definice ručně. Tato varianta se hodí zejména tehdy, když přílohu potřebujete připojit k objektu, který už dávno existuje a znovu jej ukládat nechcete/nemusíte:
Druh skriptu: Knihovna, Název knihovny: PrilohyDefinovatelnychObjektu
procedure AddAttachment(AObjectSpace: TNxCustomObjectSpace; ABOID: string; ABOCLSID: string);
var
mAttachment,
mRelation: TNxCustomBusinessObject;
mOID: string;
begin
// 1. Založíme a rovnou uložíme samostatný dokument
mAttachment := AObjectSpace.CreateObject(Class_Document);
try
mAttachment.New;
mAttachment.Prefill;
mAttachment.SetFieldValueAsString('DocQueue_ID', 'O700000101');
mAttachment.SetFieldValueAsString('Firm_ID', 'F011000000');
mAttachment.SetFieldValueAsString('Category_ID', '5000000000');
mAttachment.SetFieldValueAsString('Description', 'Založeno samostatně a připojeno pomocí relations');
mAttachment.Save;
mOID := mAttachment.OID;
finally
mAttachment.Free;
end;
// 2. Vytvoříme záznam relace, který dokument s hlavním objektem propojí
mRelation := AObjectSpace.CreateObject(Class_Relation);
try
mRelation.New;
mRelation.Prefill;
// Číslo vazby zjistíme podle CLSID hlavního objektu - nemusíme jej znát nazpaměť
mRelation.SetFieldValueAsInteger('Rel_Def', CFxDocuments.GetRelationType(ABOCLSID));
mRelation.SetFieldValueAsString('LeftSide_ID', ABOID);
mRelation.SetFieldValueAsString('RightSide_ID', mOID);
mRelation.Save;
finally
mRelation.Free;
end;
end;
Zavolání knihovny z háčku business objektu
Knihovna sama nic nespustí - proceduru AddAttachment je potřeba zavolat z nějakého skutečného háčku. Například pro automatické založení přílohy hned po uložení nového záznamu vaší definovatelné agendy (v příkladu business objekt Complaint, viz Příklad z praxe - definovatelná agenda Reklamace) postupujte takto:
-
Ve stejném nebo jiném balíčku skriptů přidejte další řádek funkcí Přidat s Druhem skriptu Business objekt. V poli Název knihovny resp. třídy objektu vyberte svůj objekt podle Zobrazovaného názvu z jeho definice. Pro příklad níže má interní název Complaint, registrovanou třídu DefBO_Complaint a skriptovací konstantu Class_DefBO_Complaint.
-
Na subzáložce Zdrojový kód v poli Metoda vyberte háček AfterSave_Hook - do editoru se vloží jeho kostra s parametrem Self (uložený business objekt).
-
Na začátek zdrojového kódu (před první procedure) přidejte odkaz na knihovnu podle konvence název_balíčku.název_knihovny:
uses 'abraDboPrilohy.PrilohyDefinovatelnychObjektu'; -
Použijte knihovní proceduru z varianty 3 se třemi parametry. V háčku se ukládá pouze dokument a jeho relace; hlavní objekt znovu neukládejte. Podmínka osNew in Self.State omezí vytvoření přílohy na první uložení záznamu. Konstantu třídy nahraďte konstantou svého business objektu:
procedure AfterSave_Hook(Self: TNxCustomBusinessObject); begin if osNew in Self.State then AddAttachment(Self.ObjectSpace, Self.OID, Class_DefBO_Complaint); end; -
Skript stejně jako výše zkompilujte (Alt+F9) a uložte, a ověřte, že je balíček nastaven na Stav Používat.
Pokud skript pro danou agendu/business objekt upravíte za běhu systému, projeví se změna až po znovunačtení skriptů do paměti - nejjednodušeji zaškrtnutím volby Znovu načíst skripty přímo při ukládání skriptu, nebo restartem klienta.
Pro přístup do API musí mít použitý uživatel povolené příslušné rozhraní, odpovídající licenci a potřebná práva.
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