Notification
iTop integrates a notification system linked to the life cycle of the objects. This allows administrators to define e-mail notification rules when an object of a given class enters or leaves a specified state, when a new object is created, when an update occurs from the portal or when certain thresholds are reached.
The notification mechanism is divided in two parts:
-
Triggers define when notifications have to be sent. Example: when a ticket reaches the state “assigned”.
-
Actions define what will be done. In the current version of iTop, the only available kind of action consist in sending an email.
For a given trigger you can define several actions to be executed, and their sequence. Also, a given action can be executed by several triggers.
Use the link “Notifications” in the “Admin tools” menu to manage triggers and actions:
-
The “Triggers” tab displays all created triggers.
-
The “Actions” tab displays all Actions
Creating an action
Before creating a useful trigger, at least one action must be defined. Email actions are templates for formatting the messages to be sent, the define the content of the message as well that the subject, sender and recipients.
To create a new action, go to the “Actions” tab and click on “New…”. The following wizard appears:
The mandatory fields for an email action are:
-
Subject: the subject of the message. May contain placeholders.
-
Body: the body of the message. May contain placeholders. By default iTop sends all the messages with the MIME Type text/html for the body of the email, so you may put HTML tags to format the message.
-
From: this field contains a static email address. Note that some mail servers will reject the message if the “from” address is not valid.
The contacts to be notified in the “To”, “Cc”, and “Bcc” are defined by an OQL query. This allows to specifiy mutilple recipients for the notification, like “all the contacts attached to a ticket” or “all the contacts on the impacted site”…. (Refer to Object Query Language Reference for more information about writing OQL queries)
This OQL query must return a list of objects containing an e-mail attribute, namely:
-
Contact
-
Person
-
Team
For instance, to notify all persons whose name starts with John, the To field can contain:
SELECT Person WHERE name LIKE 'John%'
The query can contain placeholders (using the syntax
:this→attribute
) that refer to the current object for
which the notification is being sent. For example, to send a
notification to the person who i sthe “caller” of a ticket, the
To field will contain:
SELECT Person WHERE id= :this->caller_id
If the list returned by the query is empty no mail is sent. By default the importance of the mail is “normal”.
Placeholders
Inside the “Subject” and “Body” of the message, you can refer to
fields of the object that triggered the action. The syntax to be
used for such placeholders is $this->attribute$
.
Where attribute
is the code of the field as defined in
the Data Model.
There are also some specific placeholders:
Placholder | Meaning |
---|---|
$this->name()$ |
The name of the current object |
$this->hyperlink()$ |
The url to access the current object in iTop |
$this->hyperlink(portal)$ |
The url to access the current object in the iTop portal |
$this->html(attribute)$ |
The HTML representation of the value of the attribute |
Comments specific to some types of attributes:
-
Case Log attributes: the syntax
$this->head(attribute)$
returns the text of the latest entry in the case log. -
Link set attributes: the very standard syntax
$this->attribute$
returns a list of names (separated by a new line character, see the note below).
Testing notifications
To test a new action, you can use the status “Being tested” and fill “Test recipient” with a test address. In that case, the notification will be sent to this latter address. Once the notification have been tested, change its status to “In Production” to have notifications flow to their actual recipients.
If you want to de-activate an action, just set its status to “Inactive”.
Creating a trigger
-
When a new object is created
-
When an object enters in a given state
-
When an object leaves a given state
-
When an object is updated from the iTop portal
-
When the given threshold for a Time-To-Resolve (TTR) or a Time-To-Own (TTO) is reached
To create a new trigger, click on “New” in action drop down list for the given category in “Trigger” tab. The following wizard appears:
You have to select which type of trigger you want to create:
-
Trigger (on entering a state)
-
Trigger (on leaving a state)
-
Trigger (on object creation)
-
Trigger (on threshold)
-
Trigger (when updated from the portal)
Once you have selected the type of trigger you get the following form:
For each trigger you have to define the class of object for which this trigger is applicable and additionnal parameters:
-
On entering/leaving a state both require the state. The value to be entered for the “state” is the internal code of the state, as defined in the data model. State codes can be seen in the “Life Cycle” tab of the “Data Model”, section “Transitions”. The value code is the value listed between parentheses.
-
On threshold requires a stop watch and a threshold. The expected value for the stop watch is an attribute code. User Requests and Incident tickets come with two stop watches: tto and ttr. The threshold is a percentage of the goal of the stop watch. With the standard data model you can use 75 or 100.
The “Triggered Actions” tab defines which action(s) will be executed when this trigger fires. Remember that one action can be linked to several triggers, so it's possible to reuse some actions. The “Order” field determines in which order, for a given trigger, the actions are executed (actions are launched in ascending order).
You can use the menu “Application log” where all notifications are tracked to check if a mail was triggered. A detailed log of event describes what happened with a given notification, for an easier troubleshooting.
You can as well see which notification had been sent for a given ticket (User Request, Incident, Change) using the tab “Notifications” in the details of the ticket.
SELECT EventNotification
sendmail_path = "/usr/sbin/sendmail -t -i"
Depending on your actual environment, the configuration may be different. For example it is also possible to use SSMTP as a proxy to the actual mail server, as explained in the following link: http://tombuntu.com/index.php/2008/10/21/sending-email-from-your-system-with-ssmtp/
SMTP = <smtp server> smtp_port = 25
In order to test mail notifications you can use, the “Test Page” (follow the link from the “Notifications” pages) or type:
http://<itop server location>/setup/email.test.php
The test page performs a number of checks on the PHP configuration and allows you to send a plain-text email to the recipient of your choice. This is useful for validating that the PHP configuration of the server is indeed correct for sending e-mails.
Email Configuration
iTop 2.0 supports two methods for sending emails: the built-in
mail
function of PHP or SMTP via the Swift Mailer
library (installed with iTop). The configuration parameter
email_transport
determines which method is used for
sending eMails from iTop. If the value of the
email_transport
parameter is PHPMail
(which is the default value), then the built-in mail()
function is used. If the value is SMTP
then the SMTP
transport of Swift Mailer is used.
When using PHP's mail
function the language's
settings are used. Check the PHP documentation for more information.
When using the SMTP transport, the following parameters can be set in the iTop configuration file:
Configuration parameter | Type | Visible | Description | Default Value |
---|---|---|---|---|
email_transport_smtp.encryption | string | No | tls or ssl (optional) | |
email_transport_smtp.host | string | No | host name or IP address (optional) | localhost |
email_transport_smtp.password | string | No | Authentication password (optional) | |
email_transport_smtp.port | integer | No | port number (optional) | 25 |
email_transport_smtp.username | string | No | Authentication user (optional) |
Notifications and application responsiveness
Sending emails is a relatively slow operation. Depending on your
mail server, sending one email may take several seconds
(establishing the connexion to the server, sending the data, etc…).
When a Ticket is created or updated in iTop, several emails may be
emitted, depending on the notifications configured. This can take a
few seconds to complete. To improve the responsiveness of the
application, the notifications can be sent asynchronously by a
process running in the background on the web server. To activate
the asynchronous sending of notifications, set
'email_asynchronous' ⇒ true,
in the configuration file
and make sure that the background process
is up and running.
SMTP
transport is generally a bit faster than PHP's
built-in mail function (PHPMail
), so it may be worth
the extra configuration effort.