Configuration of the Mailbridge

The Mailbridge system requires several configuration steps across different levels of the ADITO environment. This document outlines the procedures for defining aliases, configuring project-wide preferences, setting up technical users, and activating the service within the instance configuration.

info

This section covers the IMAP mail server. There is a separate section for Microsoft Azure Exchange mail server connection (Graph API).

---

Mailserver Alias Definition

The initial step in setting up the Mailbridge is the definition of a mailserver alias. This alias serves as the connection point between the ADITO system and the external mail server.

To create a new mailserver alias, right-click the alias node in the project tree and select New. Assign a descriptive name, such as mailserverMailbridge. In the subsequent dialog, select Mailserver IMAP as the alias type.

Figure: Creating a new Mailserver IMAP alias in the project tree.

If incoming emails must be archived or copied to a repository, a second alias for the mail repository is required. Standard xRM-based projects typically include a pre-defined database mail repository alias named defaultDbRepository. If this alias is missing or a different storage method is required, create a new alias and select either Mailrepository DB for database storage or Mailrepository IMAP if the emails should be stored in a separate IMAP account. There is also a new mail repository type for Microsoft Exchange (Mailrepository Graph).

info

Like the mailserver for Graph, the mail repository for Graph is covered in a separate section.

When using an IMAP repository, a distinct mail server user or a different folder within the same mailbox must be specified to avoid conflicts with the primary Mailbridge account. All new alias definitions must be deployed to the system to become active.

---

System Alias Configuration

After deployment, the alias definitions are available for system-specific configuration. Open the target system in the project tree to create the necessary alias configurations.

Right-click the respective alias entry and select Create from the context menu to initialize the configuration.

Figure: Initializing the alias configuration within the system settings.

Once the alias configuration is created, the connection properties for the receiving side of the mailserver alias must be defined.

Figure: Configuration interface for mailserver IMAP properties.

Technical Connection Properties

The following table describes the essential properties for the IMAP connection:

Property	Description
host	The IP address or URL of the mail server, supporting both on-premise solutions and cloud services like Microsoft 365.
port	The port used for IMAP communication. While port 143 is the standard for unencrypted or STARTTLS connections, the specific port depends on the server environment.
connectionSecurity	Defines the encryption method. This must match the server configuration and can be set to Off, TLS, or SSL.
authenticationType	Specifies the authentication method, supporting either BASIC or OAUTH2.

OAuth2 Authentication

Selecting OAUTH2 as the authentication type adds several specific properties to the configuration sheet.

Figure: Additional configuration fields for OAuth2 authentication.

For integration with Microsoft Azure AD or similar identity providers, refer to the provider's specific documentation to configure the required application roles. The technical user must have the necessary permissions to read, modify, and delete emails within the associated mailbox.

The scope property is typically set to /.default to utilize the static consent system. This is necessary because the Mailbridge operates as a technical background process and cannot provide dynamic user consent during runtime. This configuration ensures that the required permissions are granted once by an administrator.

---

Project-wide Mailbridge Preferences

Global settings for the Mailbridge are managed within the project preferences. Open the preferences node in the project tree and navigate to the _PREFERENCES_PROJECT data model, then select the Email section (under the Modules node).

Figure: Project-wide email and mailbridge preferences.

Mailbridge Configuration Details

The mailBridgeMailserver property defines the active mail bridges and their behavior through a dedicated configuration dialog.

Figure: Dialog for managing multiple mailbridge instances.

The configuration options within this dialog include the following parameters:

• Active: This checkbox determines whether the specific mailbridge instance is currently operational.
• Name: A freely definable identifier used to distinguish between different mailbridge configurations.
• Server: The alias of the mailserver that this mailbridge instance will monitor.
• User: The login name of an ADITO user whose credentials and email settings are used for server authentication.
• Bridge mode: Defines the processing logic. Process only executes the assigned logic, Copy only archives the email to the repository, and Both performs both actions.
• Flag mode: Determines which emails are retrieved based on their status, such as New, Read, Unread, or All.
• Process: Specifies the project process to be executed for each email when the bridge mode includes processing.
• Error process: Defines a fallback process that is triggered if an error occurs, such as when email attachments exceed size limits.
• Interval (ms): The frequency of the mailbridge execution cycles. Values can be specified in milliseconds or using suffixes like S (seconds), M (minutes), or H (hours).
• Timeout (ms): The maximum duration the system attempts to read from the mailbox before terminating the attempt.
• Attachment policy: Controls how attachments are handled. ALL processes all attachments within size limits , THRESHOLD replaces attachments exceeding the limit with empty files, and NONE ignores all attachments.
• Maximum size (Byte): Overrides the global mailGlobalMaxSizeRecieve property for this specific mailbridge instance.
• Recieving filter: Additional processing of the email can be performed based on the expression defined here.

