Microsoft 365 Email Input

The Microsoft 365 Email Input task allows the processing of emails from any of the organization's Microsoft 365 accounts, without having to specify a user's credentials. This way, privacy is maintained while allowing a process to handle email messages and attachments for any user. The task communicates through HTTPS. However, the real protection scheme (like certificates) is configured in Azure Active Directory by the IT administrators.

This task uses the Microsoft Graph API.
For this task to function correctly, Workflow needs to be granted application permissions or delegated permissions for Microsoft Graph in the organization’s Azure instance.
It needs read access to the Users category (User.Read.All) so that the task can identify the users in the organization.
In addition, in order to be able to read emails through the Microsoft 365 Email Input task, it needs the Mail.Read permission; the Mail.ReadBasic permission is insufficient as it does not grant access to the email’s body or attachments.
For more information on setting application permissions for Microsoft Graph, see https://docs.microsoft.com/en-us/graph/auth-v2-service.

Input

The Microsoft 365 Email Input task captures an email and its attachments from the selected inbox when it corresponds to the rules defined in the General tab.
It will process one email at a time (unless the process is self-replicating; see Process properties) and it will capture the emails as long as there is unread email in the selected inbox.

Processing

The task accesses Inbox folders in the organization through the Microsoft Graph API (subject to that organization's IT policies) .

Filtering is done at the mail server. Only the first unread email matching the conditions is retrieved from the mail server, along with its attachments. Captured emails can either be deleted or marked as read.

The MS Graph REST API is limited to a certain number of requests within a certain period of time. This is called throttling. When throttling comes into play, the plugin receives HTTP response 429. The plugin will log the error and retry, but it exits with an error after 15 unsuccessful attempts.

Output

Once the plugin is done processing, an XML file is created with the email’s details and location of the body and any attachments. The encoding of the XML file is UTF-8.

The body and attachments are located in the job's Temp folder of Workflow. Within the same process, those files must be moved to another location, otherwise they will be deleted at the end of the process (as expected for all files in Workflow's Temp folder).
Retrieving and moving the body and attachment files may be done using an XML Splitter.

Example output file
<?xml version="1.0"?>
<Email>
	<FromName>Anny One</FromName> 
	<FromEmail>onea@ca.objectiflune.com</FromEmail>
	<Subject>Your Subscription</Subject> 
	<DateTime>2020-01-22T14:03:38Z</DateTime>
	<To>someone@ca.yourcompany.com</To> 
	<CC/> 
	<BCC/> 
	<Files> 
		<File>
			<Type>Body</Type>
			<Folder>C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Debug\0106HBKO3IODK3F\</Folder>
			<Filename>0106HBKO3IODK40.html</Filename>
		</File>
		<File>
			<Type>Attachment</Type>
			<Folder>C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Debug\0106HBKO3IODK3F\</Folder>
			<Filename OriginalName="SubscriptionDetails.pdf">0106HBKO3X2KK41.pdf</Filename>
		</File>
		<File>
			<Type>Attachment</Type>
			<Folder>C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Debug\0106HBKO3IODK3F\</Folder>
			<Filename OriginalName="20171005_124920.jpg">0106HBKO4J5U342.jpg</Filename>					</File>
	</Files>
</Email>

The most pertinent information is located at the top level, under <Email>.
The sub node <Files> contains all the files for the email.
For each file, the type (body or attachment), folder and filename is provided. A file of type Body is always present and contains the body of the email.

The <Folder> information is the same for all files and is repeated to facilitate the selection when using an XML Splitter.

If multiple attachments have the same name, they will be appended with a numeric suffix, for example: File.pdf, File (1).pdf, File (2).pdf.

