Notifications
iTop integrates a notification system linked to the life cycle of the objects. This allows administrators to define email 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:
-
Name: an identifier of this action, so you can retrieve it.
-
Subject: the subject of the message. May be built dynamically by using placeholders as described herebelow.
-
Body: the body of the message. May be built dynamically by using placeholders as described herebelow. By default iTop sends all the messages with the MIME Type text/html for the body of the email.
-
From (email): Either a static email address or a placeholder like
$this->agent_id->email$
. Note that some email servers will reject the message if the “from” address is not valid. -
From (label): Either a static label or a placeholder like
$this->agent_id->friendlyname$
.
Of course you must specify at least one of the 3 fields which are used for the mail recipients, either To, Cc or Bcc.
Other fields:
-
Description: free text to identify the purpose of the email action. Not sent within the email message.
-
Status:
-
In production: email are sent to people retrieved by To, Cc and Bcc queries
-
Being tested: email are sent to
Test recipient
email address -
Inactive: email are not sent
-
-
Language: the language to use for the placeholders inserted in the generated email. This impacts mostly the labels of enumerations (like the status of a ticket) and the date and time formats.
-
HTML Template: A file containing an HTML template for wrapping your email in a nice formatting. The uploaded HTML file can contain all the usual placeholders plus a specific one
$content$
which indicates the area where the content of the Body will be inserted. -
Test recipient: email address used instead of To, Cc and Bcc when the status is
Being tested
-
Reply to (email): Either a static email address or a placeholder like
$this->team_id->email$
. This a standard attribute of an email message. It is used automatically by mailing tools as the address to use, when the user does “reply” on the email in his mailer. If omitted thefrom
address is used. -
Reply to (label): Either a static label or a placeholder like
$this->team_id->friendlyname$
. This a standard attribute of an email message. It is used automatically by mailing tools as the label to use, when the user does “reply” on the email in his mailer. If omitted thefrom
label is used. -
Ignore Notify Flag: Whether or not to take into account the Notify flag on Contacts when determining the list of contacts to notify (in each of the To: CC: and Bcc: fields). When this field is set to “Yes”, the list of contacts to notify is exactly what is specifed by the OQL expression. If set to “No” a condition is automatically added to the OQL expression to exclude the Contacts which “Notify flag” is set to “No”.
Defining recipients
The contacts to be notified in the “To”, “Cc”, and “Bcc” are defined by an OQL query. This allows to specify multiple recipients for the notification, like “all the contacts attached to a ticket” or “all the contacts on the impacted site”.
notify =
'yes'
is automatically appended to the OQL.Using predefined queries
The easiest mean to define who will receive those notifications is to retrieve the query using the magnifier icon and select the appropriate query
It copies the corresponding OQL in the field. You can pick up a different predefined query for each field:
You can modify the query, if it's not 100% what you need.
Writing your own query
You can write your own query from scratch and test it: Refer to Object Query Language Reference for more information about writing OQL queries
This OQL query must return a list of objects containing a single email 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%'
To notify all the Persons attached to CIs attached to the
Ticket, uses:
SELECT Person AS P JOIN lnkContactToFunctionalCI AS L1 ON L1.contact_id = P.id JOIN FunctionalCI AS CI ON L1.functionalci_id = CI.id JOIN lnkFunctionalCIToTicket AS L2 ON L2.functionalci_id = CI.id WHERE L2.ticket_id = :this->id
Notification
flag set to No
,
add this criteria to the WHEREPerson.notify = 'yes'
Since iTop 3.1.0 you can achieve the same result by just setting the field Ignore Notify flag to “No” for this action.
Using Placeholders
The query can contain placeholders that refer to
-
the current object for which the notification is being sent. The syntax is :this->attribute.
-
the current contact which has done the action at the origin of the event. The syntax is :current_contact->attribute.
For example, to send a notification to the agent only if he did not triggered the event himself, the To field will contain:
SELECT Person WHERE id= :this->agent_id AND id != :current_contact->id
This syntax works also: :current_contact_id
which is equivalent to
:current_contact->id
Message contents and placeholders
The message body is edited using a WYSIWYG HTML Editor.
Since iTop 3.1.0 you can also upload your own
HTML template for
the email. Both the HTML template and the
Body field can be combined by inserting the
placeholder $content$
in the
HTML template. The
content of the Body field will replace the
$content$
placeholder.
The “Subject” and “Body” parts can be build dynamically by using
placeholders. The syntax to be used for such placeholders is
$xxxx$
.
Placeholders used in … | have different syntaxe | Example |
Recipient queries (TO, CC, BCC…) | in OQL, placeholder starts with : colon | eg. :current_contact->friendlyname |
Message parts (subject, body) | in HTML text, placeholders starts and ends with $ | eg. $current_contact->friendlyname$ |
There are several types of placeholders:
-
$CONSTANT$
refers to a fixed value named constant. -
$this->function()$
refers to a built-in function executed within the context of the object that triggered the action. -
$this->attribute$
refers to the field attribute of the object that triggered the action. -
$this->attribute_external_key->attribute$
refers to the field attribute of the object pointed by attribute_external_key it-self being a field of the object that triggered the action. -
$this->representation(attribute)$
refers to a built-in representation of the field attribute of the object that triggered the action. Ex:$this->html(name)$
. -
The specific placeholder
$content$
can be used only inside the HTML template to indicate where the Body has to be inserted when generating the email.
Check here the details of those various types of placeholders
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
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:
-
When an object enters in a given state = Trigger (on entering a state)
-
When an object leaves a given state = Trigger (on leaving a state)
-
When a new object is created = Trigger (on object creation)
-
When an object is deleted = Trigger (on object deletion)
-
When an object is mentioned in a log = Trigger (on object mention)
-
When an object is modified = Trigger (on object update)
-
When a attachment is downloaded = Trigger (on object's attachment download)
-
When a document is downloaded = Trigger (on object's document download)
-
When a given threshold for a Time-To-Resolve (TTR) or a Time-To-Own (TTO) is reached = Trigger (on threshold)
-
When a Ticket need to be approved = Trigger (when an approval is requested) brought by extension Approval process automation
-
When a log is updated in the Console = Trigger (when log is updated) brought by extension Email Reply
-
When a log is updated by a email = Trigger (when updated by mail) brought by extension Ticket Creation from eMails
-
When an object is updated from the iTop portal = Trigger (when updated from the portal)
Trigger (on object update)
combined with the context
and fieldsMore Triggers can be added by other extensions. For eg.
Notify
On Expiration
& Send updates by email
Once you have selected the type of trigger you get the following form:
Common fields
Any type of trigger requires you to specify three parameters:
-
Description is left to you to further identify the purpose of this trigger.
-
Target class defines the class of object for which this trigger is applicable.
-
Filter restrict the objects to which the trigger applies. It is an OQL query returning all the objects that would activate the trigger. Leaving it blank means: all the objects of the expected class.
Filter
The OQL filter should not make any reference to the current object, it is useless and not working. When the OQL will be executed, iTop will check if the current object is part of the scope.
Example: User Requests requested by a caller, himself part of the team in charge of delivering Tickets on that service subcategory (Be cautious this is a non standard datamodel, also a meaningful one!)
- Non-working example
-
SELECT UserRequest AS u JOIN ServiceSubcategory AS s ON u.servicesubcategory_id = s.id JOIN Team AS t ON s.delivery_team_id = t.id JOIN lnkPersonToTeam AS lnk ON lnk.team_id = t.id WHERE lnk.person_id = :this->caller_id
There is no need to add any condition on the current object.
- better
-
SELECT UserRequest AS u JOIN ServiceSubcategory AS s ON u.servicesubcategory_id = s.id JOIN Team AS t ON s.delivery_team_id = t.id JOIN lnkPersonToTeam AS lnk ON lnk.team_id = t.id WHERE lnk.person_id = u.caller_id
AND
u.id=:this→id
maybe not as such, but with the exact same
result.Contexts
Contexts allow you to specify in which contexts, the trigger should be activated.
-
Warning: some context are not available on Trigger (A specific Datasynchro or a particular CRON Task cannot be specified)
Portal
can replace the trigger
when updated from the portal and be more specific, by
specifying a particular portal and/or particular modified
fieldsTriggers brought by old versions of extensions will not propose Contexts.
-
For on threshold trigger, context is CRON, so make sure to put it, if you defined Contexts.
-
For Email Reply, the Contexts is limited to
Console
by design of the extension. -
For others like “Notify on Expiration” the Contexts is CRON by design of the extension.
Triggered Actions
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).
See the step by step example
Check below for trigger specific parameters and behaviors:
On object update
This trigger proposes to specify the Target fields. Specifying none, means that any field would fire the trigger. Otherwise, at least one of the specified fields need to be changed to activate the trigger.
On entering/leaving a state
Both triggers 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
This trigger 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.
When log is updated
This trigger requires to specify the log code attribute on the Class. then only if a trigger and active action is configured, it adds on the Console only, a checkbox when editing that log, to manually allow the user to disable the notification if he wants.
On mention
This trigger requires to specify the Mentioned filter which is an OQL query specifying the Object (in general the Persons) which can be mention on a particular Target class object. This query can use placeholders to limit the returned Person based on the target class object attributes.
Behavior
Once you have set such Trigger on a class, when editing
a log, if the user enter a special character (@ by default
for Person, it's defined in the Configuration file) followed by a
few characters then iTop searches for Person matching the entered
characters. The returned Person can be limited by existing
Trigger (on mention)
.
-
The Triggers must be applicable to the current object class, so having a Target class being a parent class or the class itself of the edited object.
-
The Mentioned filter on the Trigger must return Person (or Contact or any class in fact)
-
When there is more than one applicable
Trigger (on mention)
, then iTop does a UNION of the various Mentioned filter -
The number of returned Person is limited to the Configuration Parameter
max_autocomplete_results
-
The Triggers applicable, even if they are not linked to an active Email notification, are taken into account to filter the Person
With this mechanism, if you are using iTop as a Service Provider, you can avoid mentioning a customer contact on a Ticket which would be for another unrelated customer.
Of course, the same behavior applies to other classes than Person, if the Configuration file mentions other allowed classes, with their own special character (see below)
Configuration
There is a special Configuration for this trigger, which comes automatically:
- Configuration file
-
// mentions.allowed_classes: Classes which can be mentioned through the autocomplete in the logs. // Key of the array must be a single character that will trigger the autocomplete, // Value must be a DM class (eg. "@" => "Person", "?" => "FAQ") 'mentions.allowed_classes' => array('@' => 'Person'),
'mentions.allowed_classes' => array('@' => 'NonExistingCLassName'), \\
During iTop Setup process, for the each class having a caselog, a Trigger (on mention) is automatically created for this class as Target class.
-
The scope of the trigger is not limited. We consider that the feature to mention someone in a log of that class is available on all objects, but this can be changed.
-
The Mentioned filter is set so it retrieve any active Person of the current user organization. And if the Target class has an
org_id
field, then any active Person belonging to the Organization of the current object is proposed as well.
SELECT Person WHERE ((`status` = 'active') AND ((`org_id` = :current_contact->org_id) OR (`org_id` = :this->org_id)))
and each Trigger is linked to a single created Email notification with:
-
From being the person email who mentioned that Person in a Log, so the current user
-
To should be the Person who was mentioned, which you can get this way:
SELECT Contact WHERE id = :mentioned->id
-
Subject is “You have been mentioned in XXXX”, XXXX being the name of the object in which log you have been mentioned
-
Body of the Email notification is:
- Body
-
Hello $mentioned->first_name$, You have been mentioned by $current_contact->friendlyname$ in $this->hyperlink()$
Note the placeholder $mentioned->attribute$
to
use field from the recipient Person.
As for any message, you can use the standard placeholder (see
below)
Of course, you can customize the Subject and Body, but changing the To is not recommended!
You can also split this generic notification, to create one per trigger using it, so it provides more accurate information about the modification done, for example the last caselog entry.
On document download
The Trigger (on object's document download)
is
activated when someone downloads a file attribute (eg.
File
on the Document File
class) in the
backoffice or the end-user portal.
This trigger gives you access to new placeholders in the actions (of course the standard ones are still available):
-
$file->mime_type$
Mime type of the file (eg. “image/png”) -
$file->file_name$
Name of the file, as uploaded. -
$file->downloads_count$
Number of time the file has been downloaded. Note that it is the count BEFORE the current download, so you can hook some checks to prevent it if a threshold is exceeded. -
$file->data$
Binary content of the file -
$file->data_as_base64$
Base64 encoded content of the file, can be useful for integrations with other apps
On Attachment download
The Trigger (on object's attachment download)
is
activated when someone downloads an attachment in the backoffice or
the end-user portal.
This trigger gives you access to new placeholders in the actions (of course the standard ones are still available):
-
$attachment->xxx$
Same possibilities as for$this->xxx$
but with the attachment itself ($this
being the object it is attached to) -
$attachment->mime_type$
Mime type of the file (eg. “image/png”) -
$attachment->file_name$
Name of the file, as uploaded. -
$attachment->downloads_count$
Number of time the file has been downloaded. Note that it is the count BEFORE the current download, so you can hook some checks to prevent it if a threshold is exceeded. -
$attachment->data$
Binary content of the file -
$attachment->data_as_base64$
Base64 encoded content of the file, can be useful for integrations with other apps
$xxx->data$
and
$xxx->data_as_base64$
as their output can be
huge.Test your Trigger
You can 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 email 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 email 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 emails.
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) | |
email_transport_smtp.verify_peer | bool | No | Verify peer certificate | true |
Notifications and application responsiveness
Sending emails is a relatively slow operation. Depending on your
email 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.Configuring Notification CSS
The is a variable (email_css) in iTop configuration that allows to overload the default CSS used for Email notification. Look at the following tutorial to learn how to personalize your own css.