How Can We Help?

Email Configuration Integration

 
Email integation is a very important module for the organizations that adopt a Service Desk software, in order to interact with their customers and to improve the collaboration between team members.

Deepser is designed to provide a web platform in order to avoid a large number of email messages and so defining a shared and orderly way to manage a service.
It’s clear, however, that the email notifications to customers (or operators) can be a plus for our service.

In addition to set up a web portal, we can give other communication channels like emails to that users who want the “security” of an email confirmation after their request.

Fundamental entities of the Deepser email integration are:

  • Mailbox: the email addresses managed to send or receive notifications.
  • Events: talking about outgoing emails, an event is used to define when sending a notification.
    It is possible to define an infinite number of events to notify our users.
  • Templates: the templates (subject, body and layout) of the outgoing emails.
  • Messages: the email messages sent or received by the system. This entity it’s not directly visible in the Email module, because every message (and their attachments) are only visibile inside the forms of the entity they are linked to (eg: a message related to an Operation in the module “Service”, or an email sent about an asset of the CMDB).

 
To configure the mailboxes, select the menu System > Tools > Email > Mailbox

 

We can see the grid with all the mailboxes already in the system.
To create a new email integration, click “Add Mailbox”.

 

We can define 2 kind of mailboxes:

  • OUT: used to send notifications to users.
  • IN:used to read emails sent to our support by the users.

 
Note: after having configured a mailbox it is always possible to check the connection clicking the button “check”:

 

 



 

Mailbox Out Configuration

The Mailbox OUT configuration must be done using different entities.
It is necessary, infact, to define an outgoing mailbox, the events that will trigger the email notifications (and the conditions) and the templates of the emails.
We start with the configuration of the mailbox.
Select first of all if it is a mailbox OUT or IN in the field Type. The form of the mailbox changes depending on this field.
The fields to configure the mailbox out are the following:

 

Field Meaning
Name Name of the mailbox. It is a descriptive field used in the system to display the mailbox.
Type IN or OUT (IN to receive emails, OUT to send emails).
Status If “Disabled” the email integrations will not be active.
Display Email The displayed email address. It is not the username. The username is used to access the email, this field is only the displayed email address if our server allows us to use a different email address for the outgoing messages.
Display Name The name displayed in the “From” field of tne emails (eg: Your Service Desk).
Host The address of the mailserver. It depends on your provider or mailserver.
Port Port to connect to the mailserver.
Encryption Encryption of the connection to the mailserver. It depends on your provider or mailserver.
Username User name (usually the email address) to connect to our mailbox.
Password Password to connect to our mailbox.
Protocol Protocol to send emails (SMTP or OWA). It depends on your provider or mailserver.
Prefix It’s the prefix to prepend to the unique field of the record (usually the ID) sent by email.
The Prefix is mainly used in the Subject of the email by the incoming integration (mailbox IN), to tell Deepser if it has to create a new record or to update an existing one.
To give an example, if we are sendind an email for a Service Operation record, we can define that the prefix is “TICKET#”. By doing so, the emails will be sent with the subject “TICKET#ID” (where ID is the unique number of the Service Operation). If the user answers that email must not delete this text, to make Deepser aware of the record the email is referring to.
Allowed Email It tells if emails can be sent only to users registerd in the system or to any email address.
Is Default Outgoing It tells if the email is the default to send notifications.
Deepser lets configure an infinite number of mailboxes, but the system needs to know which is the default one to send notifications.
Every Service Operation record, for example, contains a field called Mailbox ID, that represents the email address to send the notifications for that record. If this field is not filled, then the emails will be sent using the Default Mailbox.
Custom Code Custom PHP code executed after an email has been sent.
It is possible to configure this field to trigger custom events. For example, if we wanted to update a counter of the reinders or update a specific entity of Deepser, we could exploit the customization of this field.