info

The maximum size of an email as used in the attachment policy. is set in the mailGlobalMaxSizeRecieve property or in the maximum size column of the mailbridge config.

info

The execution interval should not be set below 5 seconds to prevent performance issues and excessive server load.

The Flag Modes explained

Flag	Meaning
New	Only fetches newly recieved emails, this does not include older unread emails.
Read	Only fetches emails that were read by a user.
Unread	Fetches all unread emails.
All	Fetches all emails in the specified inbox of the mailbridge user.

Available Process Variables

When a process is triggered by the mailbridge, several local variables are provided to handle the email data:

Variable	Description
$local.mail	Contains the complete email object including headers and content.
$local.recipients	Provides an array of all recipient email addresses.
$local.sender	Contains the sender's email address.

In the event of an error, the following variables are available in the error process:

• $local.error: The specific ADITO error code.
• $local.errorid: The unique identifier of the error occurrence.
• $local.errormessage: The descriptive error message.
• $local.mailid: The identifier of the email that caused the error, allowing for manual intervention or separate processing.

Receiving Filters

Value	Description
CRLF	Replaces are line breaks with \r\n. This can be used to ensure correct processing, if emails are read that were created by Linux or Mac OS users, as these operating system either only use \n (Linux) or \r (Mac OS).
Extractattachment	Expects all incoming emails to only have one attachment and then uses the attachment to create the mail object.
Extractattachment2	Expects all incoming emails to only have one attachment that’s encoded in MIME type Message/rfc822. The mailbridge will extract the attachment and form the mail object based on the attachment.
log	Writes the email to the log.
printtext	Writes the email to the console logger.

---

Technical User Configuration

The Mailbridge requires a dedicated ADITO user for authentication against the mail server. This technical user stores the credentials and folder configurations for the specific mailbox.

Each mail server requires a separate technical user, as a single user can only be associated with one set of mailbox credentials. If a suitable user does not exist, create one in the system's user management by switching the system editor to User and selecting Create User.

Figure: Basic property configuration for the technical mailbridge user.

Assign a descriptive title to the user, such as mailbridge_service. To ensure system security, assign the role INTERNAL_TECHNICAL to the user. This role prevents the account from being used for interactive client logins, restricting its use to background technical processes.

Extended Email Properties

Specific mailbox settings are configured in the Extended tab under the Email group.

Figure: Configuration of mailbox-specific attributes.

The following properties must be configured for the technical user:

• mailserverInbox: The name of the folder on the mail server that should be processed as the inbox.
• mailserverOutbox: The name of the outbox folder. While not actively used by the mailbridge for processing, many mail servers require this value for a successful connection.
• mailserverPwd: The password for the mail server account.
• mailserverUser: The login name for the mail server account, often following the format username@domain.com.
• userserverEnabled: This checkbox must be active to enable the email subsystem for this user.

---

Instance and Module Activation

The final configuration step takes place within the instance configuration of the target system. Open the _CONFIGURATION node and navigate to Modules in the Navigator, then locate the Email group.

Figure: Activating the email and mailbridge subsystems at the instance level.

The activation is controlled by the following properties:

• mailGlobalEnabled: This property serves as the master switch for the entire email subsystem. If disabled, all email-related functionality is inactive.
• mailBridgeEnabled: This setting activates the mailbridge service for the specific system instance.
• mailBridgeActiveMailservers: When the mailbridge is enabled, this property allows for the selection of specific mailbridge instances defined in the project preferences. By default, all defined mailbridges are active.

Figure: Selecting specific mailbridge instances for the system instance.

Use the selection dialog to restrict the active mailbridges to those required for the specific system environment.