Scripts of Type Email
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 emails:
- Mule/ESB - this has also been available in all previous CM versions (This feature is deprecated in CM versions 6.11 and up.)
- 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.
Email Scripts for the Processing of Incoming Emails in Mule/ESB Mail Mode
Please note that Mule/ESB is deprecated in CM versions 6.11 and up!
When an email is received by ConSol CM, it is processed by several scripts, see following figure.
Figure 418: ConSol CM Admin Tool - Email scripts (Mule/ESB Mail)
Please note that the following scripts are part of the Mule/ESB mailing system which is deprecated in ConSol CM version 6.11 and up. Thus, you might find these scripts in systems which have been or have to be updated from a lower version to 6.11, but never in newly installed CM 6.11 systems.
- IncomingMailRouting.groovy
Standard script. This is the first script that is executed when an email arrives. Here, it is decided whether a new ticket has to be created, the email 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 email arrives in one of the ConSol CM-configured mailboxes (see section Email for details). If the email subject does not match the regular expression in the email subject for appending the email to an existing ticket, this script is executed. All emails 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 emails has to be defined and more values of ticket fields can be defined (like, e.g., the default priority for email 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 email to an existing, open ticket. The assignment of the email to the ticket is performed using the comparison between the email subject and the required regular expression. Please see section Email 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 email when it pertains to a closed ticket. The default system behavior is to create a new ticket for the customer (sender of the email) and to create a reference to the old/closed ticket. Usually, no changes are required in this script.
Email Scripts for the Processing of Incoming Emails in NIMH Mode
When an email is received by ConSol CM, it is processed by several scripts, see following figure.
Figure 419: ConSol CM Admin Tool - Email scripts (NIMH)
- NimhIncomingMailRouting.groovy
Standard script. This is the first script that is executed when an email comes in. Here, it is decided whether a new ticket has to be created, the email 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 email has been received in one of the ConSol CM-configured mailboxes (see section Email for details). If the ticket subject does not match the regular expression for appending the email to an existing ticket, this script is executed. All emails 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 emails has to be defined and more values of ticket fields can be defined (like, e.g., the default priority for email tickets). A default company is defined. In case the default company does not exist yet (in a new system), it will be created automatically. In the script, 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 email to an existing, open ticket. The assignment of the email to the ticket is performed using the comparison between the ticket subject and the required regular expression. Please see section Email 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 email when it pertains to a closed ticket. The default system behavior is to create a new ticket for the customer (sender of the email) 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 email scripts than when using Mule/ESB Mail mode. Please see the mapping in the table below.
|
Mule |
NIMH |
|---|---|
|
where required:
|
where required:
|
|
|
|
|
with respective methods, example:
|
with respective methods, example:
|
|
|
|
|
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 pipeContext is an object of class MailPipeContext |
|
|
pipeContext.setAttribute(...)
|
|
esb endpoints in mail routing script ("target handlers"):
|
script endpoints in mail routing script ("target handlers"):
|
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.
Email Scripts for Outgoing Emails
For every queue, an Email script can be configured. Please see section Queue Administration for an explanation how to configure this. An email 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 Email script you can change or set queue-specific settings for the outgoing email. 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 Email 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 Email scripts. You might want to use it to configure queue-specific Email scripts.
Within the outgoing Email script, the Java object mailEntry is implicitly available as the object mail. You have to set all required attributes for the outgoing email using the mail.setAttribute() or mail.setAttributes() methods.
def queueReplyAddress = "serviceteam@mycompany.com"
// you might also use system properties for the queue-specific email addresses and fetch an
// address using the configurationService!
mail.setAttribute('Reply-to', queueReplyAddress)
Common email attributes are:
- Bcc
- From
- Reply-to
- To
- Cc
- Subject
For a very detailed description of the email format, please refer to RFC 5322.
When you work with the configuration of the Reply-To email 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 Email Editor in the Web Client. If it is really the effective Reply-To address in an email depends on the configuration in the queue-specific outgoing email 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-Email-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 email script. Since the outgoing email script is the last instance which processes an outgoing email, 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 Email Editor which might cause some confusion! What that means for your system configuration is explained in the next section).
- The email 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 email clients will set the From address as Reply-To address.
- The email address of the current engineer (the engineer who is logged in to the Web Client). This personal email address is used as Reply-To address for emails from the Web Client if neither the mail.reply.to property is set nor a queue-specific outgoing email 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 emails. So even in case there should be a difference between the address which was displayed in the Ticket Email Editor (the mail.reply.to property) and the Reply-To address which was really used (the Reply-To in the queue-specific outgoing email 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 email script
or
- use the mail.reply.to system property.
However, since the email communication should take place via ConSol CM and not using personal email addresses, one of the two system settings mentioned above should be used to prevent CM from using personal email addresses as Reply-To. The latter would automatically lead to customer emails being sent to an engineer's personal email 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 Email 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 emails:
(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 email.
- 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 email 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 email client.