An in-depth discussion about the default mailbox is now necessary.
Deepser, as we said before, sends notifications using the default mailbox. There are some exceptions.

  1. Mailbox ID in the Operation Records: if an Operation record is created by the incoming email integration, Deepser can set for this record an OUT mailbox to send always notifications from that OUT mailbox. For example, if we want to define a specific mailbox to send notifications to a customer, we can use this configuration to send always notifications to that customer from a specific mailbox.
    In the example, we can define a mailbox called support.customer-acme@mycompany.com and tell the system that every email sent to that mailbox will create a Service Operation. We can also define that every record created by that mailbox will also send notifications from that mailbox.
  2. Company Mailbox: we can define a mailbox for every company of Deepser. Every email sent to users of that company will be sent from that specific mailbox.

Obviously, if we don’t define a specific mailbox for records or companies, the default outgoing mailbox will always be used.
If we set a mailbox as the default outgoing, all the other mailboxes will be set as “non-default” by the system. There is only always one and only one default outgoing mailbox.

 



 

Events configuration

Once defined an outgoing mailbox, to trigger notifications it is necessary to configure the events to send emails.
To do that, go to the menu: System > Tools > Email > Event.
Create a new event by clicking on the button “Add Event”.
We will see the form of the event.

 

 
The fields hav ethe following meaning:

 

Field Meaning
Name Name of the event. Used in the select-boxes.
Email Template The email template (layout, subject, body) associated to that email.
Status If “Disabled” the event is not triggered by the system.
Send Attachments If Yes all the attachments of the record that triggers the event will be sent. For example, we can easily send all the file attachments to a user assigned to a Service Operation by email.
Model Entity of Deepser for that we are sending the email.
Event Expression PHP code that represents the condition that triggers the event. This field is mandatory todefine when we want to send the email, based on the changes in the record data. For example, if we want to send an email when a new operation record is created, we need to write the following code:
[php]
if ($this->getModel()->getCurrentVersion()==1)
return true;
[/php]
So, when the record has version equals to 1 (when it is created in the system) an email will be sent.
To PHP code to add the destination addresses of the email.
Cc PHP code to add the Cc of the email.
Bcc PHP code to add the Bcc of the email.
Custom Code PHP custom code run after the email has been sent.

 



 

Event Example

To understand the events, let’s give an example.
We want to send an email to the Requester User when a record of Operations is created.
This is useful to notify the user that his request has been correctly submitted and we are taking care of it.
To do so, define a Template (we will see the details in the next paragraph).
Then, fill in the fields as follow:

Field Value
Name Email to Requester User when opening a new Operation
Email Template (chose a template, see next paragraph)
Send Attachments Yes
Status Enabled
Model DeepService – Operation
Event Expression [php]
if ($this->getModel()->getCurrentVersion()==1)
return true;
[/php]
To [php]
$this->addTo($this->getModel()->getRequesterUser()->getEmail());
[/php]

Doing so, we have completed our event configuration.
When a user submits a request we will send him a new notification.
The same way, we can also configure an Event Expression to send a notification when the assigned user changes:
[php]
if($this->getModel()->dataHasChangedFor(“assigned_username”))
return true;
[/php]
Ed il relativo campo To:
[php]
$this->addTo($this->getModel()->getAssignedUser()->getEmail());
[/php]

 
To complete the configuration of this step, we need to define a template.

 



 

Template Configuration

The template defines the layout and data of the email sent by Deepser.
To define a new Template, go to the menu System > Tools > Email > Templates and click on the button “Add Mail Template”.

 

The fields have the following meaning:

Field Meaning
Code Unique code for the template, useful to insert the template in other templates.
Name The name of the template, it will be displayed in the select-boxes.
Status If Disabled the template cannot be used.
Subject Subject of the email.
Body Phtml code to compose the body of the email.
Styles CSS styles added to the body of the email.

Typically, we define a set of templates and we can inlude the templates inside other templates.
Think about a header and a footer. We define once a header with our company logo and then we include it in all the other templates.

 



 

Example of Template configuration

To configure a template we must write PHTML (PHP e HTML) code in the field Body of the Template.

 
We will report a complete template configuration to send emails to a Requester:

