MS Graph v2 (od v5.7.102)

Cron MsGraphCreateProcessesFromMailCron2 (dále jen V2) zakládá případy z e-mailů načtených přes Microsoft Graph. Je nástupcem cronu MsGraphCreateProcessesFromMailCron (dále jen původní cron). Původní cron zůstává beze změny a běží dál – na V2 se přechází vědomě, až když se rozhodnete.

Článek je psaný pro konzultanty: co V2 přináší, jak na něj přejít a co znamená každý parametr.

Dostupnost

Základ je na všech verzích stejný. Na 5.19 navíc:

• se nastavení zadává ve formuláři, který chyby hlídá už při uložení,
• uživatele, šablonu a hlavičku vybíráte ze seznamu místo psaní ID,
• pole, která nedávají smysl, jsou skrytá (např. přípony příloh se ukážou až po zapnutí jejich filtru),
• je k dispozici filtr typu zprávy (messageClass) a mapování hlaviček (headerMapping).

Co je ve V2 jinak

Jedna chyba už neshodí celý běh

To je hlavní důvod, proč V2 vznikl. U původního cronu stačila jedna nedostupná schránka nebo jeden rozbitý e-mail a zbytek se v tom běhu nezpracoval. V2 zpracovává každou schránku i každý e-mail samostatně. Problém zapíše a pokračuje dál.

Souhrn po každém běhu

Po každém běhu přibude do logu jeden souhrnný záznam: kolik e-mailů se načetlo, zpracovalo, přeskočilo a selhalo. U každého neúspěšného e-mailu uvádí schránku, předmět, odesílatel a důvod. Celý log už procházet nemusíte.

Když v běhu byla alespoň jedna chyba, může navíc odejít:

• souhrnný e-mail – jedna zpráva za celý běh (nastavení runSummary),
• e-mail odpovědným za schránku – každý dostane jen chyby svých schránek (nastavení errorEmailAddresses u schránky). Když jeho schránky prošly bez chyby, nedostane nic.

Úspěšný běh žádný e-mail neposílá.

Kontrola nastavení před připojením

Než se V2 připojí ke schránce, zkontroluje její nastavení: přihlašovací údaje, ID složek, číselná ID procesu a kolidující přepínače příloh.

Ochrana proti dvojímu zpracování

Aktivní smí být vždy jen jeden z cronů MsGraphCreateProcessesFromMailCron a MsGraphCreateProcessesFromMailCron2 (včetně jejich klonů). Pokus uložit jako aktivní i druhý z nich skončí chybou. Když se to obejde zásahem do databáze, V2 si při startu všimne, že běží původní cron, přeskočí se a zapíše proč.

Další novinky

• E-mail, u kterého se nepodařilo založit případ, zůstane nepřečtený ve vstupní složce a zkusí se znovu při dalším běhu.
• Ignorování obrázků z podpisu – loga a bannery se nemusí ukládat jako dokumenty případu.
• E-mail jako PDF – samotnou zprávu lze uložit k případu jako PDF.
• Filtr typu zprávy (jen 5.19) – pozvánky, doručenky a odpovědi „mimo kancelář“ nezaloží případ.
• Mapování hlaviček (jen 5.19) – vlastní hlavičku e-mailu lze uložit do proměnné.

Přechod z původního cronu

Při upgradu na verzi s V2 se cron V2 založí sám a předvyplní podle původního cronu: schránky, přihlašovací údaje, mapování, rozvrh i timeout. Založí se ale jako neaktivní, takže se nic samo nespustí a nic se nezpracuje dvakrát. Původní cron zůstává beze změny a běží dál.

Postup přepnutí

1. Otevřete cron MsGraphCreateProcessesFromMailCron2 a projděte předvyplněné nastavení podle tabulek parametrů níže. Zkontrolujte hlavně runSummary, kam budou chodit souhrnné e-maily.
2. Deaktivujte původní cron MsGraphCreateProcessesFromMailCron.
3. Aktivujte MsGraphCreateProcessesFromMailCron2.
4. Po prvním běhu zkontrolujte v logu souhrnný záznam.

Jak ověřit převedené nastavení

V servisní konzoli spusťte:

sys.msGraphConvertParamsForCron2()

Funkce vrátí nastavení původního cronu převedené do struktury V2 a nic přitom nezmění. Poslouží k porovnání nebo ke zkopírování do V2. Konkrétní cron (např. klon) převedete podle jeho ID:

sys.msGraphConvertParamsForCron2(42)

Klony původního cronu

Pokud máte původní cron naklonovaný pro více konfigurací, migrace klony nepřevádí. Jen je vypíše do update logu. U každého klonu:

1. převeďte jeho nastavení funkcí sys.msGraphConvertParamsForCron2(ID_klonu),
2. naklonujte cron V2 a vložte do něj výsledek,
3. deaktivujte klon původního cronu a aktivujte klon V2.

Co se při převodu změní

Příklad nastavení

Jedna schránka pro faktury. Odpovědná účetní dostává chyby své schránky, podpora dostává souhrn celého běhu a obrázky z podpisů se neukládají.

{
    "amountOfEmailByRun": 100,
    "runSummary": {
        "log": true,
        "sendEmail": true,
        "emailAddresses": ["podpora@firma.cz"]
    },
    "items": [
        {
            "auth": {
                "type": "secret",
                "emailAddress": "faktury@firma.cz",
                "tenantId": "00000000-0000-0000-0000-000000000000",
                "clientId": "00000000-0000-0000-0000-000000000000",
                "clientSecret": "{{vault:msgraph-faktury}}"
            },
            "folders": {
                "in": { "id": "ID_VSTUPNI_SLOZKY" },
                "out": { "id": "ID_VYSTUPNI_SLOZKY" }
            },
            "process": {
                "user_id": 1,
                "tproc_id": 25,
                "header_id": 3
            },
            "config": {
                "errorEmailAddresses": ["ucetni@firma.cz"],
                "ignoreInlineAttachments": true
            },
            "mapping": {
                "sender": { "value": "from.emailAddress.address", "option": "optional" },
                "mailSubject": { "value": "subject", "option": "optional" },
                "mailBody": { "value": "body.content", "option": "optional" }
            }
        }
    ]
}

Parametry

Sloupec Povinné:

• Ano – bez vyplnění se schránka nezpracuje a důvod se objeví v souhrnu,
• Ne – můžete vynechat, použije se výchozí hodnota,
• Podmíněně – povinné jen v situaci popsané u parametru.

U nepovinných parametrů je smazání klíče totéž jako nastavení výchozí hodnoty. Formulář na 5.19 si některé klíče drží i s prázdnou hodnotou, to nevadí.

Hlavní úroveň

runSummary – souhrn běhu

items[].auth – přihlášení ke schránce

items[].folders – složky

items[].process – jaký případ se zakládá

user_id, tproc_id a header_id musí být čísla. Na 5.19 je vybíráte ze seznamu, takže je špatně zadat nejdou.

items[].config – chování schránky

items[].messageClass – filtr typu zprávy (jen 5.19)

items[].mapping – co se uloží do proměnných

Klíč je název proměnné procesu, hodnota je cesta do e-mailu, nebo objekt { "value": …, "option": …, "isConstant": … }.

items[].headerMapping – hlavičky do proměnných (jen 5.19)

Nepovinné. Klíč je název proměnné, hodnota internetMessageHeaders načte hlavičku se stejným názvem, jako má proměnná.

"headerMapping": {
    "X-Header-Company": "internetMessageHeaders"
}

Příklad naplní proměnnou X-Header-Company z hlavičky X-Header-Company.

Řešení potíží