MS Graph v2 (from v5.7.102)

The MsGraphCreateProcessesFromMailCron2 cron (hereinafter V2) creates cases from e-mails retrieved via Microsoft Graph. It is the successor to the MsGraphCreateProcessesFromMailCron cron (hereinafter the original cron). The original cron remains unchanged and keeps running – switching to V2 is a deliberate step you take when you decide to.

This article is written for consultants: what V2 brings, how to switch to it, and what each parameter means.

Availability

The core is the same on all versions. On 5.19, in addition:

• settings are entered in a form that catches errors as soon as you save,
• the user, template and header are selected from a list instead of typing IDs,
• fields that make no sense in the current context are hidden (e.g. attachment extensions only appear once their filter is enabled),
• the message type filter (messageClass) and header mapping (headerMapping) are available.

What is different in V2

A single error no longer brings down the whole run

This is the main reason V2 was created. With the original cron, one unavailable mailbox or one broken e-mail was enough to stop the rest of that run from being processed. V2 processes each mailbox and each e-mail independently. It records the problem and moves on.

Summary after every run

After every run, one summary record is added to the log: how many e-mails were retrieved, processed, skipped and failed. For each failed e-mail it lists the mailbox, subject, sender and reason. You no longer need to go through the whole log.

If there was at least one error in the run, the following can also be sent:

• summary e-mail – one message for the whole run (runSummary setting),
• e-mail to those responsible for a mailbox – each recipient only gets errors from their own mailboxes (errorEmailAddresses setting on the mailbox). If their mailboxes went through without errors, they receive nothing.

A successful run sends no e-mail.

Settings check before connecting

Before V2 connects to a mailbox, it checks its settings: credentials, folder IDs, numeric process IDs and conflicting attachment switches.

Protection against double processing

Only one of the crons MsGraphCreateProcessesFromMailCron and MsGraphCreateProcessesFromMailCron2 (including their clones) may be active at a time. Attempting to save the other one as active ends with an error. If this is bypassed by modifying the database, V2 detects at startup that the original cron is running, skips itself and logs the reason.

Other new features

• An e-mail for which a case could not be created stays unread in the input folder and is retried in the next run.
• Ignoring signature images – logos and banners don't have to be saved as case documents.
• E-mail as PDF – the message itself can be saved to the case as a PDF.
• Message type filter (5.19 only) – meeting invitations, delivery reports and "out of office" replies do not create a case.
• Header mapping (5.19 only) – a custom e-mail header can be saved into a variable.

Switching from the original cron

When you upgrade to a version with V2, the V2 cron is created automatically and pre-filled based on the original cron: mailboxes, credentials, mapping, schedule and timeout. However, it is created as inactive, so nothing starts on its own and nothing is processed twice. The original cron remains unchanged and keeps running.

Switchover procedure

1. Open the MsGraphCreateProcessesFromMailCron2 cron and review the pre-filled settings against the parameter tables below. Pay particular attention to runSummary – where the summary e-mails will be sent.
2. Deactivate the original cron MsGraphCreateProcessesFromMailCron.
3. Activate MsGraphCreateProcessesFromMailCron2.
4. After the first run, check the summary record in the log.

How to verify the converted settings

Run the following in the service console:

sys.msGraphConvertParamsForCron2()

The function returns the original cron's settings converted into the V2 structure without changing anything. Use it for comparison or to copy into V2. To convert a specific cron (e.g. a clone), pass its ID:

sys.msGraphConvertParamsForCron2(42)

Clones of the original cron

If you have cloned the original cron for multiple configurations, the migration does not convert the clones. It only lists them in the update log. For each clone:

1. convert its settings using sys.msGraphConvertParamsForCron2(CLONE_ID),
2. clone the V2 cron and paste the result into it,
3. deactivate the clone of the original cron and activate the V2 clone.

What changes during conversion

Configuration example

One mailbox for invoices. The responsible accountant receives errors from her mailbox, support receives the summary of the whole run, and signature images are not saved.

{
    "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": "INPUT_FOLDER_ID" },
                "out": { "id": "OUTPUT_FOLDER_ID" }
            },
            "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" }
            }
        }
    ]
}

Parameters

The Required column:

• Yes – if not filled in, the mailbox is not processed and the reason appears in the summary,
• No – can be omitted, the default value is used,
• Conditional – required only in the situation described for the parameter.

For optional parameters, deleting the key is the same as setting the default value. The form on 5.19 keeps some keys even with an empty value – that is fine.

Top level

runSummary – run summary

items[].auth – mailbox sign-in

items[].folders – folders

items[].process – what case is created

user_id, tproc_id and header_id must be numbers. On 5.19 you select them from a list, so they cannot be entered incorrectly.

items[].config – mailbox behavior

items[].messageClass – message type filter (5.19 only)

items[].mapping – what is stored in variables

The key is the name of the process variable; the value is a path in the e-mail, or an object { "value": …, "option": …, "isConstant": … }.

items[].headerMapping – headers into variables (5.19 only)

Optional. The key is the variable name; the value internetMessageHeaders loads the header with the same name as the variable.

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

The example fills the X-Header-Company variable from the X-Header-Company header.

Troubleshooting