Mail Triggers
Introduction to Mail Triggers
One of the core functionalities of ConSol CM is its interaction with an email infrastructure. This makes it possible for the engineer to send manual emails and for the system to send automatic emails to customers and to engineers, as required in the respective process step. Obviously, ConSol CM has also to receive emails. This is done by retrieving emails from one or more mailboxes with ConSol CM-owned addresses. For a detailed explanation of all interactions between the mail server and ConSol CM, please refer to the ConSol CM Administrator Manual and the ConSol CM Operations Manual. In the current manual, only the workflow interactions are explained.
Figure 79: ConSol CM Process Designer - Mail trigger
Mail Trigger at a Scope
When an email is received which belongs to an existing ticket, it might be required to register this action and to perform specific actions subsequently. This can be achieved using one or more mail triggers within a workflow.
Usually, there is a difference as how emails to open tickets are treated versus emails to closed tickets. In the default configuration, ConSol CM behaves as follows:
- If the ticket is open, the email will be integrated into the ticket and all attachments of the email will be attached to the ticket. The focus in the following section will be on this use case.
- If the ticket is closed, a new ticket will be opened, and a reference (ticket-ticket relation) of the new ticket to the old ticket will be set. Since this use case is basically the same as creating a new ticket and does not really use email triggers, this case will not be explained in the following section.
For a detailed explanation of the system configuration regarding email processing, please refer to the ConSol CM Administrator Manual, section Scripts of type Email.
Please keep in mind that (in the default configuration, i.e. without modification of the Admin Tool script AppendToTicket.groovy) the only automatic action, which is performed by ConSol CM after having received an email in a specific mailbox, is to attach this email to the ticket with the matching ticket tag in the subject, e.g. Ticket (<TicketNumber>). See also ConSol CM Administrator Manual section Scripts of Type Email.
All other actions, which should be executed when an email has been received, have to be programmed manually in the workflow (and/or in Admin Tool scripts)!
Examples for the use of mail triggers are:
When an email has been received ...
- the engineer of the ticket (the ticket owner) should also get an email as notification.
- the ticket icon (in the Web Client) should be marked by an overlay.
- the ticket should be transferred to an activity where the engineer has to confirm that he/she has read the email.
- the sender and the subject of the email are checked and parsed. If the email is a confirmation or a denial in an approval process, the ticket is managed according to the defined rules and activities in the workflow. That way, the approval can be performed using the email only, no login of the approver in the Web Client is required.
Mail Trigger at an Activity
When a mail trigger is attached to an activity, this activity is only executed when an email is received.
Figure 80: ConSol CM Process Designer - Mail trigger at activity
Adding a Mail Trigger to a Workflow
Adding a Mail Trigger to a Scope
Grab the mail trigger icon in the palette and drop it into the desired scope. It is automatically attached to the top of the scope. You can modify the position afterwards (move it to the left or right in order to improve the layout). Only one mail trigger can be used per scope.
A mail trigger which has been attached to a scope cannot be moved to another scope. In case you would like to attach a mail trigger to another scope, remove the one you have defined and create a new one for the correct scope.
You can draw connections from the trigger to put activities or decision nodes behind it. The first step which is executed after a mail trigger always has to be an automatic activity!
Adding a Mail Trigger to an Activity
In the very rare case that you have to attach a mail trigger to an activity (we do not recommend this!), grab the mail trigger icon in the palette and drop it into the desired activity. It will be attached to the corner of the activity.
A mail trigger which has been attached to an activity cannot be moved to another scope or activity. In case you would like to attach a mail trigger to another scope/activity, remove the one you have defined and create a new one for the correct scope/activity.
Properties of a Mail Trigger
A mail trigger does not have any properties.
Examples for Mail Triggers
Use Case 1: Overlay for Ticket Icon
When an email has been received for a ticket which is currently in the scope, the ticket icon in the Web Client GUI should be marked with the overlay mail.
The mail trigger is attached to the scope and the overlay is attached to the automatic activity which is connected to the trigger. The overlay range is activity.
In this way, the ticket is marked with the overlay when the email has come in. As soon as an engineer has moved the ticket to another activity, the overlay disappears.
Please note that the ticket does not leave its context. All that happens is the attachment of the overlay to the ticket icon. Then the ticket returns to its original position in the workflow. We call this an interrupt. Please read the section Process Logic for a detailed explanation.
Figure 81: ConSol CM Process Designer - Use case 1: Scope with mail trigger
Figure 82: ConSol CM Web Client - Use case 1: Ticket with overlay icon
Use Case 2: Overlay for Ticket Icon and Email Confirmation by Engineer
When an email has been received for a ticket which is currently in the scope, the ticket icon in the Web Client GUI should be marked with the overlay mail. The engineer has to confirm that he/she has read the email. Since the email trigger is attached to the global scope and thus an email can be received during the entire process, the acknowledgment activity can be implemented very well using a scope activity. In this way, the acknowledgment activity (named Set confirmation: email read in our example) is also available during the entire process.
The mail trigger is attached to the scope and the overlay is attached to the adjacent automatic activity. The overlay range is activity. In this way, the ticket is marked with the overlay when the email has come in.
Within the script which follows the mail trigger, a boolean field mail_to_read is set to true. In the workflow, an activity Set confirmation: email read is offered when required. It is only displayed in case the value of the boolean field mail_to_read is true. This is a stronger mechanism to remind the engineer of an incoming email than to use only the overlay. The engineer has to confirm the email by executing the scope activity Set confirmation: email read explicitly. Within this workflow activity, the value of the boolean field mail_to_read is set back to false and the mail overlay is removed. Now the ticket is ready to receive another email and to notify the engineer.
Please note that also in this case the ticket does not leave its context as a consequence of the action which is executed after the email has come in. All that happens is the attachment of the overlay to the ticket icon and the modification of a boolean variable. The ticket returns to its original position in the workflow. So this is also an interrupt. Please read the section Process Logic for a detailed explanation.
Figure 83: ConSol CM Process Designer - Use case 2: Scope with mail trigger
Figure 84: ConSol CM Process Designer - Use case 2: Properties of activity "Email received"
Figure 85: ConSol CM Admin Tool - Use case 2: New boolean field to register email
The script of the activity Email received contains the following script:
ticket.set("serviceDesk_fields.mail_to_read",true)
Figure 86: ConSol CM Process Designer - Use case 2: Activity for email confirmation
Figure 87: ConSol CM Process Designer - Use case 2: Properties of activity "Confirmed: email read!"
The precondition script for the scope activity Set confirmation: email read contains the following script:
return ticket.get("serviceDesk_fields.mail_to_read")
The script for the scope activity Set confirmation: email read contains the following script:
ticket.set("serviceDesk_fields.mail_to_read",false)
def si = ticket.scopeInfo
for (ov in si.getActivatedOverlays().toArray() ) {
if(ov.name.contains("Email_received_overlay")){
si.removeOverlay(ov)
}
}
Code example 9: Removing an overlay, here: the email overlay, variant 1
ticket.set("serviceDesk_fields.mail_to_read",false)
def si = ticket.scopeInfo
def ovs = si.activatedOverlays
ovs.each(){ ov ->
// log.info 'OVERLAY NAME is now ' + ov.name
if (ov.name == " defaultScope/ServiceDeskTicketInProgressScope/Email_received_overlay"){
si.removeOverlay(ov)
}
}
Code example 10: Removing an overlay, here: the email overlay, variant 2
ticket.set("serviceDesk_fields.mail_to_read",false)
def si = ticket.scopeInfo
for (ov in si.getActivatedOverlays().toArray() ) { // use the array to avoid concurrent modification
if (ov.parent.name == "defaultScope/ServiceDeskTicketInProgressScope/Email_received") { // identifier is the name of the parent activity
si.removeOverlay(ov)
}
}
Code example 11: Removing an overlay, here: the email overlay, variant 3
Using variant 1 or 2, you have to find out the name of the overlay first. This is usually done by having it printed out into the server.log file. Using variant 3, you only have to find out the name of the overlay's parent activity, i.e. the activity where the overlay is attached. This can be done rather comfortably with a right mouse click and by copying the name of the element to the clipboard.
Figure 88: ConSol CM Web Client - Use case 2: scope activity "Set confirmation: email read"
Process Logic with Mail Triggers
When an email is received, the mail trigger of the innermost possible scope fires.
Example 1:
The ticket is at position (1) in the Ticket on hold scope. When an email comes in, the mail trigger for this scope fires (2) and, as a consequence, the ticket is moved to another scope (3).
Figure 89: ConSol CM Process Designer - Example 1: Mail trigger of sub-scope active
Example 2:
The ticket is at position (1) in the Work in progress scope. When an email comes in, the mail trigger of the main scope (2) fires (because the Work in progress scope does not have a mail trigger). So the ticket position is not changed (3).
Figure 90: ConSol CM Process Designer - Example 2: Mail trigger of main scope active