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:

  • 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 the from 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 the from 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”.

If all list returned by the OQL queries are empty no email will be sent.
If the field “Ignore Notify flag” of this action is set to “No”, the condition 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:

The caller in To:
SELECT Person WHERE id= :this->caller_id


In Cc the contacts linked to the Ticket:

SELECT Contact 
JOIN lnkContactToTicket AS L ON L.contact_id = Contact.id 
WHERE L.ticket_id = :this->id


In Bcc the member of the team to which the Ticket is dispatched:

SELECT Person AS P 
JOIN lnkPersonToTeam AS L ON L.person_id=P.id
WHERE L.team_id = :this->team_id

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

Icon to test a query Run Query screen

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
If you don't want to notify Persons with Notification flag set to No, add this criteria to the WHERE
  Person.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.

Since iTop 3.1.0, a Preview tab is available once the Action has been saved. You can use it to check the content of the email and visualize the placeholders. However, be aware that the rendering of the HTML in your browser can be quite different of what will be rendered in email clients.

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)
The last three can be replaced by Trigger (on object update) combined with the context and fields

More 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
iTop will add AND u.id=:this→id maybe not as such, but with the exact same result.
If you want to trigger a notification limited to Ticket created by email, use origin='mail' in the Trigger Filter.

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)

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.

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.

The filter is applied after the object is written into the database, so write your OQL Filter to test the new values after object modification.

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.

For those particular triggers to occur, the iTop cron.php must be running

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

This feature is currently limited to the iTop console

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)

This only applies to Caselog, not working on other text or HTML fields

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'),
To disable completely the OnMention feature, set it this way:
'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.

Current limitation: you have no mean to know in which log you have been mentioned in case the object has multiple logs. So using $this->head_html(public_log)$ in the Body may return something totally unrelated to the mention action if it was done in the private_log of the Ticket for eg.
You could use this mechanism to notify contacts associated to a mentioned Business Process, Application, Server, Change, FAQ,…

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
Be cautious with $xxx->data$ and $xxx->data_as_base64$ as their output can be huge.

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 2.0 supports two methods for sending emails: the built-in mail function of PHP or SMTP via a 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, then the built-in mail() function is used. If the value is SMTP then the SMTP transport 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
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. 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.

Since iTop 3.1.0 you can specify your own HTML template for each email notification. This enables rich formatting without the limitations of WYSIWYG HTML Editor

A Step by Step example

latest/admin/notifications.txt · Last modified: 2024/01/04 16:07 (external edit)
Back to top
Contact us