Akcie

Prepis videa

Takže čo sa týka akcií, na úvod akcie je možné teda preťaziť nejakým takýmto spôsobom a je možné nastaviť rôzne typy akcie. Konkrétne je možné nastaviť odoslanie notifikačného e-mailu s tým, že vyberiem si tu nejakú šablónu, proste klasika nastavenia pri odosielaní e-mailu. Ďalej tu máme akciu dátovú.

Táto dátová akcia mi jednoducho zapíše do daného atribútu nejakú buď fixnú hodnotu alebo preniesie hodnotu atribútu v závisí. Ďalší typ akcie je transformačný, to znamená spustenie konkrétnej transformácie ktorú mám zadefinovanú v rámci týchto transformácií. Ďalej tu je akcia integračná, to môžem ukázať napríklad na tom QR kóde.

To znamená, že mám tu na vyber z nejakých integrácií, ktoré máme implementované v moduláriu a tá integrácia sa vlastne spustí, spustí sa nejaká konkrétna jej metóda s nastaveným mapovaním do budúcna. By sa teda mapovanie malo presnúť do udalosti. Vlastne aj predtým tie transformácie, čo som ukazoval, tak celé toto nastavenie transformácií by malo ísť do udalosti.

Aj celé tlačidla by mali ísť do udalosti. Takže tam sa to celkovo zjednoduší a hlavne dá na jedno miesto aby sa toto nemuselo vyklikávať takto na dvakrát. Ešte je tu taká možnosť odstraniť diakritiku, počkať na odpoveď.

To sú asi také, že chápeme, čo je tým myslené. Ďalej máme typ akcie Script. To sú najčastejšie akcie, 90 % akcií bude typu Script, kde teda v JavaScripte sa dá napísať doslova čokoľvek.

No a potom sú tu nejaké ďalšie akcie typu Query. Pravdu povediať, netuším úplne, čo to robí, ani som to nikdy nevidel použité. Takisto uprava, ešte som nevidel použité.

Takisto získanie schémy. To vyzerá ako, že sa proste získa nejaká data, schéma datovej štruktúry. Neviem, čo sa s tým ďalej deje.

A takisto substitúcia. Tiež, pravdu povediať, netuším, čo to robí. V tomto prípade udalosti, ale určite odporúčam, okrem zliadnutia týchto videí, si prejsť poriadne aj dokumentáciu, ktorú máme spísanú k udalostiam.

Dozviete sa tu vlastne aj prehľad dostupných príkazov, ktoré tu teda máme a podobne. Takže určite odporúčam tu na prečítací prejsť si poriadne aj dokumentáciu. A v samostatných ďalších kapitolách si rozoberieme konkrétne príklady, konkrétnych udalostí, ktoré tu naši local developers doteraz urobili.

Pretože nemá zmysel vymýšľať koleso dookola, ale radšej sa inšpirujeme tým, čo už pred nami niekto urobil.

Pri výbere akcií máme k dispozícií viacero typov. Jedna udalosť môže obsahovať aj viacero akcií, ktoré sa potom vykonajú postupne. Akcie pracujú vždy len s aktuálnym dokumentom (nevieme cez ne napr. zmeniť dáta v inom dokumente, to ale môžeme dosiahnuť pomocou skriptov).

Typy akcií

Pri výbere akcie, si môžeme zvoliť z nasledovných typov:

• Notifikačný (email)
• Dátový
• Transformačný
• Integračný
• Skript
• Query
• Úprava
• Získanie schémy
• Substitúcia
  

Notifikačný (email)

Tento typ akcie slúži na odosielanie emailovej notifikácie, v prípade že sú splnené podmienky.

Pozor: akcie sa vykonajú vždy pri splnení podmienok. Ak budeme mať teda nastavenú podmienku typu odošli email, ak je cena vo faktúre väčšia ako 10 000, podmienka sa vyhodnotí ako pravdivá po každom uložení dokumentu, aj keď aktívne nebudeme meniť cenu. Keby teda niekto 10x klikol upraviť a potom uložiť dokument, bude to mať za následok odoslanie 10 emailov, čo nie je vždy želané správanie. Ak chceme odoslať len jeden email, pri prvom splnení podmienky, môžeme si pridať do dokumentu pomocnú boolean premennú, napr. odoslaná notifikácia, ktorá bude mať prednastavenú hodnotu Nie, a podmienka v udalosti bude že zároveň musí mať tento atribút hodnotu Nie, v prípade že odošleme email, zároveň nastavíme hodnotu tejto premennej na Áno, čím zabránime vyššie spomenutému problému.

