Open topic with navigation

E-Mail

This section explains the navigation item E-mail in navigation group E-Mail in the Admin Tool. Furthermore, the e-mail-related system properties and the configuration for e-mail duplication are covered.

Introduction to E-Mails in ConSol CM

Before we explain the administration of e-mail accounts using the ConSol CM Admin Tool, we will give you a short introduction on the subject e-mail with ConSol CM, because this represents a core functionality of the application. ConSol CM can send and receive e-mails.

In this section, the focus is on general mailing with ConSol CM and on the set-up in single server environments. In case you have to configure a CM cluster, please read this section first and proceed to the ConSol CM Set-Up Manual, section E-Mail.

Sending E-Mails from ConSol CM

Manual E-Mails

E-mails can be sent manually by an engineer or automatically by the system. Manual e-mails are sent using the Ticket E-Mail Editor. In most systems, by default, the ticket's main customer is the receiver of the e-mail, but the engineer can select or type any other e-mail address. The system-wide default value can be changed by an administrator using Page Customization, using the attribute mailToSelection in the Page Customization section. Furthermore, the engineer can use e-mail templates and/or quote ticket text. Please see the ConSol CM User Manual for a detailed introduction about working with the Ticket E-Mail Editor.

Figure 305: ConSol CM Web Client - Ticket E-Mail Editor

Automatic E-Mails

Automatic e-mails may be sent by ConSol CM in situations like the following:

1. Initiated by the workflow engine, e.g.,
   
   1. when the engineer to whom the ticket is assigned should be reminded to attend to the ticket.
   2. when customers should receive an automatic confirmation that a ticket has been opened for them.
   3. when customers should receive an automatic confirmation that a ticket of theirs has been closed.
   4. when a supervisor or approver should receive a message that a new case has to be approved.
   In any workflow activity, an e-mail can be sent to any valid e-mail address. Please see the ConSol CM Process Designer Manual for a detailed explanation of the methods to use.
2. Initiated by the system in case of an error or for a success message, e.g.,
   
   1. system error
   2. e-mail error
   3. DWH synchronization (error or success)
      Usually, those e-mails are sent to the ConSol CM administrator. However, for most special error cases a special receiver e-mail address can be configured using system properties. Please see section System Properties for details.
3. Initiated by the ConSol CM system to remind engineers
   1. When an engineer receives a ticket or a ticket is retrieved from the engineer, an e-mail can be sent to this engineer. This can be configured on a per-queue basis, as described in section Queue Administration.

Receiving E-Mails with ConSol CM

The ConSol CM system can fetch e-mails from one or more mailboxes (= e-mail accounts) on one or more mail servers. The mailboxes are configured in the Admin Tool (General E-Mail Configuration (Navigation Item E-Mail)). Please keep in mind that ConSol CM works with mailboxes here. Each of the mailboxes can be reached by at least one e-mail address. In certain cases, one mailbox might be used for more than one e-mail address. This can be significant when writing Scripts of Type E-Mail.

As far as the mail server is concerned, ConSol CM is just a regular e-mail client fetching e-mails using a standard mail protocol: IMAP(S) or POP3(S). Depending on the mail server configuration and on the ConSol CM system property cmas-esb-mail, mail.delete.read (in Mule/ESB mode) resp. cmas-nimh, mailbox.default.task.delete.read.messages (in NIMH mode), the e-mails are deleted from the mailbox on the mail server after ConSol CM has picked them up. The default setting is mails are not deleted after pick-up.

If you do not want ConSol CM to delete e-mails from the mail server, please make sure to monitor the mailbox(es) to avoid a data overflow and server or performance problems.

All incoming e-mails are first stored in an incoming e-mail pool in ConSol CM and are then processed in a chain of e-mail scripts. Please see section Scripts of Type E-Mail for a detailed explanation of those scripts. When an e-mail cannot be processed, the administrator will receive a notification e-mail. The unprocessed e-mail is listed under E-Mail Backups.

There are different possibilities concerning the default system behavior for an incoming e-mail:

• The subject of the e-mail does not contain any ticket number with a valid syntax (i.e., it does not contain the pattern which is defined as regular expression (RegEx) for the ticket subject):
  A new ticket is created.
• The subject of the e-mail does contain a ticket number with a valid syntax (RegEx) and the ticket is still open:
  The e-mail is attached to the existing ticket.
• The subject of the e-mail does contain a ticket number with a valid syntax (RegEx), but the ticket is closed:
  A new ticket is created and a reference to the old ticket is established.

By modifying the e-mail scripts (see section Scripts of Type E-Mail), the default system behavior can be changed. However, this can corrupt core functionalities of the system and should not be done or only done by very experienced ConSol consultants!

E-Mail Configuration Using the Admin Tool

