You are browsing the documentation for iTop 2.7 which is not the current version.

Consider browsing to iTop 3.1 documentation

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:

New Action

The mandatory fields for an email action are:

  • 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: 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.

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
  • Test recipient: email address used instead of To, Cc and Bcc when the status is Being tested
  • Reply to: 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 the from address is used.

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”. (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%'

The query can contain placeholders that refer to the current object for which the notification is being sent. The syntax is :this->attribute.

For example, to send a notification to the person who is the “caller” of a ticket, the To field will contain:

SELECT Person WHERE id= :this->caller_id

The query can contain placeholders that refer to the current contact which has done the action at the origin of the event (might be an issue if the user is not linked to a contact). 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

Since iTop 2.3 this syntax works also: :current_contact->id which is equivalent to :current_contact_id and even in a more generic manner: :current_contact->attribute

If the list returned by the query is empty no email will be sent.

To notify only Persons attached to the Ticket (i.e. all the Persons in the “Contacts” tab) the OQL query to be used as recipients (either To, CC or Bcc) is the following:
  SELECT Person 
  JOIN lnkContactToTicket AS L ON L.contact_id = Person.id 
  WHERE L.ticket_id = :this->id
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
If you don't want to notify Persons with Notification flag set to No, add this criteria to the WHERE
  Person.notify = 'yes'

Message contents and placeholders

Starting with iTop 2.3.0, the message body is now edited using a WYSIWYG HTML Editor.

The “Subject” and “Body” parts can be build dynamically by using placeholders. The syntax to be used for such placeholders is $xxxx$.

The placeholders available for the recipient queries (TO, CC, BCC…) differ from the placeholders available for the message parts (subject, body).

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)$.

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 a new object is created = Trigger (on object creation)
  • When an object is modified = Trigger (on object update)
  • When an object is deleted = Trigger (on object deletion)
  • 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 an object is updated from the iTop portal = Trigger (when updated from the portal)
  • When a given threshold for a Time-To-Resolve (TTR) or a Time-To-Own (TTO) is reached = Trigger (on threshold)

More Trigger can be added by specific extensions such as:

  • Trigger (when log is updated) brought by extension Email Reply
  • Trigger (when updated by mail) brought by extension Ticket Creation from eMails
  • Trigger (when an approval is requested) brought by extension Approval process automation
If you want to trigger a Notification '(on object creation)' limited to Ticket created by email, use origin='mail' in the Trigger Filter.

Once you have selected the type of trigger you get the following form:

Any type of trigger requires you to specify three parameters:

  • Description is left to you to further identify the purpose of this trigger.
  • 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.

Depending on the type of trigger, you will have to define additional parameters:

  • 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)
  • On object update 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 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).

Contexts

Trigger On object update with Contexts = Portal can replace the trigger when updated from the portal and be more specific, by specifying a particular portal and/or particular modified fields

Triggers 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.

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
iTop will add AND u.id=:this→id maybe not as such, but with the exact same result.

Test your Trigger

We strongly encourage you to test triggers and actions before moving them to production, by using the “Being Tested” status on actions.

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.

Notifications tab on ticket

You can also list all sent and failed notifications by using the page “Admin tools” / “Run Queries” and running the query:
SELECT EventNotification
If you are running iTop on a Linux server, make sure that the variable “sendmail_path” value in php.ini. For example:
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/

If you are running iTop on a Windows server, you need to make sure that the php.ini file contains the following lines:
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 sending test page

Email Configuration

iTop supports different methods for sending emails, the choice must be made with the configuration parameter email_transport:

  • If the value 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.
  • If the value is SMTP_OAuth added in iTop 2.7.7 then the SMTP transport with OAuth authentication is used (compatible with Microsoft Azure and Google Gmail), using laminas
When using SMTP_OAuth you must configure OAuth client as well

When using PHP's mail function the language's settings are used. Check the PHP documentation for more information.

When using the SMTP or SMTP_OAuth 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)
Though it seems easier to use the default transport (PHP mail), the drawback is the lack of reporting when it fails. For instance, you may get the error message “No valid recipient for this message.” for a configuration issue. More information in Swift Mailer transports documentation. Therefore, we strongly encourage you to use the SMTP transport, which will return detailed error messages.

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.

If you rely a lot on notifications, note that a direct SMTP connection using the 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.

A Step by Step example

2_7_0/admin/notifications.txt · Last modified: 2022/07/19 10:00 (external edit)
Back to top
Contact us