Ukážku nastavenia notifikačnej akcie môžeme vidieť na nasledujúcom obrázku. Vpravo hore máme na výber premenné záznamu, premenné firmy a premenné používateľa. Po kliknutí a výbere niektorej z týchto premenných, sa premenná skopíruje, takže ju môžeme vložiť do predmetu alebo do tela emailu. Funguje to v podstate rovnako ako odosielanie emailov podľa emailových šablón. Tieto premenné sa pri odosielanie emailu nahradia skutočnými hodnotami z dokumentu, firmy alebo používateľa.

V automatických udalostiach nie sú k dispozícii premenné používateľa, namiesto toho sa tam nahradia prázdnym textom. Pri manuálnych udalostiach sa za premenné používateľa doplnia údaje aktuálne prihláseného používateľa, ktorý udalosť spustil vykonaním spúšťacej akcie (vytvorenie, úprava alebo vymazanie záznamu).

Emailová šablóna: ak máme pre dátovú štruktúru vytvorené emailové šablóny, môžeme nejakú z nich vybrať, vďaka čomu nám predvyplní predmet a telo emailu podľa emailovej šablóny. Telo aj predmet môžeme potom ďalej upravovať.

Vizuál prílohy: spolu s emailom môžeme odoslať aj prílohy – vizuál dokumentu v pdf formáte. V prípade že vizuál prílohy nevyberieme, odošle sa email bez príloh. Ak vyberieme nejaký vizuál, tak bude súčasťou prílohy.

Príjemci: v tejto časti môžeme vyplniť statických príjemcov – email sa odošle na tieto emailove adresy vždy keď sa splnia podmienky a bude sa posielať notifikácia. Je môžné zadať aj viacero emailových adries.

Príjemci – Atribúty: sem môžeme vybrať dynamických príjemcov z atribútov. Aby sme tu mali atribút na výber, tak daný atribút musí byť typu ‚Krátky text‘ a musí mať typ E-mail. Ak tu vyberieme nejakého príjemcu z atribútu, tak sa email odošle na danú adresu z dokumentu, ktorá sa nachádza v tomto atribúte. Je možné taktiež vybrať aj viacero príjemcov, ak je atribút typu email v opakovateľnej skupine.

Dátový

Dátový typ akcie zmení hodnoty v aktuálnom dokumente pri splnení podmienok. Je potrebné zvoliť atribút, a novú hodnotu ktorou sa nahradí pôvodná hodnota.

Transformačný

Po splnení podmienok sa vykoná zvolená transformácia. Tento typ vie byť užitočný keď napr. potrebujeme automaticky vytvoriť iný typ dokumentu s prenesenými dátami pri splnení podmienok.

Integračný

Vykoná sa zvolená integrácia. Zatiaľ máme definované integrácie na systémy OMEGA (účtovnícky systém), TRIMEL a DCOM (integrácie pre staré mesto s vjazdom a parkovaním).

Použitie skriptov

Druhá varianta k akciám je použitie skriptov. Skripty môžu pracovať aj s inými dokumentami, pomocou vopred definovaných akcií ktoré podporujú. Ich použitie je však náročnejšie, keďže si vyžadujú aspoň základnú znalosť javascriptu, a akcie čo sa majú stať je potrebné písať pomocou kódu. Zároveň však umožňujú väčšiu funkcionalitu ako je dopytovanie záznamov, upravovanie záznamov, vytváranie nových záznamov alebo hromadné úpravy.

Získanie dát zo vstupného dokumentu