General E-Mail Configuration (Navigation Item E-Mail)

In this navigation item you can set the parameters for the e-mail connection.

Figure 306: ConSol CM Admin Tool - E-mail

Administration

Admin e-mail:

Enter the e-mail address which should receive general messages or warnings from the system. Using the GUI, you can enter one admin e-mail address. Multiple addresses separated by commas are possible, but they have to be entered directly in the navigation item System Properties. Use the system property cmas-core-security, admin.email. The total number of characters (for both GUI and property) must not exceed 72. If there are many recipients, we recommend using a mailing list on the mail server system.

Incoming E-Mail

The configuration of incoming e-mail is divided into two areas:

• Configured accounts:
  Here you can use a pop-up window to add or edit accounts from which e-mails are retrieved. The connection to the mailbox is checked during set-up, so it is not possible to configure an account that cannot be used when the system is in operation (provided the mail server has not changed etc.). The value(s) are saved in the system property cmas-esb-mail, mail.incoming.uri. Please see the e-mail properties section in System Properties for detailed information. Required values are:
  
  • Protocol
    The protocol used to retrieve e-mails from the server. Supported protocols are IMAP4, IMAP4s, POP3, and POP3s. Please keep in mind that ConSol CM behaves like a regular e-mail client. When the secure protocol version is used, the corresponding certificate is required! This has to be stored in the security store of the application server.
  • Server
    The DNS-resolvable name or IP address of the mail server.
  • Port
    The port on the mail server where the mail daemon/service is listening.
  • User name
    The user name of the e-mail account.

  • Password
    The password of the e-mail account.

    Please keep in mind that one e-mail account can have more than one e-mail address. So here, you are dealing with the account name, i.e., with the mailbox. When you edit the Admin Tool script(s) that process the incoming e-mails, it might be required to use the e-mail address. The e-mail address is also required when you configure the REPLY-TO-address, the FROM-address, and queue-specific e-mail addresses! So be sure to use the correct parameter: mailbox or e-mail address!

• Configuration:
  
  • Incoming e-mail subject pattern:
    Describes the elements that the subject of an incoming e-mail has to contain in order to assign this e-mail to a certain ticket. The pattern is defined in form of a regular expression (RegEx).
    Example:.*?Ticket\s+\((\S+)\).* would match every subject line that contains Ticket (<Ticketnumber>).

  • Outgoing e-mail subject template:
    Describes the pattern which is used to create the ticket ID in the subject of an outgoing e-mail. The template should be matchable by the incoming e-mail subject pattern. Via the Edit button on the right you can modify the incoming e-mail subject pattern and outgoing e-mail subject template and verify if they match.
    Example:Ticket (${ticketName}) would match the example RegEx above.

    You can check if the pattern for the incoming e-mail subject pattern and for the outgoing e-mail subject template match by using the Edit button and the editor that is opened. Please make sure that the e-mail subject has been set correctly at all locations, e.g., also in all workflow scripts and Admin Tool scripts!

  • Maximum number of restarts:
    Shows the maximum number of restarts after an error when ConSol CM fetches e-mails. Valid for all mail pollers.
  • Error e-mail address:
    E-mail address to which messages and warnings of the mail sub-system are sent. This is usually the same as the general administrator address.

For the configuration of incoming e-mail you might also want to check the e-mail-related system properties, see System Properties. Particularly, the polling interval (the time interval for fetching e-mails from the mail server, system property cmas-esb-mail, mail.polling.interval) might be of interest.

Outgoing E-Mail

The connection data for outgoing e-mails are set here:

Outgoing e-mail connector

Use the following format:

smtp://<IP address of mail server>:<port>

Example with standard port:

smtp://123.123.123.123:25

Example for SMTP server with authentication:

smtp://test:testpassword@ConSolMailServer2:25

The example above uses the following parameters:

• Protocol: SMTP
• User name: test
• Password: testpassword
• Host/Mailserver: ConSolMailServer2
• Port: 25

Please note: If user name and/or password which have to be provided contain the character '@', the '@' has to be coded as %40.

E-Mail Modes: Mule/ESB Mail or NIMH

Starting with CM version 6.9.4, there are two modules for the retrieval of incoming e-mails:

• Mule/ESB Mail
  Has been available in ConSol CM since version 6.
• NIMH
  The New Incoming Mail Handler, available since version 6.9.4. This will be the only available incoming e-mail module in future ConSol CM versions.

In the current ConSol CM version, you, as an administrator, can decide which module to use: you can run ConSol CM in Mule/ESB mode or in NIMH mode. Mule/ESB and NIMH use different system settings which are stored as system properties. They are explained in the following two sections. The "switch" which changes the incoming e-mail mode is the system property cmas-core-server, nimh.enabled which can be set to true or false.

