← Using the Mail Definition Type

Mail Inbound User Guide

The Mail Inbound module allows you to react to operator and user messages using your email client without having to log on to the Redwood platform. An email is sent to the user with all replies for the user message in the form of mail-to hyperlinks. The user clicks one of these links and a mail reply is generated that can be sent to the corresponding operator or user message. In the central Redwood server, a mail connector monitors the IMAP inbox for emails and starts a process for each incoming mail. The process applies rules to extract the responses and replies to the corresponding operator or user message and moves the email to another folder. The mail inbound module consists of two components:

  • Mail Connector - Represents the connection to the inbox of a specific email account
  • Mail Reactor - Chain definition started by the mail connector for each incoming email to be processed

Figure 1: The Mail Inbound Module Workflow

Every incoming mail in the reactor inbox leads to the start of a reactor process (see Section 3).

Installation and Requirements

In version 9.2.x and later a mail-reactor.car file is delivered with the Redwood server installation.

note

Mail inbound is only visible when license ProcessServerService.MailConnector.limit is in place.

From the Control Center:

  1. Click Configuration in the left-hand navigation bar.
  2. Select Software and select the mail-reactor.car line item.
  3. Right click and select Download from the dropdown to download the car file to a local directory.
  4. Click Promotion in the left-hand navigation bar.
  5. Select Imports and select the Import definitions from: mail-reactor.car line item.
  6. Click the Add icon (plus sign in circle) in the toolbar to install the mail inbound module.
  7. The Submit Import Wizard window will open.
  8. Select Upload file to server and choose the car file downloaded in Step 3 and click Next.
  9. Select Use embedded Import Rule Set with Target Partition and click Next.
  10. Bypass Import Action Parameters by clicking Next.
  11. Under Import Details, you have the option to set the Description, add more Documentation, set a Requested Start Time, or choose whether to set it to Test Mode.
  12. Click Submit.
  13. Click Applications on the left-hand navigation bar. A successful installation creates an application named Redwood_MailReactor. It contains the mail reactor chain, which is used by default. Further customization within the Redwood_MailReactor application is possible.

Mail Connectors

A mail connector polls email accounts for incoming emails.

Add a New Mail Connector

To add a new mail connector:

  1. Open the Control Center on the left-hand navigation bar.
  2. Select Mail Connectors from the Environment dropdown.
  3. Click the Add icon (plus sign in circle) or right click inside the Mail Connectors tab and select New mail connector...
  4. The New Mail Connector window will open. Mandatory fields are indicated with a red stripe.
  5. Fill in the mandatory fields detailed below and click the Check connection button to ensure that the mail connector can connect to the desired email account.
    1. Partition - Name of the partition to store the mail connector object (security criteria), selectable from a list.
    2. Name - Name of the mail connector object (typically indicating the email account), 80 characters maximum
    3. Description - Description of the mail connector object, 256 characters maximum
    4. Application - The assigned application of the mail connector object (organizational criteria), selectable from a list
    5. Username - Redwood email account, receiving the answered user message
    6. Password - Password of the Redwood email account
    7. Protocol - Communication protocol accepted by the email server. Supported communication protocols:
      1. IMAP
      2. IMAPS
      3. POP3
      4. POP3S
      5. MS Graph
    8. E-mail server name or IP - Server name or IP address of the email server for the receiving email account
    9. Server Secret - Will be set automatically, but can be set manually when a specific secret needs to be used
    10. Inbox Folder - The folder which needs to be checked for incoming emails, typically Inbox
    11. Error Folder - The folder where the incoming email will be moved to when the reactor process does not finish successfully; this folder will be automatically created within the receiving email account if it does not already exist
  6. Processed Folder - The folder where the incoming email will be moved when the reactor process finishes successfully; this folder will be automatically created within the receiving email account if it does not already exist
    1. Polling interval - The number of seconds between checks of the email account; default 10 seconds.
    2. Process Definition - The chain to start for each valid email received; default Redwood_Mail_Reactor.
    3. Start On Startup - Whether the mail connector starts automatically after the startup of the Redwood server; the default is activated
  7. Additional connection settings can be added if required. By default, no additional property is used. See JavaMail API IMAP protocol documentation for details.
  8. Press Save & Close.

Using OAuth 2.0

