Karta udalosti v nastaveniach dátovej štruktúry slúži na nastavenie akcií (udalostí), ktoré sa majú vykonať nad dokumentom v dátovej štruktúre, pri naplnení určitých podmienok.
Typy udalostí
Automatické udalosti
Automatické udalosti sa spúšťaju automaticky pomocou cron jobu v presne stanovený čas (momentálne to je okolo 04:00 AM). Ak máme pre dátovu štruktúru nastavenú automatickú udalosť, pri jej spustení sa pre všetky uložené dokumenty, ktoré nie sú uzamknuté vyhodnotí splnenie podmienok a v prípade že sú podmienky pre daný dokument splnené, vykoná sa udalosť nad daným dokumentom.
Pozor: Automatické udalosti sa vyhodnocojú a pri splnení podmienky aplikujú pre každý dokument. Ak chceme napr. poslať email ak je splnená nejaká podmienka a budeme to riešiť cez udalosť, pošle sa samostatný email pre každý dokument ktorý spĺňa podmienku, napr. v prípade 10 000 dokumentov, 10 000 emailov.
Automatické akcie sa neaplikujú na zamknuté alebo aktuálne editované (neuložené) dokumenty.
Manuálne udalosti
Manuálne udalosti sa vykonávajú po vykonaní akcie, ktorá je nastavená ako spúšťač. Momentálne máme k dispozícii 3 spúšťače udalostí:
- Vytvorenie záznamu
- Upravenie záznamu
- Zmazanie záznamu
Jedna udalosť môže mať aj viacero týchto spúšťačov naraz, ale takisto nemusí mať ani jeden, vtedy sa manuálna udalosť nevykoná. To môže byť výhodne v prípade že udalosť chceme dočasne deaktivovať, ale nechceme ju úplne odstrániť, aby sme ju potom nemuseli vyklikávať nanovo.
Vytvorenie: Udalosť s týmto spúšťačom sa vyhodnocuje po vytvorení dokumentu. Za vytvorenie sa však požaduje len počiatočné vytvorenie dokumentu, napr. po tranformácii alebo prostredníctvom integrácie. Ak však vytvárame nový dokument cez tlačidlo + v prehľade (vytváranie cez transformáciu typu NEW), za vytvorenie dokumentu sa považuje len jeho počiatočné vytvorenie, kde budeme mať vo väčšine prípadov predvolené, prípadne prázdne dáta. Ak by sme teda nastavili podmienku pre vykonanie udalosti že nejaké číslo v dokumente musí byť väčšie ako 10, vytvoríme dokument, prepíšeme manuálne hodnotu v dokumente a potom ho uložíme, spúšťač vytvorenie túto udalosť nespustí. Pri ukladaní sa už bude brať do úvahy spúšťač ‚Úprava‘. Pri transformácii na iný dokument cez typ TRANSFORM, budeme mať v dokumente prenesené dáta z dokumentu už pri vytváraní, takže v takom prípade by sa udalosť vykonala ak by mal daný stĺpec hodnotu väčšiu ako 10.
Úprava: S týmto typom spúštača sa budeme stretávať najčastejšie. Udalosť s týmto spúšťačom sa vyhodnocuje vždy pri uložení dokumentu. To znamená že pri uložení dokumentu sa vyhodnotia podmienky udalosti a ak sú splnené vykonajú sa akcie.
Zmazanie: Udalosť s týmto spúšťačom sa vyhodnocuje keď je dokument odstránený.
Systémové udalosti
Systémovými udalosťami vieme nastaviť spustenie akcie, v prípade že nastane „systémová udalosť“. Tieto udalosti sú zatiaľ k dispozícii 2, a to prijatá emailová správa a proces bankového účtu.
Prijatá emailová správa
Pomocou tejto udalosti vieme vykonať akcie po tom ako obdržíme email na prepojenú emailovú adresu. Po zvolení tejto udalosti je potrebné vybrať emailový účet. Na to aby sme mohli túto funkcionalitu využívať, je potrebné pridať účet k zoznamu emailových účtov, a nastaviť mu IMAP prepojenie, aby bolo možné číťať obrdžané emaily.
Akonáhle máme pridaný nejaký email s IMAP prepojením, môžeme nastaviť udalosť, ktorá sa vykoná pri prijatí novej emailovej správy.
Pri emailových správach vieme určit podmienky na základe obsahu emailu. Môžeme napr. určiť čo sa má stať v závislosti od premetu správy, odosielateľa prípadne či email obsahuje prílohy. Ak budú podmienky vyhodnotené ako splnené, prejde sa na vykonávanie akcii podobne ako pri iných typoch udalostí.
Využitie: Spracovanie faktúr po príchode na email; automatické vytváranie dátových štruktúr na základe obrdžaných emailov…
TODO – doplniť proces bankového účtu
Podmienky
V prípade že je udalosť spustená (buď automaticky alebo manuálne zvoleným spúšťačom), prejde k vyhodnocovaniu podmienok. Ak podmienky nie sú splnené, akcie v udalosti sa nevykonajú.
Pri definovaní podmienok, máme na výber 3 možnosti: „Všetky podmienky musia byť splnené“, „Aspoň jedna podmienka musí byť splnená“, alebo „Spúštať vždy bez podmienok“. Z názvu by už malo byť jasné aký je medzi nimi rozdiel. Po výbere spôsobu vyhodnocovania môžeme pridať viaceré podmienky. Na výber máme atribúty z dokumentov a každý typ atribútu má na výber operátory, ktoré môžeme použiť pri vyhodnocovaní. Pokiaľ vyberieme atribút, ktorý predstavuje tabuľku, môžeme definovať ďalšie podmienky pre záznamy v tabuľke, a podmienka pre tabuľku môže vyhodnocovať koľko takýchto záznamov spĺňajúcich požadované podmienky by sa v tabuľke malo nachádzať.
V prípade že sú zadefinované podmienky splnené, prejde sa na ďalšiu časť, ktorou je vykonanie akcie. Akcia môže predstavovať buď použitie skriptu, alebo vykonanie nastavených akcií.
Akcie
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íkazinput.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: '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,
}
};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.