Job Information definitions

  • %1 - Date received. Contains the date of the reception of the email (and not the date of retrieval by PlanetPress Workflow). The format is YYYY/MM/DD HH:MM:SS.

  • %2 - Sender's name: Contains the name of the sender as defined by the sender himself (or, if the sender is using Exchange, by the name defined in his Exchange server).

  • %3 - Sender's address: Contains the email address of the sender as defined by the sender.

  • %4 - Subject: Contains the subject of the received email (may be blank).

  • %5 - Recipients:Contains a list of the names of all the recipients of the email, separated by a semicolon (;).

  • %6 - Attachment count: Contains the number of attachments of the email. A ZIP file is counted as 1 attachment. Some embedded images may be counted as attachment. The body of the email does not count as an attachment.

Task properties

General Tab

Condition

Enter the condition(s) that must be met for an unread email to be captured.

  • First found (no conditions): When no conditions are specified, the first unread email that is found will be processed (for each iteration of the plugin). In any other case, all conditions must be met for the email to get processed.

  • “From/To/CC/Subject/Body” contains: Select one or more options and enter the search text. "Contains" means that the search text can be surrounded by other text; for example, when looking for “world” in the “Subject” field, an email with the subject “Hello world, my name is Peter” will be captured.
    These condition fields are variable property fields. You can use any combination of text, variables and data selections; see Variable task properties. The use of the characters ? and * as wildcards is not supported in these fields.
    Note that it is not possible to specify multiple values in any of the fields and that conditions are case-insensitive.

Connection

  • Application ID: Enter the application ID provided by Azure for this specific application. This value is static and cannot contain variables.

  • Application Password: Enter the client secret (key) for the Azure app. This value is static and cannot contain variables.

  • Tenant ID: Enter the Tenant ID as specified in Azure. This value is static and cannot contain variables.

  • User ID: This is the user's ID or email address. This value is dynamic. You can use any combination of text, variables and data selections; see Variable task properties.

  • Use delegated permissions: Select this option to use delegated permissions instead of application permissions. Delegated permissions allow the application to log in as a standard registered user, and IT can grant that user account access to specific inboxes and specific OneDrive folders.
    Application permissions can be restricted to a strict minimum to ensure the plugin can perform its tasks, but no more. However, application permissions apply to all accounts in the organization: if the application has been granted permission to read emails, then that permission applies to all email accounts in the organization, and if it has access to OneDrive, it has access to all folders.

Post-processing

  • Select what to do when an email is processed: mark as read or delete the captured email from the account's Inbox.

Advanced properties

To get access to the following properties tabs, right-click the plugin in the process and select Advanced Properties.

"Other" Tab
  • Job Information group
    • Information elements: Indicates what Job Info variables are automatically created by the input task.
    • Add lines before first data page: Using the arrows keys you can add any job information directly at the beginning of your data file.
  • Backup input files: Check this to save a copy of each data file that is captured by your input. These files are saved in the PlanetPress Workflow Tools working folders under the "Backup" folder.
    To navigate quickly to the Workflow working folders, press the keyboard shortcut CTRL+ALT+Shift+F4 from within the Workflow configuration tool.
    The number of days to keep backups of jobs processed by input tasks is set per process; see Process properties.
  • Backup filename: Enter the file name that you wish the input data file backup to be saved under.
  • Delete Existing Metadata: Check to remove any Metadata from memory. This option is disabled on initial input tasks, and is checked by default on secondary input tasks.

On Error Tab

For a description of the options on the On Error tab see Using the On Error tab.

Miscellaneous Tab

The Miscellaneous tab is common to all tasks.

It contains a text area (Task comments) that lets you write comments about the task. These comments are saved when the dialog is closed with the OK button and are displayed in The Task Comments Pane.

Check the option Use as step description to display the text next to the icon of the plugin in the Process area.

The tab also provides an option to highlight the task in The Process area with the default color, set in the Preferences (see Colors), or the color selected or defined under Highlight color on this tab.
To revert the selected highlight color to the default color, open this tab, turn the Highlight option off and close the dialog with the OK button; then turn highlighting back on.
Highlighting can also be turned on and off via the task's contextual menu and with the Highlight button on the View ribbon.