Open topic with navigation
Scripts of Type E-Mail
Scripts of this type are used for several features. Some of the scripts are part of the default system configuration and have to be modified according to the customer-specific system configuration. You can also add your own scripts.
IMPORTANT INFORMATION
Since ConSol CM version 6.9.4, there are two modes to receive incoming e-mails:
- Mule/ESB - this has also been available in all previous CM versions
- NIMH (New Incoming Mail Handler) - new in version 6.9.4
For all configurations/settings which are valid for both modes, no further notes are added. For all settings which vary depending on the mode, this will be explained in separate (i.e., Mule/ESB- or NIMH-specific) sections.
E-Mail Scripts for the Processing of Incoming E-Mails in Mule/ESB Mail Mode
When an e-mail is received by ConSol CM, it is processed by several scripts, see following figure.
Figure 346: ConSol CM Admin Tool - E-mail scripts (Mule/ESB Mail)
- IncomingMailRouting.groovy
Standard script. This is the first script that is executed when an e-mail arrives. Here, it is decided whether a new ticket has to be created, the e-mail pertains to an existing open ticket (then AppendToTicket.groovy is executed), or if it pertains to a closed ticket (then MailToClosedTicket.groovy is executed). This script does not require any changes to adapt it for a customer-specific environment.
- CreateTicket.groovy
Standard script which is responsible for the creation of a ticket when an e-mail arrives in one of the ConSol CM-configured mailboxes (see section E-Mail for details). If the e-mail subject does not match the regular expression in the e-mail subject for appending the e-mail to an existing ticket, this script is executed. All e-mails which are received by ConSol CM (and have not been assigned to an existing ticket) are processed here, regardless of which mailbox they are collected from. In the script, the default queue for incoming e-mails has to be defined and more values of Custom Fields can be defined (like, e.g., the default priority for e-mail tickets). Or decisions can be made, e.g., determining which queue the new ticket should be created in, depending on the TO-address or other parameters. So usually, this script has to be adapted considerably. Please ask a ConSol CM consultant for support with this task.
- AppendToTicket.groovy
Standard script which is responsible for appending an e-mail to an existing, open ticket. The assignment of the e-mail to the ticket is performed using the comparison between the e-mail subject and the required regular expression. Please see section E-Mail for a detailed explanation of this topic. Usually, no changes are required for this script.
- MailToClosedTicket.groovy
Standard script which is responsible for handling an e-mail when it pertains to a closed ticket. The default system behavior is to create a new ticket for the customer (sender of the e-mail) and to create a reference to the old/closed ticket. Usually, no changes are required in this script.
E-Mail Scripts for the Processing of Incoming E-Mails in NIMH Mode
When an e-mail is received by ConSol CM, it is processed by several scripts, see following figure.
Figure 347: ConSol CM Admin Tool - E-mail scripts (NIMH)
- NimhIncomingMailRouting.groovy
Standard script. This is the first script that is executed when an e-mail comes in. Here, it is decided whether a new ticket has to be created, the e-mail concerns an existing open ticket (then NimhAppendToTicket.groovy is executed), or if it pertains to a closed ticket (then NimhMailToClosedTicket.groovy is executed). This script does not require any changes to adapt it for a customer-specific environment.
- NimhCreateTicket.groovy
Standard script which is responsible for the creation of a ticket when an e-mail has been received in one of the ConSol CM-configured mailboxes (see section E-Mail for details). If the ticket subject does not match the regular expression for appending the e-mail to an existing ticket, this script is executed. All e-mails which are received by ConSol CM (and have not been assigned to an existing ticket) are processed here, regardless of which mailbox they are collected from. In the script, the default queue for incoming e-mails has to be defined and more values of Custom Fields can be defined (like, e.g., the default priority for e-mail tickets). Or decisions can be made, e.g., determining which queue the new ticket should be created in, depending on the TO-address or other parameters. So usually, this script has to be adapted considerably. Please ask a ConSol CM consultant for support with this task.
- NimhAppendToTicket.groovy
Standard script which is responsible for appending an e-mail to an existing, open ticket. The assignment of the e-mail to the ticket is performed using the comparison between the ticket subject and the required regular expression. Please see section E-Mail for a detailed explanation of this topic. Usually, no changes are required for this script.
- NimhMailToClosedTicket.groovy
Standard script which is responsible for handling the e-mail when it pertains to a closed ticket. The default system behavior is to create a new ticket for the customer (sender of the e-mail) and to create a reference to the old/closed ticket. Usually, no changes are required in this script.
Differences between Scripts in Mule/ESB Mail and NIMH
When NIMH is enabled, different Groovy classes have to be used in the e-mail scripts than when using Mule/ESB Mail mode. Please see the mapping in the table below.
|
where required:
import com.consol.cmas.esb.mail.MailContextService
|
where required:
import com.consol.cmas.nimh.extension.MailSupportService
import com.consol.cmas.nimh.common.model.MailHolder
|
|
mailContextService
|
mailSupportService
|
|
msg
with respective methods, example:
mailLog.info("Routing " + msg.getUniqueId())
|
mailHolder
with respective methods, example:
mailLog.info("Routing " + mailHolder.getUid()
|
|
mailLog
|
mailLog
|
|
spring cm services
|
spring cm services
|
|
all places where mailHolder is used
Example: see Example OLD below
|
pipeContext (used as parameter in mailSupportService invocations)
Example: see Example NEW below
|
|
esb endpoints in mail routing script ("target handlers"):
endpoints["esb_mail_mailToClosedTicketEndpoint"]
endpoints["esb_mail_appendToTicketEndpoint"]
endpoints["esb_mail_createTicketEndpoint"]
|
script endpoints in mail routing script ("target handlers"):
endpoints["mailToClosedTicketScript"]
endpoints["appendToTicketScript"]
endpoints["createTicketScript"]
|
Example OLD:
String email = mailContextService.extractMailFromField(msg)
Example NEW:
String email = mailSupportService.extractMailFromField(mailHolder, pipeContext)
The steps you have to perform when you want to switch your ConSol CM system from Mule/ESB Mail mode to NIMH mode are described in section Switching from Mule/ESB Mail to NIMH.
E-Mail Scripts for Outgoing E-Mails
For every queue, an E-mail script can be configured. Please see section Queue Administration for an explanation how to configure this. An e-mail which is written from a ticket in this queue (automatically by the workflow or manually by an engineer) passes through this script before it leaves the ConSol CM system. So in this E-mail script you can change or set queue-specific settings for the outgoing e-mail. A common use case is the setting of a queue-specific REPLY-TO address in order to use team-specific REPLY-TO addresses.
An example of an outgoing E-mail script is the following script which is part of the ConSol CM default application:
- ChangeOutgoingMail.groovy
Standard script that is not used, but serves as a template for outgoing E-mail scripts. You might want to use it to configure queue-specific E-mail scripts.
Within the outgoing E-mail script, the Java object mailEntry is implicitly available as the object mail. You have to set all required attributes for the outgoing e-mail using the mail.setAttribute() or mail.setAttributes() methods.
def queueReplyAddress = "serviceteam@mycompany.com"
// you might also use system properties for the queue-specific e-mail addresses and fetch an
// address using the configurationService!
mail.setAttribute('Reply-to', queueReplyAddress)
Code example 62: E-mail script
Common e-mail attributes are:
- BCC
- From
- Reply-to
- To
- CC
- Subject
For a very detailed description of the e-mail format, please refer to RFC 5322.
When you work with the configuration of the REPLY-TO e-mail address, please note the following technical behavior of ConSol CM and adapt your system accordingly!
The technical background:
There are four potential REPLY-TO addresses which you deal with:
- The REPLY-TO address which is set with the system property mail.reply.to. If it is set, it will be displayed in the Ticket E-Mail Editor in the Web Client. If it is really the effective REPLY-TO address in an e-mail depends on the configuration in the queue-specific outgoing e-mail script. See next item. If the Page Customization attribute showReplyTo for the type mailTemplate is set to false, no REPLY-TO address will be displayed in the Ticket-E-Mail-Editor, but if the property mail.reply.to is set, this address will be used anyway - unless an outgoing mail script sets another address, see next item.
- The REPLY-TO address which is set in a queue-specific outgoing e-mail script. Since the outgoing e-mail script is the last instance which processes an outgoing e-mail, the REPLY-TO address set in this script will always be the effective REPLY-TO address which is used. In case the mail.reply.to property is set, this mail-reply.to-address will not really be used (but it will be displayed in the Ticket E-Mail Editor which might cause some confusion! What that means for your system configuration is explained in the next section).
- The e-mail address which is set in the system property mail.from. If this is set and neither mail.reply.to nor a queue-specific REPLY-TO address is set, most e-mail clients will set the FROM address as REPLY-TO address.
- The e-mail address of the current engineer (the engineer who is logged in to the Web Client). This personal e-mail address is used as REPLY-TO address for e-mails from the Web Client if neither the mail.reply.to property is set nor a queue-specific outgoing e-mail script is configured nor the mail.from property is set.
In the Web Client, in the ticket history, the REPLY-TO address which was really used is always displayed for outgoing e-mails. So even in case there should be a difference between the address which was displayed in the Ticket E-Mail Editor (the mail.reply.to property) and the REPLY-TO address which was really used (the REPLY-TO in the queue-specific outgoing e-mail script), the effective address is displayed. This would be the one from the script in this case.
What we recommend:
A system REPLY-TO address should always be set! You can decide if you
- work with the REPLY-TO address in the queue-specific outgoing e-mail script
or
- use the mail.reply.to system property.
However, since the e-mail communication should take place via ConSol CM and not using personal e-mail addresses, one of the two system settings mentioned above should be used to prevent CM from using personal e-mail addresses as REPLY-TO. The latter would automatically lead to customer e-mails being sent to an engineer's personal e-mail account instead of CM.
What that means for your system configuration:
- The simplest way to set a REPLY-TO address is by using the mail.reply.to system property. It will be displayed in the Ticket E-Mail Editor and will be the effective REPLY-TO address.
- If queue-specific REPLY-TO addresses are required, we recommend to write one outgoing mail script where queue names are mapped to specific REPLY-TO addresses. This can then be extended for BCC, CC or other addresses.
You can combine the mail.reply.to property and queue-specific REPLY-TO addresses: for all queues without a specific outgoing mail script, the mail.reply.to address will be used, for all queues which have a queue-specific outgoing mail script that contains a REPLY-TO address, this will be used.
What that means when you work with workflow scripts which send e-mails:
(A detailed explanation is provided in the ConSol CM Process Designer Manual!)
- Use the object and method configurationService.getValue("cmweb-server-adapter","mail.reply.to") to retrieve the value of the system property and set it as REPLY-TO address in the outgoing e-mail.
- Use the Mail object when the queue-specific script should be used: e.g. mail.useDefaultScript() . This will overwrite the mail.reply.to property!
If neither the system property nor the queue-specific outgoing e-mail script is used, i.e. when the REPLY-TO address is not set, usually the FROM address will be used as REPLY-TO by the e-mail client.
