Skip to main content

Email configuration

Emails are used for internal and external communication involving the users of ConSol CM. ConSol CM fetches emails from one or more accounts to create cases or attach the emails to existing cases. Emails can be sent manually from cases or automatically in specific situations. ConSol CM sends emails from one email account, but the used addresses can be modified.

The settings of the email configuration are saved in system properties.

Emails are used for several purposes in ConSol CM. They can be written in the Web Client by a user or be sent automatically by the system. When the users write emails using the rich text editor of a case, they can select a text template to fill the editor with a text drafted for a certain purpose. By default, the email address of the case's contact is selected as a recipient, this can be changed in the page customization attribute mailToSelection.

Automatic emails are sent in a number of specific situations, e.g. when the assignee of a case is changed or an error occurred. The email text is retrieved from a technical template. In addition, you can define automatic emails which are sent in workflow activities or contact or resource actions. Such emails are usually based on a text template.

Technical definitions:

  • Email account: Information to access a mailbox on an email server, usually consisting of host name, port, username, and password
  • Email address: Identification for sending and receiving emails with an email account. An email account can have several email addresses.
  • Email server: Software to transfer email messages between clients, not part of ConSol CM.

Available settings​

Settings for incoming email accounts​

ConSol CM can retrieve emails from several accounts acting as a regular email client. The accounts for incoming emails are configured in the Accounts tab of the Email configuration page. The configuration is saved in system properties in the module cmas-nimh. The following settings are available:

  • Name: Optional. The name of the account for use in ConSol CM.

    Best practice

    Always use the name to reference the account in email scripts. Do not use the account number, i.e. the number used in the system properties referring to the respective account, because this number can change when you add or remove accounts.

  • Protocol: Mandatory. The protocol used to retrieve emails from the email server. Supported protocols are IMAP, IMAPs, POP3 and POP3s.

    info

    When the secure protocol is used, the corresponding certificate must be stored in the security store of the application server.

  • Host: Mandatory. The host name or IP address of the email server.

  • Port: Optional. The port used to retrieve emails from the email server. It depends on the used protocol. If you do not provide a port, the default port is used (see watermark).

  • Authentication method: Mandatory. Select Basic or OAuth 2.0.

    For basic authentication, you need to provide the following settings:

    • User name: Mandatory. The name of the email account.
    • Password: Mandatory. The password of the email account. See Supported characters for passwords in ConSol CM for details about the allowed characters.

    For OAuth 2.0 authentication, you need to provide the following settings:

    • User name: Mandatory. The name of the principal.
    • Client ID: Mandatory. The application ID from the registration of the ConSol CM application.
    • Client secret: Mandatory. The secret value from the registration of the ConSol CM application.
    • Client authority: Mandatory. The login URL with the tenant ID from the registration of the ConSol CM application, e.g. https://login.microsoftonline.com/1234567890
    • Scope: Mandatory. The scope, e.g. https://outlook.office365.com/.default
    info

    OAuth 2.0 is only supported with the IMAPS protocol.

  • Delete read messages: Optional. Determines whether messages are automatically deleted from the email server after polling. Applicable only for IMAP and IMAPS protocols. POP3 and POP3S protocols always delete read messages. Select Use global configuration to use the default setting from the Settings tab, property mailbox.default.task.delete.read.messages.

  • Debug account: Optional. Determines whether low level email polling information is written to the log files. Select Use global configuration to use the default setting from the Settings tab, property mailbox.{number}.session.mail.debug.

Settings for the outgoing email connection​

