Email scripts

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 TODO Email configuration. When ConSol CM receives an email, it is processed by several scripts.

• NimhIncomingMailRouting.groovy: This is the first script that is executed when one of the configured mailboxes receives an email (see TODO Settings for incoming email accounts). It determines how to handle this email. There are three cases:

  • Email does not belong to any case: The script NimhCreateTicket.groovy is executed and a new case is created.

  • Email belongs to an open case: The script NimhAppendToTicket.groovy is executed and the email is added to the history of the case.

  • Email belongs to a closed case: The script NimhMailToClosedTicket.groovy is executed and a new case is created and linked to the closed case.

    Reopening the case

    If the case which receives the email should be reopened instead of creating a new case, you need to introduce a reopen activity in the workflow and adapt NimhIncomingMailRouting.groovy to reopen the case and call NimhAppendToTicket.groovy.

• NimhCreateTicket.groovy: This script is executed if the email subject does not match the regular expression for appending the email to an existing case. It creates a new case for the incoming email. The following aspects need to be defined in this script:

  • Queue in which the case should be created
  • Values of case fields which should be set automatically during case creation
  • Fields which are used for the name and email address of the persons in the desired contact data model
  • Field which is used for the name of the default company
  • Contact group

  By default, the script searches for a person whose email address matches the From address of the incoming email. If no such person is found, a new person is created in the default company.

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

• NimhAppendToTicket.groovy: This script is executed if the email belongs to an open case. It appends the email to the case history. The assignment of the email to the case is performed by comparing the email subject with the regular expression set in Pattern for incoming email subjects in the Settings tab of the Email configuration page (see TODO Global configuration).

• NimhMailToClosedTicket.groovy: This script is executed if the email belongs to a closed case. It creates a new case for the person and a reference to the closed case.

• NimhErroneousMessageHandling.groovy: This script is executed if the processing of the email fails. If it returns "true", a backup of the email is saved and shown on the Failed incoming emails page. If it returns "false", no (further) processing takes place. You can implement other actions prior to the return statement, e.g. create a case with the failed email as an attachment.

Which scripts do you need to modify?

Usually, you only need to adapt NimhCreateTicket.groovy to your configuration.

Email scripts for outgoing emails

The processing of outgoing emails can be fine-tuned by queue. Each queue can have an email script which is executed for every email written from a case in this queue. This applies to emails which are sent manually by a user and to automatic emails which use the method Mail.useDefaultScript().

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

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

Example script

The default configuration includes an example script for outgoing emails called ChangeOutgoingMail.groovy.

Reply-to addresses

There are four ways to set the Reply-to address:

• 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 case 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 an 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.

Reply-to addresses 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()