Zpracování e-mailů
Zpracování e-mailů je místo, kde administrátor spravuje připojení k e-mailovým schránkám (IMAP, POP3 a Microsoft Graph) a kde vidí evidenci všech e-mailů, ze kterých TAS zakládal případy. Připojení obsahuje jen to, kde schránka je a jak se do ní přihlásit. Co se s poštou stane, tedy z jaké šablony vznikne případ a které proměnné se vyplní, nastavuje cron Email processing v Cronech. Stejná připojení používá i chytrá událost Mail a funkce sys.mail.* v Servisní konzoli. Stránku vidí uživatel s rolí Administrátor, otevřete ji v menu Administrace kartou Zpracování e-mailů v kategorii Integrace a správa dat.
Zpracování e-mailů nahrazuje crony Create Processes from MS Graph mails (obě varianty) a Check unprocessed MS Graph mails. Jak převést jejich nastavení, popisuje článek MS Graph (e-mail), část Od verze 5.21.
Přehled připojení
| Č. | Prvek | K čemu slouží |
|---|---|---|
| 1 | Zavřít | Vrátí vás do menu Administrace. |
| 2 | Připojení | Záložka se seznamem připojení ke schránkám. |
| 3 | Evidence e-mailů | Záložka se záznamy o zpracovaných e-mailech, viz níže. |
| 4 | Vytvořit připojení | Otevře okno pro nové připojení. |
| 5 | Filtr | Uložení a zrušení filtru a panel s podrobným filtrem nad tabulkou. Vedle je tlačítko pro zobrazení tabulky přes celou obrazovku. |
| 6 | Název | Jedinečný název připojení. Podle názvu se na připojení odkazují crony, chytré události a funkce sys.mail.*. Tabulka je ve výchozím stavu seřazená podle názvu. |
| 7 | Typ | Protokol připojení: msgraph (Microsoft 365 přes Microsoft Graph), imap, nebo pop3. |
| 8 | Popis | Volný text pro administrátory. |
| 9 | Aktivní | Zda se připojení smí použít. Neaktivní připojení cron odmítne s chybou. |
| 10 | Vložil | Kdo připojení založil. |
| 11 | Vloženo | Kdy bylo připojení založeno. |
| 12 | Akce řádku | Nabídka Otestovat připojení, Zjistit složky, Upravit a Smazat, viz níže. |
| 13 | Export | Stáhne tabulku do souboru. Vedle jsou volby zobrazení a výběru sloupců. |
Dvojklikem na řádek otevřete připojení k úpravě.
Akce řádku
| Akce | K čemu slouží |
|---|---|
| Otestovat připojení | TAS se přihlásí do schránky a zkusí ji přečíst. Výsledek ukáže upozornění Připojení „…“ funguje, nebo Připojení „…“ selhalo i s chybou, kterou vrátil poštovní server. Test nic nemění, nečte ani nepřesouvá e-maily. |
| Zjistit složky | Zobrazí strom složek schránky typu msgraph, viz níže. |
| Upravit | Otevře okno připojení s uloženými hodnotami. Typ připojení už změnit nelze. |
| Smazat | Po potvrzení připojení smaže. Crony a chytré události, které ho používají, pak skončí chybou. Záznamy v evidenci e-mailů zůstanou, jen bez názvu připojení. |
Vytvořit a upravit připojení
Okno má dvě části: Základní informace a Parametry. Parametry se mění podle zvoleného typu. U každého parametru je otazník s nápovědou, technický název parametru a jeho výchozí hodnota, kterou můžete klepnutím doplnit. Okno se nezavře klepnutím mimo něj, jen tlačítkem Zavřít.
| Pole | K čemu slouží |
|---|---|
| Název | Povinné, musí být jedinečné. Připojení, které už používá cron nebo chytrá událost, nejde přejmenovat. TAS uložení odmítne a vypíše, které crony a úkoly ho používají. Nejdřív v nich vyberte nový název, pak připojení přejmenujte. |
| Typ | Povinné, nabídne se msgraph, imap a pop3. Po uložení se už nedá změnit, pro jiný protokol založte nové připojení. |
| Popis | Nepovinný text, zobrazí se v tabulce. |
Pole Password a Client Secret nejsou textová pole, ale výběr tajných klíčů z Trezoru. Připojení si uloží jen odkaz
{{vault:název}}, samotnou hodnotu ne. Tajný klíč proto nejdřív založte v Trezoru. Ikona oka vedle pole otevře vybraný klíč v Trezoru na nové kartě. Pokud byl klíč z Trezoru smazán, pole to ukáže a připojení nepůjde uložit.Tlačítko Uložit zkontroluje povinné parametry, jejich formát a existenci tajného klíče v Trezoru. Prázdné nepovinné parametry dostanou při uložení výchozí hodnotu.
IMAP
| Parametr | K čemu slouží |
|---|---|
host | Povinné. Adresa IMAP serveru, například imap.company.com. |
port | Port serveru. Výchozí 993 (šifrované spojení), 143 pro nešifrované spojení nebo STARTTLS. |
secure | Šifrované spojení (TLS), ve výchozím stavu zapnuté. Vypněte jen pro port 143. |
user | Povinné. Účet, kterým se TAS přihlašuje. |
password | Povinné. Heslo účtu jako tajný klíč z Trezoru. |
emailAddress | Adresa schránky pro logy a evidenci e-mailů. Když zůstane prázdná, použije se user. |
rejectUnauthorized | Odmítne server s neplatným TLS certifikátem, ve výchozím stavu zapnuté. Vypněte jen u známého serveru s certifikátem podepsaným sám sebou. |
POP3
| Parametr | K čemu slouží |
|---|---|
host | Povinné. Adresa POP3 serveru, například pop.company.com. |
port | Port serveru. Výchozí 995 (šifrované spojení), 110 pro nešifrované. |
secure | Šifrované spojení (TLS), ve výchozím stavu zapnuté. Vypněte jen pro port 110. |
user | Povinné. Účet, kterým se TAS přihlašuje. |
password | Povinné. Heslo účtu jako tajný klíč z Trezoru. |
emailAddress | Adresa schránky pro logy a evidenci e-mailů. Když zůstane prázdná, použije se user. |
deleteAfterProcessing | Smaže e-mail ze schránky, jakmile z něj vznikl případ. Ve výchozím stavu vypnuté. |
POP3 neumí e-mail přesunout ani si zapamatovat, že byl přečtený. Zpracovaný e-mail jde jen smazat, nebo nechat ve schránce. Při vypnutém
deleteAfterProcessing cron při každém běhu čte znovu stejné e-maily. Druhý případ z nich díky evidenci e-mailů nevznikne, ale cron čte jen tolik e-mailů, kolik dovolí jeho Limit, takže se k novějším nemusí dostat. Jakmile ověříte, že zpracování funguje, mazání zapněte.Microsoft Graph
| Parametr | K čemu slouží |
|---|---|
emailAddress | Povinné. Schránka v Microsoft 365, ze které TAS čte, například support@company.com. |
authType | Způsob přihlášení. secret (výchozí) použije Client secret registrace aplikace v Microsoft Entra ID. managedIdentity použije spravovanou identitu Azure, takže v TAS není uložený žádný secret. Funguje jen tehdy, když TAS běží v Azure. |
tenantId | ID tenantu (adresáře) v Microsoft Entra ID. Povinné u secret. |
clientId | ID aplikace (Client ID) z registrace aplikace. Povinné u secret. U managedIdentity sem patří Client ID spravované identity přiřazené uživatelem, prázdné pole znamená identitu přiřazenou systémem. |
clientSecret | Client secret registrace aplikace jako tajný klíč z Trezoru. Povinné u secret. |
scope | Rozsahy OAuth. Prázdné znamená https://graph.microsoft.com/.default, tedy všechna aplikační oprávnění, která správce tenantu aplikaci schválil. |
Registrace aplikace v Entra ID potřebuje aplikační oprávnění ke čtení a zápisu pošty cílové schránky (cron e-maily čte, označuje jako přečtené a přesouvá), schválené správcem tenantu.
Zjistit složky
Okno ukáže adresu schránky a strom jejích složek. Po klepnutí na složku se dole zobrazí její název a ID, které tlačítkem vpravo zkopírujete. ID složky potřebujete do vstupní a výstupní složky v cronu Email processing. V cronu ale nemusíte ID kopírovat: pole složek tam mají vlastní tlačítko se stejným stromem. U IMAP zadáváte místo ID název složky, například INBOX nebo INBOX/Processed.
Smazání připojení
Tlačítko Smazat připojení odstraní, tlačítko Ne okno zavře beze změny. Než připojení smažete, odeberte ho z cronů a chytrých událostí, jinak skončí chybou.
Evidence e-mailů
Na záložce Evidence e-mailů je jeden záznam pro každý e-mail, který cron Email processing při zakládání případů načetl. E-mail se pozná podle připojení a Message-ID, takže ze stejného e-mailu nevznikne druhý případ, ani když ve vstupní složce zůstane.
| Č. | Prvek | K čemu slouží |
|---|---|---|
| 1 | Vybráno | Počet zaškrtnutých řádků. |
| 2 | Změnit status | Otevře okno pro hromadnou změnu stavu zaškrtnutých řádků. Aktivní je, jen když máte vybraný aspoň jeden řádek. Najednou lze změnit nejvýše 1000 záznamů. |
| 3 | Výběr řádků | Zaškrtávátko v záhlaví vybere všechny řádky, zaškrtávátka v řádcích jednotlivé e-maily. |
| 4 | Status | Stav zpracování e-mailu, viz tabulka níže. Ve filtru můžete vybrat jeden ze stavů. |
| 5 | Připojení | Připojení, přes které cron e-mail načetl. U smazaného připojení je prázdné. |
| 6 | Schránka | Adresa schránky. |
| 7 | Předmět | Předmět e-mailu. |
| 8 | Pokusy | Kolikrát zpracování e-mailu selhalo. |
| 9 | Poslední chyba | Chyba posledního neúspěšného pokusu. |
| 10 | Případ | Číslo případu, který z e-mailu vznikl. Klepnutím případ otevřete. |
| 11 | ID zprávy | Message-ID e-mailu z poštovního serveru. |
| 12 | Datum zpracování | Datum a čas poslední změny záznamu. Tabulka je ve výchozím stavu seřazená od nejnovějšího. |
| 13 | Akce řádku | Nabídka Změnit status a, pokud z e-mailu vznikl případ, Otevřít případ. |
Stavy e-mailu
| Status | Co znamená |
|---|---|
| Čeká na zpracování | Cron e-mail načetl a začal ho zpracovávat. Stav zůstane, pokud běh cronu spadl uprostřed, a cron e-mail zpracuje při dalším běhu. |
| Zpracováno | Případ vznikl. Záznam se ukládá společně s případem, takže stav Zpracováno znamená, že případ existuje. Pokud e-mail zůstal ve vstupní složce, cron ho při dalším běhu jen označí jako přečtený a přesune do výstupní složky. |
| Chyba | Zpracování selhalo a případ nevznikl. Cron to zkusí znovu při dalším běhu a zvýší počet pokusů. |
| Ukončeno po pokusech | Zpracování selhalo pětkrát. Cron e-mail dál přeskakuje a při každém běhu zapíše chybu do logu. E-mail zůstává ve vstupní složce schránky a čeká, až příčinu opravíte. |
Záznamy ve stavu Zpracováno maže cron CleanupCron ve výchozím nastavení po 365 dnech. Záznamy v ostatních stavech nemaže, protože jejich e-mail je stále ve vstupní složce. Ukončené e-maily hlásí i stránka Stav systému: varování, když je nějaký e-mail Ukončeno po pokusech, a kritický stav, když e-mail čeká nebo je v chybě déle než 8 hodin.
Změna stavu
Stav jednoho e-mailu změníte z nabídky řádku, více e-mailů tlačítkem Změnit status nad tabulkou. Otevřít případ z nabídky řádku otevře případ, který z e-mailu vznikl.
| Pole | K čemu slouží |
|---|---|
| Předmět / Vybráno | U jednoho e-mailu jeho předmět, u hromadné změny počet vybraných e-mailů. |
| Status | Nový stav, ve výchozím stavu Čeká na zpracování. Lze zvolit kterýkoli ze čtyř stavů. |
| Upozornění | Počítadlo pokusů se při každé změně vynuluje. Když e-mail už případ má a vybraný stav není Zpracováno, okno upozorní, že další zpracování založí druhý případ, pokud e-mail nikdy neopustil vstupní složku. |
| Změnit status | Uloží změnu. Změna se zapíše do Logů i se jménem administrátora. |
| Zavřít | Zavře okno bez změny. |
Co který stav udělá:
- Čeká na zpracování vrátí e-mail do dalšího běhu cronu, pokud je stále ve vstupní složce. Použijte ho po opravě příčiny u e-mailů ve stavu Chyba nebo Ukončeno po pokusech.
- Zpracováno zastaví zakládání případu. Cron e-mail při dalším běhu jen označí jako přečtený a přesune do výstupní složky.
- Ukončeno po pokusech nechá e-mail ve vstupní složce a cron ho přeskakuje.
Cron Email processing
Případy z e-mailů zakládá cron Email processing (technický název EmailProcessingCron), který nastavíte v Administrace → Crony. Ve výchozím nastavení běží každých 5 minut mezi 3:00 a 19:59 a je neaktivní, zapnete ho sami. Na nové instalaci je cron v seznamu připravený. Na instalaci, která přešla z dřívější verze, ho přidáte tlačítkem Přidat cron a volbou EmailProcessingCron (PLATFORM). Cronů Email processing můžete mít víc, například s různým časováním.
Parametry cronu mají dvě části: výchozí nastavení společné pro všechny schránky a seznam schránek (úloh). Každá úloha čte jedno připojení.
| Parametr | K čemu slouží |
|---|---|
Limit (limit) | Kolik e-mailů cron přečte z každé schránky za jeden běh, výchozí 100. Zbytek zpracuje příští běh. |
Attachments (defaults.attachments) | upload (výchozí) nahraje přílohy e-mailu k případu jako dokumenty, skip přílohy vynechá. Obrázky vložené do těla e-mailu se jako přílohy nenahrávají nikdy. Když se některou přílohu nepodaří nahrát, zpracování e-mailu selže a cron ho zkusí znovu. Případ bez dokumentů nevznikne. |
Ignored Attachment Types (defaults.ignoredAttachmentTypes) | Přípony souborů, které se nenahrávají, například png a gif pro loga v podpisech. Prázdné znamená, že se nahrají všechny přílohy. |
Attach Email As Pdf (defaults.attachEmailAsPdf) | K případu přiloží i samotný e-mail jako PDF s hlavičkou, tělem a seznamem příloh. Ve výchozím stavu vypnuté. Potřebuje LibreOffice. Když se PDF vytvořit nepodaří, případ a jeho dokumenty to neovlivní. |
Ignore Auto Replies (defaults.messageClass.ignoreAutoReplies) | Přeskočí automatické odpovědi (například nepřítomnost), pozvánky a doručenky a nezaloží z nich případ. Přeskočený e-mail se přesune do výstupní složky. Ve výchozím stavu zapnuté. Funguje jen u Microsoft Graph, u IMAP a POP3 se zpracuje každý e-mail. |
Allowed Prefixes, Ignored Classes (defaults.messageClass.advanced) | Jen pro Exchange s vlastními třídami zpráv. Allowed Prefixes jsou třídy, ze kterých případ vzniká (výchozí IPM.Note, běžný e-mail), Ignored Classes třídy, které se nikdy nezpracují (výchozí IPM.Note.Rules.OofTemplate.Microsoft, odpověď v nepřítomnosti). Jinak nechte prázdné. |
Schránku přidáte tlačítkem Add pod Mailboxes. Ikony v záhlaví schránky ji zkopírují nebo smažou.
| Parametr | K čemu slouží |
|---|---|
| Name | Název úlohy zobrazený v záhlaví. Nepovinné, bez něj se ukáže název připojení. Hodí se, když víc úloh čte stejnou schránku. |
| Email Processing | Povinné. Připojení ze Zpracování e-mailů, které úloha čte. |
| Folders: In | Složka, ze které cron e-maily čte. Tlačítko složky v poli otevře strom složek vybraného připojení (Microsoft Graph). U IMAP napište název složky, například INBOX. U POP3 se nevyplňuje. |
| Folders: Out | Složka, kam cron e-mail přesune, když z něj vznikl případ. POP3 ji nepoužívá. |
| Process: User Id | Uživatel, jehož jménem se případ založí. |
| Process: Template Process Id | Šablona, ze které případ vznikne. Podle ní se nabízejí proměnné níže. |
| Process: Header Id | Hlavička šablony, pod kterou se případ založí. |
| Parametr | K čemu slouží |
|---|---|
| Variables: Message Id | Proměnná pro Message-ID e-mailu. Nepovinné, evidence e-mailů ho zná i bez toho. |
| Variables: Subject, Sender, Recipients, Body, Received At | Proměnné šablony pro předmět, adresu odesílatele, adresy příjemců (oddělené středníkem), tělo e-mailu a datum přijetí. Prázdné pole znamená, že se údaj neuloží. |
| Variables: Headers | Vlastní hlavičky e-mailu do proměnných. Vlevo název hlavičky (například X-Invoice-Id), vpravo proměnná, tlačítko Add dvojici přidá. |
| Variables: Constants | Proměnné, které dostanou na každém založeném případu pevnou hodnotu, například status = Received by e-mail. Když stejná proměnná dostává i údaj z e-mailu, platí údaj z e-mailu. |
| Attachments, Ignored Attachment Types, Attach Email As Pdf, Message Class | Odchylka od výchozího nastavení jen pro tuto schránku. Prázdné pole znamená, že platí výchozí nastavení cronu. |
Jak cron e-mail zpracuje
- Pro každou schránku načte nejvýše Limit e-mailů ze vstupní složky.
- U každého e-mailu se podívá do evidence. E-mail ve stavu Zpracováno jen označí jako přečtený a přesune do výstupní složky. E-mail ve stavu Ukončeno po pokusech přeskočí.
- Ostatní e-maily zapíše do evidence jako Čeká na zpracování a založí z nich případ: nahraje přílohy, vyplní proměnné a evidenci přepne na Zpracováno.
- Podle nastavení přiloží e-mail jako PDF, spustí případ, označí e-mail jako přečtený a přesune ho do výstupní složky.
- Když něco selže dřív, než případ vznikne, dostane e-mail stav Chyba a cron ho zkusí při dalším běhu znovu, nejvýše pětkrát. Když selže až spuštění případu nebo přesun e-mailu, případ přejde do chybového stavu a e-mail cron přesune při dalším běhu.
Chyba jedné schránky ani jednoho e-mailu nezastaví zpracování ostatních. Každá chyba se zapíše do Logů.
Jak založit případ z e-mailu
- Připravte šablonu. Ve šabloně, ze které má případ vznikat, založte textové proměnné pro údaje z e-mailu (předmět, odesílatel, tělo) a případně proměnné s pevnou hodnotou. Ověřte, že šablona je aktivní a má hlavičku, a že první úkol má řešitele.
- Uložte heslo do Trezoru. V Administrace → Trezor založte tajný klíč s heslem schránky (IMAP, POP3), nebo s Client secretem registrace aplikace (Microsoft Graph).
- Založte připojení. Na stránce Zpracování e-mailů klepněte na Vytvořit připojení, zadejte název, vyberte typ a vyplňte parametry. Heslo vyberte z Trezoru. Uložte.
- Otestujte připojení. V nabídce řádku zvolte Otestovat připojení. Když test selže, opravte parametry podle zobrazené chyby.
- Nastavte cron. V Administrace → Crony otevřete cron Email processing (nebo ho přidejte tlačítkem Přidat cron). Pod Mailboxes přidejte schránku, vyberte připojení, vstupní a výstupní složku, uživatele, šablonu a hlavičku a přiřaďte proměnné. Uložte a cron zapněte.
- Ověřte výsledek. Pošlete do schránky zkušební e-mail a počkejte na další běh cronu (výchozí každých 5 minut). Na záložce Evidence e-mailů by měl být záznam se stavem Zpracováno a odkazem na nový případ.
- Když e-mail skončí ve stavu Chyba, přečtěte si sloupec Poslední chyba, příčinu opravte a počkejte na další běh. E-mail ve stavu Ukončeno po pokusech vraťte změnou stavu na Čeká na zpracování.
Další použití připojení
- Chytrá událost Mail na úkolu umí přes připojení vypsat složky a e-maily, načíst e-mail, označit ho jako přečtený a přesunout ho.
- Servisní konzole nabízí funkce
sys.mail.listFolders,listMails,getMail,listAttachments,setRead,moveMailaverify. Všechny berou jako první parametr název připojení, napříkladreturn await sys.mail.verify("Accounts payable – supplier invoices");.
Související: MS Graph (e-mail), Crony, Trezor, Stav systému, Logy, Servisní konzole