Settings for Microsoft Azure Active Directory:

  • App registration
    • Public client flow allowed for App authentication
    • Delegated Microsoft Graph API permissions
      • IMAP.AccessAsUser.All
      • offline_access
      • Granted consent for all API permissions
    • Additional Connection Settings for MailConnector
      • redwood.connection.oauth.provider
        • The OAuth 2.0 token provider. Currently only "outlook" is supported.
      • redwood.connection.oauth.client
        • The Application (client) ID of the app registered in Microsoft Azure Active Directory.
      • redwood.connection.oauth.tenant
        • The Directory (tenant) ID of the app registered in Microsoft Azure Active Directory.
      • redwood.connection.oauth.authority (optional)
        • The OAuth 2.0 authorization endpoint. This setting is optional and defaults to the Azure Active Directory authorization endpoint URL: https://login.microsoftonline.com/ The Mail Connector passes a scope request, such as “Mail.ReadWrite” to the authorization endpoint, in order that access will be granted and an OAuth 2.0 token obtained.

Using Microsoft Graph

Settings for Microsoft Azure Active Directory

  • App registration
    • Public client flow allowed for App authentication
    • Delegated Microsoft Graph API permissions
      • Mail.ReadWrite
      • Granted consent for the API permission
  • Settings for the Mail Connector:
  • Connection Settings for the MailConnector
    • redwood.connection.oauth.client
      • The Application (client) ID of the app registered in Microsoft Azure Active Directory.
    • redwood.connection.oauth.tenant
      • The Directory (tenant) ID of the app registered in Microsoft Azure Active Directory.
    • redwood.connection.oauth.authority (optional)

Start or Stop the Mail Connector

Once the mail connector object has been created, right click the mail connector to Start or Stop it running.

Figure 7: Right Click Mail Connector to Start or Stop

Mail Connector Tracing

Mail connectors are treated as part of the Redwood server.

See server1/logs/scheduler.log or watch out for an operator message in the mail connector details. Or use the process definition System_DynamicTrace with the package com.redwood.scheduler.mail.connector for specific tracing details.

Mail Reactor

The mail reactor is basically the reacting part of the module, a chain starting for each incoming email. The current default chain is delivered with the deployment of the mail-reactor.car file described in Section 1.1.

Figure 8: Redwood_MailReactor

This example reactor chain consists of two steps, the Parser and the Handler. The Parser takes the raw email data from the starting chain, extracts the necessary information, and puts the parsed mail data into an out parameter in JSON format. The Handler takes the parsed mail data, handles additional attachments, and answers the user message via email as requested in the workflow.

Figure 9: The Mail Reactor Chain - Parser and Handler

When the reactor chain is finished successfully the original mail is moved to the processed folder. If an error occurs, the original mail is moved to the error folder.

Figure 10: Error and Processed Folders

Lifecycle of the Reactor Process

The following workflow diagram displays the lifecycle of the reactor process.

Figure 11: Lifecycle of the Reactor Process

As a Business User

Financial processes often require user interaction. For example, an approval or rejection after results have been checked on certain process stages. The goal of mail inbound is to give a business user the ability to reply to requests directly in the email with the use of mail-to hyperlink so that user effort is minimal.

Figure 12: Mail-to Hyperlink Options

The options depend on the chosen workflow within the automated process. In the example above, the mail-to hyperlink options are Reply Confirm, Forward, and Delegate.

  • If Reply Confirm is chosen, the reply email will pop up automatically. Press send and the user message will be replied to a few seconds later.
  • Forward is used when another person should be involved in the workflow but should not be able to finalize, for example when attached results need to be checked by another person.
  • Delegate gives another person the responsibility to finalize the workflow, for example when responsibility needs to be shifted to another department or procedures have been changed
note

Do not enter any additional text in the email after the mark:

Add Attachments

It is also possible to add attachments in the replying e-mail. Choose one of the offered options and click on the attach file option in your e-mail client to attach the desired file(s) to the replying e-mail.

Some file formats cannot be added. In the example below there are three attachments, a screenshot (.jpg), an Excel (.xlsx) and a text file (.txt). But in the Redwood Inbox there are only two additional files, the .jpg and .txt file. The third file in the Inbox is the original spool file which has been created by the business process. The Excel file has been ignored. This behavior is adjustable in the mail reactor process (chain).

Figure 13: Inbox Attachments

Workflow Parameter

By default, three base workflows are available in the Redwood platform: Redwood_Base_Workflow_Confirm, Redwood_Base_Workflow_RestartContinueAbort, and Redwood_Base_Workflow_AcceptReject. A workflow is used by an automated process whenever a decision, an approval or any other additional check is necessary in between process steps. The process stops and is waiting for the reply when a workflow is initiated. Depending on the reply the process continues, aborts or restarts.

Each of the workflows has a specific parameter group used for mail inbound called Mail reactor*. Activate when a react e-mail should be generated within the mail reactor parameter.

Figure 14: Mail Reactor Parameter

← Using the Mail Definition Type