Vstupný dokument pre udalosť môžeme v skriptoch získať pomocou príkazu input.inputDocument . Ak by sme teda chceli vstupný dokument uložiť do premennej aby sme s ním mohli ďalej pracovať, mohli by sme použiť napr. nasledujúci príkaz. Aby sme mali prístup k dátam, ktoré sú uložené v dokumente, musíme použiť data atribút v získanom objekte.

Logovanie hodnôt vo vnútri skriptu

Pokiaľ chceme počas vykonávania skriptu v udalosti zistiť aktuálne hodnoty (prevažne na účely debugovania skriptov), môžeme použiť log() funkciu. Skripty bežia v izolovanom prostredí, console.log() preto fungovať nebude. Výsledok logovania je potom k dispozícii v logoch/konzole (pri lokálnom spustení) kde beží backend server. Pri písaní skriptov je teda najlepšie otestovať fungovanie lokálne (prípadne aj na deve, tu bude ale obtiažnejšie získať logy z vykonávania), a keď budeme mať istotu že skript beží správne, použiť ho na produkčnom prostredí.

Všeobecná štruktúra príkazu

return {
  command: 'nazovPrikazu', // povinné (napr. 'query', 'updateOne' atď.)
  payload: {
    // vstupné dáta špecifické pre konkrétny príkaz
  },
  // voliteľné polia
  output: { /* objekty, ktoré chcete odovzdať do next skriptu cez input.previousScriptOutput */ },
  recalculateEquations: true,   // (iba pri updateOne / updateMany) či po uložení recalculovať rovnice
  shouldAwait: true            // (voliteľné, niekedy využiteľné pri sekvenčnom čakaní na dokončenie)
};

command: String, určuje typ príkazu (napr. „query“, „updateOne“, atď.).

payload: Objekt, v ktorom sú parametre pre daný príkaz. Obsah sa líši podľa typu príkazu.

output (voliteľné): Objekt, ktorý sa uloží do input.previousScriptOutput. Umožňuje predávať ľubovoľné dáta do ďalšej časti skriptu.

recalculateEquations (voliteľné, pri príkazoch typu updateOne / updateMany): Logická hodnota (true/false). Ak je true, po úspešnom uložení dokumentu sa spustí prepočet rovníc definovaných v danom type dokumentu.

shouldAwait (voliteľné): Logická hodnota (true/false). Vyjadruje či sa ma čakať na vykonanie udalosti, ak je to potrebné. Napr. ak chceme vytvárať po uložení veľa dokumentov, ale nechceme čakať na ich vytvorenie, môžeme nastaviť na false aby operácia dobehla na pozadí.

Prístup k výsledkom predchádzajúceho príkazu

previousCommandOutput – obsahuje návratovú hodnotu z predchádzajúceho príkazu (napr. pole nájdených dokumentov pri query, upravený dokument pri updateOne, atď.).

Príklad:

const documents = previousCommandOutput; // ak predtým bol query príkaz

input.previousScriptOutput – obsahuje objekt/objekty, ktoré sme explicitne vrátili v output kľúči z predchádzajúceho príkazu.

Príklad:

const { nejakaPremenna } = input.previousScriptOutput;

Poznámka: Ak potrebujeme z previousCommandOutput získať len prvý dokument, môžeme použiť napr.

const [dokument] = previousCommandOutput; 

Prehľad dostupných príkazov

1. query

Vyhľadá dokumenty podľa zadaného filtra.

Štruktúra:

return {
  command: "query",
  payload: {
    // sem patrí filter podľa ktorého chceme dokumenty vyhľadávať
    // napr. {
    //   _id: { $in: ["id1", "id2", ...] },
    //   data.nazovPola: 'hodnota',
    // },
    withLinkedDocuments: true // voliteľné, či má vrátiť aj prepojené dokumenty
  },
  output: {
    // sem môžeme vložiť akékoľvek vlastné dáta,
    // ktoré chceme odovzdať do input.previousScriptOutput
  }
};

Výstup (previousCommandOutput): Pole dokumentov, ktoré vyhovujú filtru.

Príklad:

return {
  command: 'query',
  payload: {
    _id: { $in: idArray },
    withLinkedDocuments: true
  },
  output: {
    // posielam si sem napr. pôvodný dokument, aby som ho mal v ďalšom kroku
    inputDocument: input.inputDocument,
  }
};

