MS Graph (email)
MS Graph connects TAS to Microsoft 365 mailboxes: it can create cases from incoming mail and send mail from TAS via Graph (or via SMTP with OAuth2). An administrator sets it up in Crons and in Configuration; it requires an app registration in Microsoft Entra ID. EWS (the older connection to Exchange Web Services) is no longer available in TAS – MS Graph is the only supported option.
Cases from incoming mail are created by the Email processing cron, using a connection from Administration → Email Processing. The crons described in the section Creating cases from incoming mail do not exist in version 5.21. How to migrate their settings is described in the From version 5.21 section below. Sending mail does not change.
Creating cases from incoming mail
Two crons download mail and create cases. Only one of them may run at a time; TAS enforces this and blocks the other cron:
| Cron | Note |
|---|---|
| Create Processes from MS Graph mails | Older variant. |
| Create Processes from MS Graph mails (v2) | Successor, recommended for new deployments. When you upgrade an installation that used the older cron, TAS automatically creates the v2 variant with the same settings, but inactive – activate it yourself once you have verified that the settings are correct. |
A separate cron, MsGraphCheckUnprocessedMailsCron, checks whether unprocessed mail is left in the mailbox, for example because of a processing error.
v2 cron settings
| Parameter | Meaning |
|---|---|
amountOfEmailByRun | How many emails the cron processes per run (default 100). |
runSummary.log / .sendEmail / .emailAddresses | Whether the run is logged and/or a summary email is sent, and to whom. |
items[] | One item = one monitored mailbox/folder; the cron can have several configured at once. |
items[].auth.emailAddress | Address of the mailbox to read from. |
items[].auth.tenantId, .clientId, .clientSecret | Details of the app registered in Entra ID (see below). Apply only to type: "secret". |
items[].auth.type | secret (app with a client secret) or dedicated (interactive sign-in without a stored secret). |
items[].auth.scope | Permission scope; if left empty, https://graph.microsoft.com/.default is used (all application permissions the Entra ID administrator granted to the app). |
items[].folders.in.id / .out.id | ID of the folder to read from and of the folder messages are moved to after processing. |
items[].process.user_id, .tproc_id, .header_id | The user under which the case is created, and the template/header it is created in. |
items[].mapping, .headerMapping | Mapping of email fields (subject, body, sender, attachments) to case variables. |
items[].messageClass.enabled, .allowedPrefixes, .ignoredClasses | Restriction by message type (e.g. skipping automatic replies). |
items[].config.setEmailProcessedOnError | Whether the email is marked as processed even after an error, so the cron does not get stuck on the same message. |
items[].config.ignoreAllAttachments / .ignoreSpecificAttachments / .ignoredAttachmentTypes / .ignoreInlineAttachments | Controls which attachments are attached to the case. |
items[].config.attachEmailAsPdf | Attaches the email itself as a PDF. |
items[].config.useEmailObjectInDataHolder | Makes the whole email available as an object for template calculations instead of mapping it to individual variables. |
You can get the mailbox folder IDs for
folders.in/folders.out by calling the administrator endpoint POST /ms-graph/discover-folders; you do not have to look them up manually in Graph Explorer.App registration in Entra ID
The cron needs an app registered in Microsoft Entra ID with an application permission to read (and, if needed, write) mail in the target mailbox, granted by the tenant administrator. From the registration you need tenantId, clientId and clientSecret (for the secret variant).
Do not enter the value directly in the
clientSecret field of the cron parameters – store it as a secret in the Vault and reference it with {{vault:nazev-klice}}. Do the same for the client secret used for sending mail below.Sending mail via Graph or SMTP with OAuth2
Outgoing mail is configured in Configuration (email section), independently of the crons above. TAS supports two independent methods:
Type (integrations.mail.type) | How it works | Key parameters |
|---|---|---|
msgraph | Mail is sent directly via the Graph API (/sendMail), not via SMTP. | tenantId, clientId, clientSecret, sender, optionally scope (default .default). |
oauth2 | A standard SMTP server, but a short-lived OAuth2 token is used instead of a password (a generic mechanism, not only for Microsoft 365). | host, port, basicAuth.user (mailbox), oauth2.host (token endpoint), oauth2.clientId, oauth2.clientSecret, oauth2.grantType, oauth2.scope. |
Both sets of parameters can also be set with environment variables (TAS_MAIL_SMTP_TYPE, TAS_MAIL_MSGRAPH_* for the first type, TAS_MAIL_SMTP_* and TAS_MAIL_OAUTH2_* for the second) – details on editing in Configuration are in the article Configuration.
From version 5.21: migrating to Email Processing
Version 5.21 removed the crons Create Processes from MS Graph mails (MsGraphCreateProcessesFromMailCron), Create Processes from MS Graph mails (v2) (MsGraphCreateProcessesFromMailCron2) and Check unprocessed MS Graph mails (MsGraphCheckUnprocessedMailsCron). Their rows in Crons remain after the upgrade, including their parameters, so that the settings can be carried over; delete them once migrated. You now configure a mailbox once as a connection in Administration → Email Processing, and cases are created from it by the Email processing cron. Details are in the article Email Processing.
Migrating the settings
- In the Service Console, run
return await sys.mail.migrateMsGraphToNewEmailStuff();. The function only lists what it would do and changes nothing. - If the preview is correct, run
return await sys.mail.migrateMsGraphToNewEmailStuff(true);. For each mailbox address from the old crons, it creates a connection of typemsgraph. It derives the name from the address (for exampleinvoices@company.com→invoices-company-com) and writes the source cron into the description. A client secret entered directly in the parameters is stored in the Vault as the secretmsgraph-<connection name>; an existing{{vault:…}}reference is kept. If a mailbox is used in several crons, the details from the v2 variant are used. You can run the function repeatedly; existing connections are skipped. - Review the warnings in the result: add the client secret manually to connections that lack one; connections using the discontinued
dedicatedsign-in are migrated assecret– switch them tomanagedIdentityif appropriate. - The function does not migrate the cron settings. In Administration → Crons, open the Email processing cron (or create it with the Add cron button) and add a mailbox for each connection. From the old parameters, take over the folders (
folders.in.id,folders.out.id), the user, template and header (process.user_id,tproc_id,header_id) and the variable mapping. - Enable the Email processing cron and delete the old cron rows.
| Original parameter | In the Email processing cron |
|---|---|
items[].mapping | Variables fields: Subject, Sender, Recipients, Body, Received At and Message Id. The new cron assigns a variable to each email detail; it does not support expressions. |
items[].headerMapping | Variables: Headers, but reversed: header name on the left, variable on the right. {"InvoiceId": "X-Invoice-Id"} becomes X-Invoice-Id → InvoiceId. |
config.ignoreAllAttachments | Attachments = skip. |
config.ignoreSpecificAttachments, config.ignoredAttachmentTypes | A single Ignored Attachment Types list. |
config.attachEmailAsPdf, messageClass | The same options Attach Email As Pdf and Message Class. Message Class still works only with Microsoft Graph. |
runSummary, errorEmailAddresses | Removed; no run summary email is sent. Every error is recorded in Logs and in Email Records. |
| Cron Check unprocessed MS Graph mails | No replacement. Unprocessed emails are shown in Email Records and on the System Status page. |
The
sys.msGraph* functions in the Service Console have been replaced by sys.mail.* functions, which take the connection name instead of the mailbox's position in the cron parameters. The POST /ms-graph/discover-folders endpoint has been replaced by the Discover folders action on the connection. The configuration key featureFlag.msGraph.maxHeadSize has been renamed to featureFlag.mail.maxHeadSize. If you changed it, set the value again under the new key.Related: Email Processing, Crons, Configuration, Vault, Authentication.