Field Value
Code email_to_requester
Name A name for the template: “Email for a new ticket to the Requester”.
Status Enabled
Subject [php]
Ticket id <?php echo $this->getPrefix().$this->getModel()->getId()?> received
[/php]
Body [php]
<?php $this->includeTemplate(“header”) ?>
<br>&nbsp;<br>
Gentile <?php echo $this->getModel()->getRequesterUser()->getDisplayUsername()?>,
<br>
Ticket ID <b><?php echo $this->getModel()->getId()?></b>
sent to the system.
<br>&nbsp;<br>
<i>Details of your request:</i>
<br>&nbsp;<br>

<div class=”divTable”>
<div class=”divTableBody”>
<div class=”divTableRow”>
<div class=”divTableCell”><i>Title</i></div>
<div class=”divTableCell”><?php echo $this->getModel()->getTitle()?></div>
</div>
<div class=”divTableRow”>
<div class=”divTableCell”><i>Description</i></div>
<div class=”divTableCell”><?php echo $this->getModel()->getDescription()?></div>
</div>
<div class=”divTableRow”>
<div class=”divTableCell”><i>Created at</i></div>
<div class=”divTableCell”><?php echo $this->getModel()->getCreatedAt()?></div>
</div>
<div class=”divTableRow”>
<div class=”divTableCell”><i>Urgency</i></div>
<div class=”divTableCell”><?php
if ($this->getModel()->getUrgencyId()) {
$list = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_URGENCY);
$value = $list->getValue($this->getModel()->getUrgencyId());
echo $value->getValueLabel();
}
?></div>
</div>
</div>
</div>

<br>&nbsp;<br>
Thank you for the collaboration.
<br>&nbsp;<br>
<b><i>Your Support Team</i></b>
<br>&nbsp;<br>
[/php]

Styles Leave blank.

 



 

Email Integration “IN” Configuration

An incoming email integration is fundamental if we want to allow users to send requests to our support using their email and not only the web portal.
The email integration in Deepser is a powerful tool and can be used (as seen in other chapters) to create users, activities, assets of the CMDB, etc.
It is mostly used, however, to create new Operations.
Let’s explore the meaning of the fields of the IN mailbox form:

 

Field Meaning
Name Name of the mailbox. It is the name used in the select-boxes.
Type IN o OUT (IN to receive emails, OUT to send).
Status If “Disabled” the integration will not be considered by the system.
Host Address of the mailserver.
Port Port for the connection to the mailserver.
Encryption Encryption of the connection.
Username User name to read the mailbox (usually it is the email or the Exchange user associated to that mailbox).
Password Password to login to the mailbox.
Protocol Protocol to get the emails (POP3, IMAP or OWA).
Model The field Model represents the entity of Deepser in which to look for a record linked to the received emails.
If we set for example DeepService – Operation the mailbox will create and update records of Operations.
If we set DeepAdmin – User the emails will used to create or update users.
Model Field It is the field of the entity Model where to check if a record already exists.
If we set the ID (field: entity_id), then the check will be done on entity_id (unique ID) of the Operations.
Prefix It’s the prefix we prepend to the Model Field, to search the record.
If we set the Model Field equals entity_id of the Operation, then the email integration verifies the subject of the email: if after the Prefix there’s an ID of a record already in the system.

After the expression Prefix and until the first blank space, the ID of the model will be searched.
Thus, if we set the field Prefix with the value TICKET# and the Model Field with the value entity_id, if we receive an email with subject TICKET#70, then Deepser looks for an Operation with ID 70. If Deepser finds that record, then the record is updated and the rules applyed to update the record are that in the Update Expression field.
If we receive an email with a subject Hey this is a new ticket then Deepser creates a new record, following the rules in the field Create Expression.