The sending of e-mails, i.e., the SMTP server configuration is not influenced by the incoming e-mail mode.

E-Mail Configuration Using Mule/ESB Mail

Mule is the internal ESB (Enterprise Service Bus) which is - among other things - used to retrieve incoming e-mails.

When Mule/ESB Mail is enabled, the following mechanisms apply:

• Mule/ESB Mail runs as services, see sections CM Services and ESB Services.
• E-mails are retrieved from the configured mailboxes.
• It is not possible to retrieve e-mails from the file system.
• E-mails which could not be processed are stored in a separate directory (unparsable) in the main ConSol CM data directory and can be re-sent to the ConSol CM system, see section Management of E-Mail Backups with Mule/ESB.
• Mule/ESB Mail system properties have to be set. Please keep in mind that you can set most of the properties using the graphical user interface of the Admin Tool, navigation item E-Mail (see sections above).

The following figure provides an example of Mule/ESB Mail-related system properties. Please also refer to the detailed explanation of Mule/ESB Mail system properties in List of System Properties by Area.

Figure 307: System properties for Mule/ESB Mail

E-Mail Configuration Using NIMH

NIMH, the New Incoming Mail Handler, is a proprietary module of ConSol CM. The following picture provides an overview of all components.

Figure 308: NIMH components

When NIMH is enabled, the following apply:

• NIMH runs as a (single) ConSol CM service, see section CM Services. When NIMH is active, the Mule/ESB Mail services are disabled.
• E-mails from mailboxes on a mail server are retrieved by ConSol CM using the MailBoxPoller.
• E-mails can also be fetched from a data directory using the FileSystemPoller.
• All ConSol CM e-mails are stored in the ConSol CM database (nothing is stored in the file system).
• The MailQueuePoller retrieves the e-mails from the database and forwards them to the core ConSol CM system where the e-mails run through the e-mail script pipeline.
• NIMH uses e-mail scripts very similar to the ones used by Mule/ESB Mail. See section Scripts of Type E-Mail (NIMH).
• E-mails which could not be processed are stored in a separate database table and can be re-sent to the ConSol CM system. See section Management of E-Mail Backups with NIMH.
• NIMH-specific system properties are used (they are added automatically to the system configuration during an update to version 6.9.4 and up):
  
  • General NIMH properties
  • Default mailbox properties which are used when a property is not set as a mailbox-specific property
  • Mailbox-specific properties for each mailbox which has to be retrieved
  • FileSystemPoller properties
  • MailQueuePoller properties

The following figure provides an example of NIMH properties. Please also refer to the detailed explanation of NIMH system properties in List of System Properties by Area).

Figure 309: System properties for NIMH, 1

Figure 310: System properties for NIMH, 2

Switching from Mule/ESB Mail to NIMH

If you want to switch from Mule/ESB ("old") mode to NIMH ("new") incoming mail mode, you have to perform the following steps (please also note the info box Step-by-step guide for a switch from Mule/ESB Mail to NIMH):

• Copy the Admin Tool e-mail scripts to new scripts, naming each new one the same, but with a Nimh prefix. See also section Scripts of Type E-Mail (NIMH).
  
  • AppendToTicket.groovy -> NimhAppendToTicket.groovy
  • CreateTicket.groovy -> NimhCreateTicket.groovy
  • IncomingMailRouting.groovy -> NimhIncomingMailRouting.groovy
  • MailToClosedTicket.groovy -> NimhMailToClosedTicket.groovy
• Adapt the new Admin Tool scripts, see also section Scripts of Type E-Mail, NIMH. There are new Groovy classes which have to be used to replace the old ones.
  • Import required NIMH classes.
  • Change methods according to the table in the sectionScripts of Type E-Mail, NIMH.
  • Change the section in the mailRouting script for target handlers.
  • Check/Set NIMH-specific system properties for mailboxes, see section above and List of System Properties by Area.
  • Set this system property to activate NIMH: cmas-core-server.nimh.enabled = true

For a mapping of ESB Mail system properties to NIMH system properties, please refer to section List of System Properties by Area.

Running NIMH in a Clustered Environment

In a cluster, NIMH can run only on one node. On that node, a system property has to be set: cmas-core-server, nimh.enabled.CLUSTER_NODE_ID = true (for example: cmas-core-server.nimh.enabled.1 = true). This property replaces the general property cmas-core-server.nimh.enabled = true.

On all other nodes, NIMH and Mule (and ESB services) have to be disabled. Furthermore, set the system property cmas-nimh, mailbox.polling.threads.mail.log.enabled = true. Without this setting there is the chance that incoming e-mails may be processed several times by different cluster nodes.

E-Mail Duplication in the ConSol CM Web Client

Please see explanations on the Page Customization page at showCloneOption and appendOrReplaceOnClone.