Email configuration

Introduction to emailing in ConSol CM

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.

Concepts, terms and definitions

Concept	Other terms	Definition
email account		Information to access a mailbox on an email server, usually consisting of host name, port, user name, 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.

Purpose and usage

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.

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.

  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.

  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

  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).

  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

• cmweb-server-adapter, mail.from

• cmweb-server-adapter, mail.reply.to

• cmas-nimh-extension, mail.error.from.address

• cmas-nimh-extension, mail.error.to.address

• cmas-core-security, password.reset.mail.from

• cmas-core-server, mail.notification.sender

• cmas-core-server, mail.smtp.envelopesender

• cmas-core-server, task.execution.notification.mail.from

• cmas-nimh-extension, mail.attachments.validation.info.sender

• cmas-workflow-engine, jobExecutor.adminMail

• cmas-workflow-engine, jobExecutor.mailFrom

• cmas-dwh-server, notification.error.to

• cmas-dwh-server, notification.error.from

• cmas-dwh-server, notification.finished_successfully.to

• cmas-dwh-server, notification.finished_successfully.from

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.

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 be 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.

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.