Outgoing Mailbox We can teel the system that for every record created using this mailbox we will use the specific outgoing mailbox to send notifications.
Create Expression PHP expression to tell the system which field to set for the new records.
Update Expression PHP expression to tell the system which field to set to update records.
Allowed Email If we can receive email from all emails or only from registerd users. Ignored mails will be deleted.
Spam Expression A PHP expression to identify the SPAM emails. Ignored mails will be deleted.
Cron Expression Cron Expression that defines the frequency of the scan of Deepser. If this expression is not set, this mailbox will not be processed by Deepser.
Processed At Date and time of the last scan of the mailbox.
Custom Code PHP custom code run after the email has been received.
It is possible to configure this field to trigger custom events after the email has been received. For example, if we want to receive a counter of the reminders or to update a specific entity of Deepser after we have received the email, we can customize this field to do that.

 
Important note: based on the settings of your email server, all incoming messages could be deleted after Deepser has processed them. This is the default behaviour of the software with email servers like Exchange, Standard SMTP Servers, etc.
Be very careful when configuring the incoming email integration, do a test and a backup. Remember also that Deepser processes all the emails in the inbox, so if the mailbox is full of messages (eg: the first time we run the integration) a lot of records could be created.
To avoid this situations, not directly caused by Deepser, we advise always to do a test on mailboxes with few messages.

 



 

Configuration of an Email Integration “IN” Example

Now, we will configure an incoming mailbox (IN) to create new Operation records when a new email is received.
Any answer to that mailbox will not create a new record, but will update an existing one.
Configure the IN mailbox fields as follows:

Field Value
Name The name of the mailbox, for example: “INTODEEP Support”
Type IN.
Status Enabled.
Host Insert the address of your mailbox host.
Port The port of your mailserver.
Encryption The encryption of your mailserver connection.
Username Insert the username to read the mailbox, for example: support@mycompany.com
Password Password to connect to your mailbox.
Protocol Insert your protocol configuration (POP3, IMAP o OWA). It depends on the mailserver configuration.
Model DeepService – Operation
Model Field entity_id
Prefix TICKET#
Outgoing Mailbox Leave blank.
Create Expression [php]
$user = Deep::getModel(‘deep_admin/user’)
->loadByEmail($this->getMessage()->getFrom());

$this->getModel()
// title of the Operation = email Subject
->setTitle($this->getMessage()->getSubject())
// description of the Operation = email Body HTML
->setDescription($this->getMessage()->getBodyHtml())
// ID of the Status = New
->setStatus(1)
// Category (create a new category for the emails
// and write here the ID)
->setCategory1(23)
// the Service Type (eg: “Incident”)
->setTypeId(1);

// get the user from the email “From” field
// and set it to the requester of the Operation
if ($user)
$this->getModel()->setRequesterUsername($user->getUsername());

// save the record
$this->getModel()->save();
[/php]

Update Expression [php]
// create a new activity of type Comment
// and save it in the Operation
$id = $this->getModel()->getId();
$activity = Deep::getModel(‘deep_activity/activity’);
$activity->setModelAlias(‘deep_service/operation’);
$activity->setModelId($id);
$activity->setDescription($this->getMessage()->getBodyHtml());
$activity->setType(1);
$activity->save();
// set the status as you wish:
$this->getModel()->setStatus(4);
$this->getModel()->save();
[/php]
Allowed Email Leave empty
Spam Expression Leave Empty
Cron Expression Set the expression to read the mailbox every 5 mins:
[html]
*/5 * * * *
[/html]
Custom Code Leave empty.

With this configuration we are telling Deepser to process a mailbox. Inside the mailbox, every email with Subject not amenable to a record will create a new Operation with: Status = New; Category ID = 23; Title = email subject; Description = email HTML body.
Otherwise, if we receive an email with an existing ID, we will update the record by inserting a new activity of type Comment into the Operation and we will update also the Status of the Operation.
The email integration will run every 5 minutes. The minimum value for the frequency is 1 minute.

 
We have seen how to configure an email integration and how it is possibile in Deepser to use that to get requests from our users/customers.
Email integration is a powerful tool, but we advise always to:

  • Don’t send too many emails: the implementation of the tool has to be as slim as possibile and not too much “invasive”. Furthermore, too many emails can divert users from very important notifications.
  • Provide a single point of contact: it is unuseful to set too many mailboxes to get messages. We can choose to use a mailbox to simplify the communication, but remember always you should prefer the web portal and the collaboration with the Activities (Comments).
Next Lists Configuration
Table of Contents