Scripts of Type Email

Scripts of this type are used to configure the email functionalities of ConSol CM. 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.

Email Scripts for Incoming Emails

Incoming emails are processed using NIMH, see Email Configuration Using the Admin Tool. When ConSol CM receives an email, it is processed by several scripts.

Figure 399: Email scripts (NIMH) in ConSol CM

NimhIncomingMailRouting.groovy
This is the first script that is executed when one of the configured mailboxes receives an email (see Email Configuration Using the Admin Tool). It determines how to handle this email. There are three cases:
- The email does not belong to any ticket.
  
  -> The script NimhCreateTicket.groovy is executed and a new ticket is created.
- The email belongs to an open ticket.
  
  -> The script NimhAppendToTicket.groovy is executed and the email is added to the history of the ticket.
- The email belongs to a closed ticket.
  
  -> The script NimhMailToClosedTicket.groovy is executed and a new ticket is created and linked to the closed ticket.
  
  If the ticket which receives the email should be reopened instead of creating a new ticket, you need to introduce a reopen activity in the workflow and adapt NimhIncomingMailRouting.groovy to reopen the ticket and call NimhAppendToTicket.groovy. Please refer to the ConSol CM Process Designer Manual for further details.
Usually, it is not required to adapt this script.
NimhCreateTicket.groovy
This script is executed if the email subject does not match the regular expression for appending the email to an existing ticket. It creates a new ticket for the incoming email. The following aspects need to be defined in this script:
- Queue in which the ticket should be created
- Values of ticket fields which should be set automatically during ticket creation
- Fields which are used for the name and email address of the contacts in the desired customer data model
- Field which is used for the name of the default company
- Customer group
By default, the script searches for a contact whose email address matches the From address of the incoming email. If no such contact is found, a new contact is created in the default company.

You can further adapt the script to fine-tune ticket creation, e.g., create tickets in different queues depending on the To address of the email.

Usually, this script has to be adapted considerably. Please ask a ConSol CM consultant for support with this task.
NimhAppendToTicket.groovy
This script is executed if the email belongs to an open ticket. It appends the email to the ticket history. The assignment of the email to the ticket is performed by comparing the email subject with the regular expression set in Incoming email subject pattern in the Emails section of the Admin Tool (see Email Configuration Using the Admin Tool).

Usually, it is not required to adapt this script.
NimhMailToClosedTicket.groovy
This script is executed if the email belongs to a closed ticket. It creates a new ticket for the contact and a reference to the closed ticket.

Usually, it is not required to adapt this script.

Email Scripts for Outgoing Emails

The processing of outgoing emails can be fine-tuned by queue (see Queues). Each queue can have an email script which is executed for every email written from a ticket in this queue. This applies to emails which are sent automatically by the workflow and to emails which are sent manually by an engineer.

A common use case for outgoing email scripts is to set queue-specific Reply-to or From addresses.

The default configuration includes an example script for outgoing emails:

ChangeOutgoingMail.groovy
Template for outgoing emails 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)

Code example 74: Email script

Common email attributes are:

Bcc
From
Reply-to
To
Cc
Subject

Reply-to addresses in ConSol CM

There are four potential Reply-to addresses which you deal with:

System property mail.reply.to
If this system property is set, its value is displayed in the email editor in the Web Client. The email address can be overwritten by the outgoing email script. If the page customization attribute showReplyTo for the type mailTemplate is set to false, the Reply-To address is not displayed in the email editor, but used anyway.
Queue-specific outgoing email script
If a Reply-to address is set in the outgoing email script, this address is used. It overwrites the system property mail.reply.to, although the address set in this property is displayed in the email editor.
System property mail.from
Only relevant if the Reply-to address is neither set in the system property mail.reply.to nor in the outgoing email script. In this case, most email clients use the From address as Reply-to address.
Email address of the current user
Only relevant if the Reply-to address is neither set in the system properties mail.reply.to or mail.from nor in the outgoing email script. In this case, the personal email address of the currently logged in user is used as Reply-to address for emails from the Web Client.

The Reply-to address which was really used is displayed in the ticket history of the Web Client.

Best practice:

Always set a Reply-to address to prevent personal email addresses from being used, as this would lead to customer emails being sent to the users’ personal email accounts instead of ConSol CM. There are two places to set the Reply-to address:

System property mail.reply.to
This is the simplest way to set the Reply-to address. This address is also displayed in the email editor.
Queue-specific outgoing email script
If different Reply-to addresses are required depending on the queue, 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 system property and queue-specific Reply-to addresses. In this way the email address set in the outgoing email script is used for queues with such a script, and the email address from the system property is used for the rest of the queues.

Usage in workflow scripts

When sending emails in workflow scripts, you need to set the Reply-to address within the script.

Retrieve the value of the system property mail.reply.to and set it as a Reply-to address in the outgoing email:

configurationService.getValue("cmweb-server-adapter","mail.reply.to")
Use the Mail object if the outgoing email script should be used. This overwrites the system property mail.reply.to.

mail.useDefaultScript()

See the ConSol CM Process Designer Manual for a detailed explanation.