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:
|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.|
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 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.
- 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 email@example.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.
- 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.
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:
|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:
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.|
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:
|Name||Email to Requester User when opening a new Operation|
|Email Template||(chose a template, see next paragraph)|
|Model||DeepService – Operation|
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:
Ed il relativo campo To:
To complete the configuration of this step, we need to define a template.
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:
|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:
|Name||A name for the template: “Email for a new ticket to the Requester”.|
Ticket id <?php echo $this->getPrefix().$this->getModel()->getId()?> received
<?php $this->includeTemplate(“header”) ?>
Gentile <?php echo $this->getModel()->getRequesterUser()->getDisplayUsername()?>,
Ticket ID <b><?php echo $this->getModel()->getId()?></b>
sent to the system.
<i>Details of your request:</i>
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:
|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).|
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.
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.
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.
|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.|
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:
|Name||The name of the mailbox, for example: “INTODEEP Support”|
|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: firstname.lastname@example.org|
|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|
|Outgoing Mailbox||Leave blank.|
$user = Deep::getModel(‘deep_admin/user’)
// get the user from the email “From” field
// save the record
// create a new activity of type Comment
// and save it in the Operation
$id = $this->getModel()->getId();
$activity = Deep::getModel(‘deep_activity/activity’);
// set the status as you wish:
|Allowed Email||Leave empty|
|Spam Expression||Leave Empty|
|Cron Expression||Set the expression to read the mailbox every 5 mins:
*/5 * * * *
|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).