---

2. select

Tento príkaz je užitočný, keď potrebujete prerušiť tok skriptov napr. niečím, čo explicitne nič nemení a nič nevyhľadáva. Prakticky nič nevykonáva, iba vám umožní vrátiť údaje do output, ktoré môžete ďalej využiť.

Štruktúra:

return {
  command: "select",
  output: {
    // ľubovoľné dáta
  },
};

Výstup (previousCommandOutput): Prázdny objekt {}, ak nič nevrátite.

Ak chcete odovzdať dáta ďalšiemu skriptu, vložte ich do output, a následne ich čítate cez input.previousScriptOutput.

---

3. getSchema

Získa schému (formulár/metadáta) pre daný documentTypeId. Ak documentTypeId neuvediete v payload, použije sa documentTypeId z aktuálnej udalosti.

Štruktúra:

return {
  command: "getSchema",
  payload: {
    documentTypeId: "idTypuDokumentu" // nepovinné
  }
};

Výstup (previousCommandOutput): Schéma daného typu dokumentu.

Príklad:

return {
  command: 'getSchema',
  payload: {
    documentTypeId: '642c82325bdadfdb9f7b08d2'
  }
}

---

4. createOne

Vytvorí jeden nový dokument zadaného typu (documentTypeId).

Štruktúra:

return {
  command: "createOne",
  payload: {
    documentTypeId: "idTypuDokumentu",
    data: {
      // polia data, ktoré chceme vytvoriť
      nazov: "Nový dokument",
      cisloObjednavky: 1234
    }
  },
  output: {
    // Ak chcete niečo odovzdať do next skriptu cez input.previousScriptOutput
  }
};

Výstup (previousCommandOutput): Novo vytvorený dokument (objekt).

Príklad:

return {
  command: 'createOne',
  payload: {
    documentTypeId: '642c82325bdadfdb9f7b08d2',
    data: {
      nazov: 'Automaticky vytvorený dokument',
      hodnota: 555
    }
  },
  output: {
    docCreated: true,
  }
}

---

5. createMany

Slúži na hromadné vytvorenie viacerých nových dokumentov toho istého typu.

Štruktúra:

return {
  command: "createMany",
  payload: {
    documentTypeId: "idTypuDokumentu",
    data: [
      { nazov: "Dokument 1", hodnota: 111 },
      { nazov: "Dokument 2", hodnota: 222 }
      // ...
    ]
  },
  output: {
    // akékoľvek dáta pre ďalší skript
  }
};

Výstup (previousCommandOutput): Pole vytvorených dokumentov (každý objekt predstavuje jeden dokument).

---

6. updateOne

Upraví jeden existujúci dokument. Filter v payload.filter by mal v ideálnom prípade vrátiť len jeden dokument. Ak vráti 0 alebo viac, skript skončí chybou.

Štruktúra:

return {
  command: "updateOne",
  payload: {
    filter: {
      _id: "idDokumentuKtoryChcemUpravit"
    },
    update: {
      // pole, ktoré majú byť v data zmenené, prípadne špeciálne updatovacie operátory
      "data.stav": "vybavené",
      "data.poznámka": "Objednávka bola odoslaná"
    }
  },
  recalculateEquations: true, // voliteľné - ak chceme prepočet rovníc
  output: {
    // dáta, ktoré chceme ďalej posunúť
  }
};

Výstup (previousCommandOutput): Objekt so zmeneným dokumentom (ak bol úspešne nájdený a upravený). Ak filter nenašiel dokument, vráti null.

Ak recalculateEquations: true, po uložení skript ešte vyvolá prepočet rovníc definovaných v danom type dokumentu.

Príklad:

const objednavka = [previousCommandOutput]; // predpokladajme, že predchádzajúci query príkaz vrátil práve 1 dokument
return {
  command: 'updateOne',
  payload: {
    filter: { _id: objednavka._id },
    update: {
      'data.stav': 'vybavená',
      'data.datumUkoncenia': new Date().toISOString()
    }
  },
  recalculateEquations: true
};

---

7. updateMany

