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

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ě:

1. Vytvořte dokument v agendě Dokumenty - POST .../Documents s obsahem souboru zakódovaným do Base64 v poli Contents[].DataAsBytes.

2. 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"].

3. 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áží.

Založení knihovny se skriptem

1. Otevřete agendu Balíčky skriptů (najdete ji přes globální hledání, nebo v nabídce Nástroje přizpůsobení).

2. Funkcí Nový založte nový balíček skriptů. Do pole Název zadejte jedinečný technický název bez diakritiky, mezer a speciálních znaků (povolena jsou jen písmena A-Z a číslice) - např. abra.cz.dbo.prilohy. 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ý.

3. 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.

4. V přidaném řádku nastavte pole Druh skriptu na Knihovna.

5. Do pole Název knihovny resp. třídy objektu zadejte název knihovny, opět bez diakritiky a mezer - např. PrilohyDefinovatelnychObjektu.

6. 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.

7. 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.

8. 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ášť.

9. 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ů.

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:

1. Ve stejném nebo jiném balíčku skriptů přidejte další řádek skriptu funkcí Přidat, tentokrát s Druhem skriptu Business objekt a v poli Název knihovny resp. třídy objektu vyberte svou třídu (Complaint).

2. 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).

3. 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
   'abra.cz.dbo.prilohy.PrilohyDefinovatelnychObjektu';

4. Do těla háčku doplňte volání knihovní procedury:

   procedure AfterSave_Hook(Self: TNxCustomBusinessObject);
   begin
     AddAttachment(Self);
   end;

5. Skript stejně jako výše zkompilujte (Alt+F9) a uložte, a ověřte, že je balíček nastaven na Stav Používat.