Sending Emails

Introduction to Sending Emails

The capability of receiving and sending emails is a core feature of ConSol CM. Please read the detailed introduction in the ConSol CM Administrator Manual for information.

In this section we will describe how you can write scripts to send emails from the workflow. This is very useful for use cases like the following:

• You want to send an automatic acknowledgment of receipt to the customer when he/she has opened a ticket.
• You want to inform the engineer and his supervisor when the highest escalation level has been reached.
• You want to inform the customer that a problem has been solved (and how).

Usually, you do not write the text of the email into the script but you work with email templates. So please read the detailed introduction to the ConSol CM Text Template Manager in the ConSol CM Administrator Manual first.

Important Methods

There are different ways of sending emails from ConSol CM workflows. The following list provides an overview of the classes and methods which can be applied and discusses the advantages and disadvantages of each variant. However, please see for yourself, which variant will cover your specific use case the best way.

• Variant 1: Use an Object of Class Mail
• Variant 2: Work with the workflowApi (Singleton of Class WorkflowContextService)
• Variant 3: Use the mailService (Singleton of Class MailService)

Work with the ConSol CM API documentation in order to gain an overview of all methods which are provided by the respective classes!

Variant 1: Use an Object of Class Mail

Here you can define all required parameters for an email (see Example #1 up to Example #3 in the Examples section).

Advantages:

• You can configure the Mail object to use the queue-specific email default script ("outgoing mail script"). This is a script which processes the email before it leaves the CM system. This kind of script can be assigned to a queue (Email script, see section Queue Administration in the ConSol CM Administrator Manual). To use such a script can prove helpful, for example when you want to set a Reply-To address which is not the standard Reply-To address (stored in a system property).

Disadvantages:

• none

Information: 

• In case representation rules are in operation: the email is not sent to the representing engineers automatically.
  • Use Mail setTargetEngineers(List<Engineer> pTargetEngineers) to send the email to the specified engineers
  • Use setHandleRepresentatives(boolean pHandleRepresentatives) to send the email to the engineer and all his representatives.

• You will not find the method send() in the API documentation of the class Mail! This is because the method is not a method of the Mail class, but it is added by a helper class "behind the scenes".

Variant 2: Work with the workflowApi (Singleton of Class WorkflowContextService)

The object workflowAPI provides the method sendEmail() with several different signatures. All those methods return void.

Figure 151: Methods sendEmail() in workflowApi (WorkflowContextServcice)

Advantages:

• There are methods where a list of recipients can be provided directly as method parameter

Disadvantages:

• Can only be used in workflow context (i.e. not in every Admin Tool script, e.g. not in TEF scripts)
• Does not apply the queue-specific email default script ("outgoing mail script"), except for the method which takes a Mail object as parameter: sendEmail(Mail pMail)

Information:

We recommend to use the rather new Mail object instead of working with workflowApi for sending emails unless you have a very special reason to use workflowApi.

Variant 3: Use the mailService (Singleton of Class MailService)

You can also work with the mailService to send emails from a workflow (or an Admin Tool script which is called by a workflow script).

The following methods are available, they all return void.

Figure 152: Methods of the class MailService, they all return void

Advantages:

• You can send emails in an asynchronous way, this requires to work with a MailSendHolder object. See Example #8: Using the MailService to Send an Email in an Asynchronous Mode.
• Provides a rather high-performance way of sending emails, because the mailService is the target for other methods which send emails.
• Can be called from any context within ConSol CM.

Disadvantages:

• Does not offer convenient ways of sending attachments or addressing a list of recipients (you have to implement the loop yourself for the latter case)

Examples

Example #1: Sending an Automatic Acknowledgment of Receipt to the Customer Who Has Opened a Ticket

This script might be placed in one of the first activities of the workflow.

Code example 57: Sending an automatic acknowledgment of receipt to the customer who has opened a ticket, using a Mail object

Example #2: Sending an Email to the Engineer When a Certain Escalation Level Has Been Reached

This script might be placed in an automatic activity which is connected to a time trigger. The time trigger measures the escalation interval. When the deadline has been reached, the trigger fires and the ticket enters the automatic activity.

Code example 58: Sending an email to the engineer when a certain escalation level has been reached, using a Mail object

Example #3: Sending an Email to a Customer Integrating the Queue-Specific Mail Script

This is the same script as shown in the example above, but the queue-specific mail script will be used. For a detailed explanation of this type of script, refer to the ConSol CM Administrator Manual, section Admin Tool Scripts.

As an effect, the outgoing email will pass through the script before it leaves the CM system. Email parameters, like Cc, Bcc, or Reply To can be changed.

Code example 59: Sending an email to a customer integrating the queue-specific mail script, using a Mail object

Example #4: Sending an Email to All Contacts of the Ticket

This will send one email with all customers (that have an email address) as receiver. Please note that this is a simple example which demonstrates the use of a list. The Reply-To address is not set, so answers to the email would not be appended to the ticket.

Code example 60: Sending an email to all contacts of the ticket

Example #5: Sending an Email to Each Contact in a List of All Contacts of the Ticket

This will send one email to every single customer (that has an email address). Please note that this is a simple example which demonstrates the use of a list. The Reply-To address is not set, so answers to the email would not be appended to the ticket.

Example #6: Sending an Email and Inserting it into the Ticket History

The following code shows a script which is called to send a receipt notice to the customer when a tickets for this customer was opened. If the main customer of the ticket is a company, no email is sent, because in the example system, companies do not have email addresses. In the next step, the correct customer field which contains the email address has to be found. The field name can vary between customer groups (with the respective customer model), so this has to be considered. When the email has been sent, this is documented as ticket history entry with the correct entry type.

Code example 61: Admin Tool script for sending a notification of receipt and inserting the email as ticket history entry

Example #7: Working with a Template for the Ticket Name in the Mail Subject

In the previous coding example, the following lines are used: 

This is because the pattern in the email subject guarantees that an incoming email can be assigned to the correct ticket. This means, if you use the coding style shown in the example above, you have to make sure that the pattern you use matches the pattern which has been configured in the Admin Tool, navigation item Email (compare following figure).

Figure 153: Admin Tool: Pattern and template for the email subject

In order to avoid inconsistencies between workflow code and system configuration (Admin Tool), you can also work with the template name which is implicitly available in CM.

Use the following code in the Admin Tool script: 

Note that you have to put a parameter called ticketName in the context for the template to work.

Alternative solution: if you modify the template for the outgoing emails to accept either ticketName or the ticket object (you can then work with ticket.name), you can also work with the regular renderTemplate() method as shown below.

The outgoing email subject template is then:

Ticket (<#if ticketName??>${ticketName}<#elseif ticket??>${ticket.name}</#if>)

and the subject is then: 

def subject = workflowApi.renderTemplate(TICKET_SUBJECT_TEMPLATE_NAME)

Example #8: Using the MailService to Send an Email in an Asynchronous Mode

Here, we show an example of sending a single email. However, the code might be used to improve performance if a great number of emails should be sent in a bulk operation. Then you can really benefit from the asynchronous mechanism. The sending of the emails will not block other processes which are triggered in the same script, for example.

Code example 62: Script for sending an email in an asynchronous mode, please see also alternative code in the following example

Code example 63: Alternative code to switch statement: use a multi-dimensional hashmap for more efficient coding

Writing Emails from Scripts when Engineer Representation Rules Apply

When you write scripts where emails are sent out to engineers and/or customers, you have to take the engineer representation rules into consideration. For detailed explanations of the engineer representation feature, please refer to the ConSol CM Administrator Manual (section Role Administration) and the ConSol CM User Manual (section User Profile).

For emails sent out using scripts, the CM system behavior concerning representation rules depends on the method which is used to send the email.

All of the three methods listed here belong to the java Class Mail.

setTo(String pTo)

Mail.setTo(<email of originalReceivingEngineer>)

This method receives a String object as parameter. This is the email address of the recipient. This method will not (!) send a copy of the original email to representing engineers.

setTargetEngineer(Engineer pTargetEngineer)

Mail.setTargetEngineer(<current engineer of the ticket>)

This method receives an Engineer object as parameter and will send the original email to the engineer's email address (if set) and to the representing engineer who is registered as representation for the original email address. Be careful here - please read the info box above!

setTargetEngineers(List<Engineer> pTargetEngineers)

This method receives a list of Engineer objects as parameter and will send the original email to the email address of each engineer in the list (if email address is set) and to the representing engineers for all of the listed engineers' email addresses. Be careful here - please read the info box above!

All three methods are used in the same way, i.e. you have to use only one of them to set the recipient's address in a script which should send an email. Please see the following example which uses the Mail.setTargetEngineer() method.

Code example 64: Workflow or Admin Tool script used to send an email to an engineer, using the representation feature by using the setTargetEngineer() method