ConSol CM can send emails using one account acting as a regular email client. The account for outgoing emails is configured in the Settings tab of the Email configuration page. The configuration is saved in system properties in the module cmas-core-server. The following settings are available:

  • Protocol: Mandatory. The protocol used to send emails. Supported protocols are SMTP and SMTP with STARTTLS (sets mail.smtp.tls.enabled to true).

    info

    When the secure protocol is used, the corresponding certificate must be stored in the security store of the application server.

  • Host: Mandatory. The host name or IP address of the email server.

  • Port: Mandatory. The port used to send emails. It depends on the used protocol. If you do not provide a port, the default port is used (see watermark).

  • Authentication method: Mandatory. Select Basic or OAuth 2.0.

    For basic authentication, you need to provide the following settings:

    • User name: Mandatory. The name of the email account.
    • Password: Mandatory. The password of the email account. See Supported characters for passwords in ConSol CM for details about the allowed characters.

    For OAuth 2.0 authentication, you need to provide the following settings:

    • User name: Mandatory. The name of the principal.
    • Client ID: Mandatory. The application ID from the registration of the ConSol CM application.
    • Client secret: Mandatory. The secret value from the registration of the ConSol CM application.
    • Client authority: Mandatory. The login URL with the tenant ID from the registration of the ConSol CM application, e.g. https://login.microsoftonline.com/1234567890
    • Scope: Mandatory. The scope, e.g. https://outlook.office365.com/.default

  • Timeout for connecting to the SMTP server (in milliseconds): Defines how long ConSol CM waits for connecting to the SMTP server.

  • Timeout for sending an email (in milliseconds): Defines how long ConSol CM waits for an answer from the SMTP server after sending an email.

Global configuration​

The global configuration applies to all email accounts. The following settings are available in the Settings tab of the Email configuration page:

  • Pattern for incoming email subjects: Mandatory. Regular expression which defines the subject of incoming emails, which is required to attach the email to the correct case.
  • Template for outgoing email subjects: Mandatory. Template for the pattern used to create the subject of outgoing emails. The template must match the pattern for incoming email subjects, so that replies to emails sent from the system can be attached to the correct case. This is checked when saving the settings in this tab.
  • Number of retries for fetching emails: Mandatory. Determines the maximum number of retries after an error when fetching emails.
  • Delete read messages: Optional. Determines whether messages are automatically deleted from the email server after polling. Applicable only for IMAP and IMAPS protocols. POP3 and POP3S protocols always delete read messages. Applies to all accounts which do not have the account-specific property set. Property mailbox.default.task.delete.read.messages.
  • Debug accounts: Optional. Determines whether low level email polling information is written to the log files. Applies to all accounts which do not have the account-specific property set. Property mailbox.{number}.session.mail.debug.

Addresses​

ConSol CM includes several system properties to manage the email addresses used for system notifications. The addresses can be managed in the Addresses tab of the Email configuration page, which contains a list of the system properties with a brief description of their usage.

The following system properties are available:

  • cmas-core-security, admin.email: Defines the email address of the ConSol CM administrator. Initially, the value entered during system setup is used.
  • cmweb-server-adapter, mail.from: Defines the global From address (sender) to be used for email communication. The value set here appears as a sender of emails sent from ConSol CM.
  • cmweb-server-adapter, mail.reply.to: Defines the global Reply-to address to be used for email communication. The value set here controls the reply-to header of emails sent from ConSol CM.
  • cmas-nimh-extension, mail.error.from.address: Defines the From address for error notification emails which are sent when the email processing fails.
  • cmas-nimh-extension, mail.error.to.address: Defines the To address for error notification emails which are sent when the email processing fails. If not set, the value of the property admin.email is used.
  • cmas-core-security, password.reset.mail.from: Defines the From address (sender) of emails for resetting the password. If not set, the value of the admin.email property is used instead.
  • cmas-core-server, mail.notification.sender: Defines the From address (sender) for system notification emails which are sent when the assignee of a case is changed. If not set, the value in the :from tag in the notification template is used instead. If this is unset too, the value of the mail.from property is used.
  • cmas-core-server, mail.smtp.envelopesender: Defines the email address used as a sender in SMTP envelope. If not set, the From address of the email is used.
  • cmas-nimh-extension, mail.attachments.validation.info.sender: Defines the From header for error notification emails which are sent to the sender of rejected message when the validation of the attachment type fails. If not set, the email address set in mail.from is used. Only used if mail.attachments.validation.handling is set to reject_email.
  • cmas-workflow-engine, jobExecutor.adminMail: Defines the email address which will be notified about job execution problems (when retry counter is exceeded).
  • cmas-workflow-engine, jobExecutor.mailFrom: Defines the email address which will be set as From header for notifications to the administrator in case of job execution errors.
  • cmas-dwh-server, notification.error.to: Defines the To address for error emails from the DWH.
  • cmas-dwh-server, notification.error.from: Defines the From address for error emails from the DWH.
  • cmas-dwh-server, notification.finished_successfully.to: Defines the To address for emails from the DWH when a transfer finishes successfully.
  • cmas-dwh-server, notification.finished_successfully.from: Defines the From address for emails from the DWH when a transfer finishes successfully.
  • cmas-core-server, task.execution.notification.mail.from: Defines the email address which will be set as From header for notifications to the administrator in case of task execution errors.

