MsGraphCheckUnprocessedMailsCron - Kontrola nezpracovaných mailů

Cron MsGraphCheckUnprocessedMailsCron je hlídací (kontrolní) úloha, která hlídá, jestli se e-maily zpracované přes integraci Microsoft Graph opravdu proměnily v případy v TAS. Když najde e-mail, ke kterému žádný případ nevznikl, upozorní na to určené administrátory e-mailem. Slouží tedy jako pojistka proti tichým výpadkům zpracování pošty.

K čemu to slouží (v kostce)

Zpracování příchozí pošty v TAS funguje zjednodušeně takto:

1. Do sledované schránky přijde e-mail.
2. TAS ho podle nastavení zpracuje a založí z něj případ.
3. Zpracovaný e-mail se přesune do složky „out" (odbavené).

Cron MsGraphCheckUnprocessedMailsCron se pak dívá do složky „out" a ověřuje, že ke každému e-mailu v ní existuje odpovídající případ. Pokud e-mail ve složce leží, ale případ k němu neexistuje, znamená to problém (chyba zpracování, špatné nastavení mapování apod.) — a cron pošle report.

Jak cron pracuje

1. Načte konfiguraci z tabulky cronů v databázi.
2. Připojí se k schránce přes Microsoft Graph a stáhne e-maily ze složky „out" za zadané období.
3. Vytáhne z e-mailů hodnoty podle nastaveného mapování (odesílatel, předmět, tělo…).
4. Porovná tyto hodnoty proti proměnným existujících případů dané šablony.
5. Najde nespárované e-maily — tedy ty, ke kterým žádný případ neexistuje.
6. Pošle HTML report na zadané adresy, pokud nějaké nespárované e-maily našel.
7. Zaloguje průběh do aplikačních logů.

Konfigurace

Konfigurace se ukládá jako JSON do parametrů cronu v administraci. V poli items může být více schránek — každá se zpracovává nezávisle.

Ukázka reálné konfigurace (citlivé údaje jsou zkrácené):

{
    "items": [
        {
            "numberOfDays": "10",
            "reportAddresses": [
                "frantisek.brych@neit.group"
            ],
            "auth": {
                "emailAddress": "vytezovana_adresa@teamassistant.app",
                "tenantId": "103bsdf-a80a-...",
                "clientId": "sdfsdsdfds-140249...",
                "clientSecret": "Msdfsdfsdfsdf-...",
                "type": "secret"
            },
            "folders": {
                "out": {
                    "id": "AAMkAD...AAA="
                }
            },
            "process": {
                "user_id": "1",
                "tproc_id": "1786",
                "header_id": "2043"
            },
            "mapping": {
                "_mail": {
                    "value": "mail",
                    "isConstant": true
                },
                "mailBody": "body.content",
                "mailSubject": {
                    "value": "subject",
                    "option": "optional"
                }
            }
        }
    ]
}

Parametry jedné schránky

Mapování polí e-mailu

V objektu mapping se říká: „vezmi tuto hodnotu z e-mailu a porovnej ji proti proměnné případu se stejným názvem". Klíč vlevo je název proměnné případu, hodnota vpravo určuje, odkud z e-mailu se údaj bere.

Jednoduché mapování — název proměnné → pole e-mailu:

"mailBody": "body.content"

Do proměnné mailBody se vezme obsah těla e-mailu.

Rozšířené mapování — s doplňkovými volbami:

"mailSubject": {
    "value": "subject",
    "option": "optional"
}

Do proměnné mailSubject se vezme předmět e-mailu, přičemž option: "optional" znamená, že pole je nepovinné (může chybět).

Konstanta — pevná hodnota pro každý e-mail:

"_mail": {
    "value": "mail",
    "isConstant": true
}

Při isConstant: true se do proměnné _mail nevkládá hodnota z e-mailu, ale pevný řetězec "mail". Slouží k odlišení nebo označení záznamů.

Nejčastější pole e-mailu k mapování:

• from — adresa odesílatele,
• subject — předmět,
• body.content — text těla,
• toRecipients / ccRecipients — příjemci / kopie.

Předpoklady na straně Azure

Cron čte poštu přes Microsoft Graph API. Než ho zapneš, musí být připravené:

1. Registrace aplikace v Azure Portal — vytvořená App Registration s oprávněním Mail.Read (případně Mail.ReadWrite), typ Application, nikoli Delegated.
2. Klientský secret — vygenerovaný, pokud používáš type: "secret". Poznamenej si Application ID a Tenant ID.
3. Přístup ke schránce — servisní aplikace musí mít oprávnění ke sledované schránce (typicky přes Exchange Admin Center).
4. Síť — server TAS musí mít odchozí HTTPS přístup na https://graph.microsoft.com (TCP 443).

Zapnutí a monitoring

Cron je po nasazení neaktivní. Zapíná se v administraci: Administrace → Crony, vyber „Check unprocessed MS Graph mails" a aktivuj ho.

Ve stejné obrazovce sleduješ:

• Stav — Aktivní / Neaktivní,
• Poslední běh — čas posledního spuštění,
• Další běh — plánovaný čas,
• Poslední chyba — „Y" značí chybu v posledním běhu, „N" úspěch.

Průběh se také zapisuje do aplikačních logů. Ukázky:

INFO: No unprocessed MS Graph mails found
  mailCount: 125
  processCount: 125

WARNING: Found 3 unprocessed MS Graph mails
  failedMails: [
    { subject: "Objednávka #12345" },
    { subject: "Faktura-2024-06" }
  ]

Řešení nejčastějších problémů