Podobné ako updateOne, ale umožňuje vykonať viac aktualizácií za sebou. V payload je pole objektov, kde každý objekt obsahuje filter a update. Každá položka sa spracuje samostatne.

Štruktúra:

return {
  command: "updateMany",
  payload: [
    {
      filter: { _id: "idDok1" },
      update: {
        "data.stav": "vybavené"
      }
    },
    {
      filter: { _id: "idDok2" },
      update: {
        "data.poznámka": "Poznámka k dokumentu 2"
      }
    }
    // ...
  ],
  recalculateEquations: false, // defaultne false
  output: {
    // ...
  }
};

Výstup (previousCommandOutput): Pole aktualizovaných dokumentov.

Ak filter pri niektorej položke v poli vráti 0 alebo viac ako 1 dokument, vyvolá sa chyba (rovnako ako pri updateOne).

Pri recalculateEquations: true sa rovnice prepočítajú pre všetky ovplyvnené dokumenty.

---

8. uploadAttachments

Slúži na nahrávanie príloh k vybranému dokumentu. Prílohy sú pred nahratím automaticky komprimované do ZIP archívu a následne nahraté na S3 (resp. do úložiska).

Štruktúra:

return {
  command: "uploadAttachments",
  payload: {
    documentId: "idDokumentu",
    documentTypeId: "idTypuDokumentu",
    documentAttachmentsField: "nazovPolaVData", // ak chceme rovno zapísať attachments do data
    attachments: [
      {
        filename: "subor1.pdf",
        contentType: "application/pdf",
        content: <obsah_suboru_v_ArrayBuffer_alebo_Buffer>
      },
      {
        filename: "obrazok.png",
        contentType: "image/png",
        content: <obsah_suboru>
      }
      // ...
    ]
  }
};

documentAttachmentsField (voliteľné): Ak uvediete názov poľa v data, prílohy sa hneď po nahratí zapíšu do daného poľa v dokumente (pole bude obsahovať zoznam príloh so name a id).

Výstup (previousCommandOutput): { attachments: […] } – zoznam príloh (každá príloha s názvom a id).

Príklad:

return {
  command: "uploadAttachments",
  payload: {
    documentId: "642c82325bdadfdb9f7b08d2",
    documentTypeId: "642c82325bdadfdb9f7b08d2",
    documentAttachmentsField: "zoznamPriloh",
    attachments: [
      {
        filename: "doklad.pdf",
        contentType: "application/pdf",
        content: someBinaryData // napr. ArrayBuffer z integrácie
      }
    ]
  }
};

---

9. ocrImport

Špeciálny príkaz, ktorý spracuje priložené súbory (PDF/obrázky) cez OCR (Optical Character Recognition), vytvorí nové dokumenty požadovaného typu a pokúsi sa extrahovať dáta podľa zadaného promptu. Prílohy sa tiež nahrávajú k vytvoreným dokumentom.

Štruktúra:

return {
  command: "ocrImport",
  payload: {
    documentTypeId: "idTypuDokumentu",     files: input.inputData.document.attachments.map(attachment => {    return {       filename: attachment.filename,       contentType: attachment.contentType,       content: attachment.content.data    }    }),       prompt: "Sem môžem zadať inštrukcie, ak AI podporuje extrakciu údajov",
    extractTextFromPdf: true,             // či sa má extrahovať text z pdf
    outputFields: ["data.preberam_toto"], // polia, do ktorých sa snaží OCR naplniť extrahované dáta
    editedByUserId: "642c82325bdadfdb9f7b08d2", // userId, ktoré sa prepisuje ako posledná úprava
    documentAttachmentsField: "polePriloh" // kam uložiť prílohy v novo vytvorených dokumentoch
  }
};

Výstup (previousCommandOutput): Pole novovytvorených dokumentov, ku ktorým sa prílohy nahrali.

Tento príkaz vytvára tzv. “OCR import záznam” a následne pre každý súbor generuje nové dokumenty. Ak OCR spracovanie skončí chybou, skript ju vyhodí. 

Používa sa v kombinácii s napojením na email a systémovú udalosť, napr. automatické vytvorenie pri prijatom emaili.