Basic tasks​

You can perform the following basic tasks on the Email configuration page:

  • Add an incoming email account: You can add a new account from which ConSol CM should retrieve emails on the Accounts tab. Click the New account button and fill out the connection data, see Settings for incoming email accounts. ConSol CM can fetch emails from several accounts.
  • Modify account-specific settings of an incoming email account: You can modify an incoming email account in the Accounts tab. Click the account and fill out the connection data, see Settings for incoming email accounts. These settings are written into the account-specific system properties.
  • Deactivate an incoming email account: You can deactivate an incoming email account on the Accounts tab by clicking the Deactivate icon in the account details. This interrupts email fetching from the account and sets the system property cmas-nimh, mailbox.{name}.task.enabled to false. You can click the Activate icon to start polling again, i.e. set the property to true.
  • Provide an outgoing email account: You can provide the account for outgoing emails which ConSol CM uses to send emails in the Settings tab. Fill out the required data in the Outgoing email connection section, see Settings for the outgoing email connection. ConSol CM can send emails from one account. Nevertheless, the From and Reply-To addresses can be modified as required, see Addresses.
  • Test the connection to the email accounts: You can test the connection to the email accounts by clicking the Test connection button (in the Accounts tab for an incoming connection and in the Settings tab for an outgoing connection. If the connection fails, the technical error message from the emailing subsystem is shown. If outgoing emails are intercepted on the system because the value of mailSender.testArchive.flavour includes the system's flavour (property system.flavour), a corresponding message is shown when testing the SMTP connection.
Best practice

It is recommended to provide a name for each incoming email account and to use the name in scripts. Do not use the account number, i.e. the number used in the system properties referring to the respective account, because this number can change when you add or remove accounts.

Advanced tasks​

You can perform the following advanced tasks on the Email configuration page:

  • Modify the case subject pattern: You can modify the pattern for incoming email subjects on the Settings tab, see Global configuration. The pattern must match the template for outgoing email subjects, so that replies to emails sent from the system can be attached to the correct case. This is checked when saving the settings in this tab.
  • Modify global settings for incoming email accounts: You can modify global settings which apply to all incoming email accounts in the Global configuration section of the Settings tab, see Global configuration. These settings are written into the default system properties.
  • Review email addresses used for system notifications: In the Addresses tab, you can check which email addresses are configured as recipients (to address), senders (from address) and reply-to addresses for notifications sent by ConSol CM, see Addresses.

Technical background of emailing​

The emailing subsystem is called NIMH. It is executed as a service, see Services. ConSol CM acts towards the email server where it fetches the emails like a regular email client, using POP, POPs, IMAP or IMAPs. You can retrieve emails from one or several mailboxes. One mailbox can have several email addresses. The emails are first stored in the database and then processed by the email scripts, see Email scripts for incoming emails. Emails which cannot be processed are saved in a separate database table. They can be retried on the Failed incoming emails page.

info

ConSol CM can retrieve emails from real mailboxes only. Public folders (e.g. on a Microsoft Exchange Server) are not supported.

ConSol CM sends emails from one email account. Nevertheless, specific From and Reply-To addresses can be set, see Addresses. Outgoing emails are usually processed by an email script before sending, see Email scripts for outgoing emails.