MsGraphCheckUnprocessedMailsCron - Checking Unprocessed Emails

The MsGraphCheckUnprocessedMailsCron cron is a monitoring (check) job. It verifies that emails processed through the Microsoft Graph integration actually became cases in TAS. If it finds an email for which no case was created, it notifies the designated administrators by email. It acts as a safeguard against silent failures in mail processing.

This cron does not create cases from emails by itself. That is done by a different job (MsGraphCreateProcessesFromMailCron). This job only checks that everything that should have been processed was actually processed.

What it is for (in a nutshell)

In simplified terms, incoming mail processing in TAS works like this:

  1. An email arrives in the monitored mailbox.
  2. TAS processes it according to the settings and creates a case from it.
  3. The processed email is moved to the "out" folder (handled emails).

The MsGraphCheckUnprocessedMailsCron cron then looks into the "out" folder and verifies that a matching case exists for every email in it. If an email is in the folder but no case exists for it, there is a problem (a processing error, incorrect mapping settings, etc.), and the cron sends a report.

How the cron works

  1. Loads the configuration from the crons table in the database.
  2. Connects to the mailbox via Microsoft Graph and downloads emails from the "out" folder for the specified period.
  3. Extracts values from the emails according to the configured mapping (sender, subject, body…).
  4. Compares these values against the variables of existing cases of the given template.
  5. Finds unmatched emails, i.e. emails for which no case exists.
  6. Sends an HTML report to the specified addresses if it found any unmatched emails.
  7. Logs the run to the application logs.

Property

Value

Schedule

Every hour (00 00 */1 * * *)

Timeout

600 seconds (10 minutes) per run

Processing

Each mailbox separately. An error in one does not block the others.

Default state

Inactive. It must be enabled manually in the administration.

Configuration

The configuration is stored as JSON in the cron parameters in the administration. The items array can contain multiple mailboxes, and each one is processed independently.

Example of a real configuration (sensitive data is truncated):

{
"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"
}
}
}
]
}

clientSecret is the application password. Never share it, send it by email or commit it to a version control system. Always redact it in reports and when reporting errors.

Parameters of a single mailbox

Parameter

Required

Description

numberOfDays

Yes

How many days back emails and cases are checked. For example, "10" = the last 10 days.

reportAddresses

Yes

List of email addresses that receive the report on unmatched emails. At least one is required. With multiple addresses, the first one goes in the "To" field and the others are sent as blind copies (BCC).

auth.emailAddress

Yes

Email address of the monitored mailbox in Microsoft 365 (the address emails are extracted from).

auth.tenantId

Yes

Tenant ID in Azure AD (Microsoft Entra). You can find it in Azure Portal → Microsoft Entra ID → Properties.

auth.clientId

Yes

Application (client) ID of the registered application in Azure Portal.

auth.clientSecret

Yes (for type: "secret")

Value of the client secret from the app registration. Sensitive data.

auth.type

Yes

Sign-in method. For automated cron runs, use "secret" (application sign-in using a secret). The value "dedicated" is for interactive sign-in through a browser and is not suitable for the cron.

folders.out.id

Yes

ID of the "out" folder in Microsoft Graph that processed emails are moved to. This is the folder the cron checks.

process.user_id

Yes

ID of the TAS user under whom cases are created.

process.tproc_id

Yes

Process template ID. The cron matches emails against cases created from this template.

process.header_id

Yes

Process header (group) ID. It further narrows down which cases are included in the comparison.

mapping

Yes

Specifies which values are extracted from the email and which case variables they are compared against. See below.

Numeric values (numberOfDays, tproc_id, header_id, user_id) can also be written in the configuration as quoted text (e.g. "10", "1786"), as shown in the test example. TAS reads them correctly.

Mapping email fields

The mapping object says: "take this value from the email and compare it against the case variable with the same name". The key on the left is the case variable name, and the value on the right specifies where in the email the data comes from.

Simple mapping: variable name → email field:

"mailBody": "body.content"

The content of the email body is put into the mailBody variable.

Extended mapping: with additional options:

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

The email subject is put into the mailSubject variable. option: "optional" means the field is optional (it may be missing).

Constant: a fixed value for every email:

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

With isConstant: true, the _mail variable does not receive a value from the email but the fixed string "mail". It is used to distinguish or label records.

Most common email fields to map:

  • from: sender address,
  • subject: subject,
  • body.content: body text,
  • toRecipients / ccRecipients: recipients / copy (CC) recipients.

Prerequisites on the Azure side

The cron reads mail through the Microsoft Graph API. Before you enable it, the following must be in place:

  1. App registration in Azure Portal: an App Registration with the Mail.Read permission (or Mail.ReadWrite), of type Application, not Delegated.
  2. Client secret: generated if you use type: "secret". Write down the Application ID and Tenant ID.
  3. Mailbox access: the service application must have permission to access the monitored mailbox (typically granted through the Exchange Admin Center).
  4. Network: the TAS server must have outbound HTTPS access to https://graph.microsoft.com (TCP 443).

Client secrets in Azure have a limited validity (usually 1–2 years). When a secret expires, the cron stops working with a sign-in error. You need to generate a new secret and update the configuration.

Enabling and monitoring

After deployment, the cron is inactive. To enable it, go to Administration → Crons, select "Check unprocessed MS Graph mails" and activate it.

On the same screen you can monitor:

  • Status: Active / Inactive,
  • Last run: time of the last run,
  • Next run: scheduled time,
  • Last error: "Y" indicates an error in the last run, "N" indicates success.

Each run is also written to the application logs. Examples:

Successful run (no action needed)
INFO: No unprocessed MS Graph mails found
mailCount: 125
processCount: 125
Unmatched emails found (a report is sent)
WARNING: Found 3 unprocessed MS Graph mails
failedMails: [
{ subject: "Objednávka #12345" },
{ subject: "Faktura-2024-06" }
]

Troubleshooting common problems

Symptom

Likely cause and solution

"No report addresses defined…"

The reportAddresses field is empty. Add at least one address and save.

Sign-in error / "Unknown credentials type"

Incorrect auth.type value. It must be exactly "secret" or "dedicated". For the cron, use "secret" with a valid clientSecret.

The report lists all emails as unprocessed

Most often caused by an incorrect mapping (values from the email do not match the case variables) or an incorrect tproc_id / header_id. Check the field names and the template ID.

"Folder Not Found" / invalid folders.out.id

The folder ID is wrong or the folder was deleted. You can find the correct ID using Microsoft Graph Explorer: GET /users/{schránka}/mailFolders.

Timeout (run longer than 10 minutes)

The mailbox contains too many emails or the network is slow. Reduce numberOfDays, or split the mailboxes into separate configurations.

The cron does not run / log entries are missing

The cron is most likely inactive. Check its status in the administration and verify network access to graph.microsoft.com.

Frantisek Brych Updated by Frantisek Brych

CleanupCron

Crons

Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)