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. Available actions consist in
  • sending an email,
  • sending an internal News
  • activating a webhook

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 and allow to create a new one.

• The Email actions tab displays
  • Notification by Email,
  • Notification by Email for Request Approval, brought by extension Approval process automation
  • Notification by Email for Unauthenticated Form, brought by extension Follow-up forms (without authentication)
  • Email Notification (text), brought by extension combodo-plain-text-email

• The Webhook actions tab displays
  • Notification by Webhook (generic),
  • Notification by iTop REST API,
  • Notification by Slack,
  • Notification by Rocket.Chat,
  • Notification by Google Chat,
  • Notification by Microsoft Teams

• The Other actions tab displays
  • Notification by News
  • Notification by Calendar Invitation, brought by extension Calendar invitations
  • Notification by SMS, brought by extension sms_notifications

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

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

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.

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

  Person.notify = 'yes'

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

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

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

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

There 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 user in charge of configuring the iTop Notifications, can create new actions Notification by Newsroom, which are pretty much like an Notification by email :

• Title: text information. It is the main information that the user will see. It makes sense to use to the same logic as an email title

A few differences compare to sending an Email:

• Description is not in HTML, it's using a markdown format, so use placeholders which return a text value.
• Priority this defines the order in which the News are displayed to the user, as well as a colored bullet to differentiate them
• Icon: if not set, then the icon of the class which triggered the News is used automatically
• Such action, when triggered, generates one Notification per user (while an Email action generates a single Email Notification)

• Recipients: this must be an OQL query returning Person objects.
• OQL placeholders can be used such as :this->caller_id.
• Despite a Person exists in iTop, no News will be generated if that Persons is not linked to any active User.
• If this active User has no access to iTop back-office, he won't be able to see the News

If a Person is linked to more than one User,

• then all Users will see the News and can manage them, but the News belongs to the Person, so if one User mark them as read, they are read for the other Users, same thing if a User delete a News, it's deleted for all Users of that Person.
• Subscription and unsubscription to channels can be performed by any of the Users, but this applies to all Users linked to that Person.

• In test mode, the News is generated for the Person chosen in the Test recipient regardless if it has an associated User. So if you forget to create the User, for that Person, you can do it after, and the News will still be there.

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)

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:

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.

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

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)

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.

• Triggers can define if users are allowed to unsubscribe from all communication channels, all but one or none
• A trigger such as On Mention should not allow a complete unsubscription as users would not understand that a mention never reached its target

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

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.

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.

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.

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.

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.

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)

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(), \\

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.

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

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

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"

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.

iTop 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:

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.

On an iTop object, which has triggered notifications, you can see them in a dedicated tab.