触发器和通知

iTop集成了一个连接到对象生命周期的通知系统。这允许管理员在给定类的对象进入或离开特定状态、创建新对象、门户发生更新或达到某些阈值时，定义邮件通知规则。

通知机制分为两部分：

• 触发器定义了什么时候发送通知。例如：当工单流转到“已分配”状态时。

• 操作定义了触发时要执行的操作。目前, 仅有的一种操作就是外发邮件。

对于一个触发器可以定义多个执行的动作和执行顺序。同时，一个给定的操作可以由多个触发器触发。

使用“管理工具”菜单的“通知”来管理触发器和动作：

• “触发器”选项卡显示所有存在的触发器。

• “操作”选项卡显示所有动作。

创建一个操作

在创建有用的触发器之前，至少必须定义一个操作。邮件操作是格式化发送的消息、定义的消息内容以及主题、发送人和接收人的模板。

要创建一个新操作，进入“操作”选项卡并单击“新建…”。出现以下向导：

邮件操作的必填字段有：

• 主题：消息的主题。可以使用下面描述的占位符动态构建。

• 正文：消息的正文。可以使用下面描述的占位符动态构建。默认情况下，iTop发送MIME格式类型为text/html的所有消息给邮件主体。

• 发件人：这个字段包含静态的邮件地址。注意，一些邮件服务器会拒绝"发件人"地址无效的邮件。

  其他领域：

  描述：标识发送邮件性能或绩效用途的自由文本。在发送邮件消息内未发送。

  状况:

  在生产中：发送邮件发送给通过To，Cc和Bcc查询检索到的人员

  正在测试中：发送邮件发送到测试收件人发送邮件地址

  无效：发送邮件未发送

  测试收件人：测试状况时使用发送邮件地址代替To，Cc和Bcc

  回复：静态发送邮件地址或占位符，例如$ this→team_id→发送邮件$。这是发送邮件消息的标准属性。当发送邮件在其邮件中的发送邮件上进行“答复”时，邮寄工具会自动将其用作要使用的地址。如果省略，则使用发件人地址。

定义收件人

在收件人、抄送人和秘密抄送人中，要被通知的联系人可以通过OQL查询定义。这允许为这个通知指定多个接收人，比如“所有跟这个工单有关的联系人”或者“所有与受影响网站有关的联系人”……（关于OQL查询的写法参考 Object Query Language Reference获取更多信息）。

也就是说，OQL查询必须返回包括email属性的对象列表

• 联系人

• 人员

• 团队

例如，为了通知名字起始为“John”的所有人，接收人字段将填写：

SELECT Person WHERE name LIKE 'John%'

查询可以包含占位符，占位符代表要发送通知的当前对象。this指代要发送的通知的当前对象。语法是：this→attribute。

例如，发送通知给一个工单的“发起人”的那个人，那么收件人字段将填写：

SELECT Person WHERE id= :this->caller_id

查询可以填写当前联系人的占位符，该联系人在事件的最初状态下执行了操作(如果用户没有链接到联系人，则可能会出现问题)。语法是:current_contact->attribute。

例如，当代理亲自触发事件时，不向代理发送通知，那么收件人字段将填写：

SELECT Person WHERE id= :this->agent_id AND id != :current_contact_id

从iTop 2.3开始， :current_contact->id 的语法也可以使用，它等同于current_contact_id ，甚至以更通用的方式 :current_contact->attribute。

如果查询返回为空，将不发送邮件。

通知附属于工单的所有人（好比在“联系人”选项卡的所有人）作为收件人使用的OQL查询如下：

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

  通知附属于工单配置项的所有人，使用：

  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

消息内容和占位符

从iTop 2.3.0开始，消息的正文现在可以使用WYSIWYG HTML编辑器 .

在“主题”和”正文”部分，可以使用占位符动态构建。使用的语法为$xxxx$这样的占位符。

对于收件人查询（收件人，抄送，密送）可用的占位符是和消息部分的可用占位符（主体，正文）是不同的。

有多种类型的占位符：

• $CONSTANT$ 引用称为常量的固定值。

• $this->function()$ 引用在触发操作的对象上下文中执行的内置函数。

• $this->attribute$ 引用触发该操作的对象的属性字段。

• $this->attribute_external_key->attribute$ 引用触发操作的对象的attribute_external_key字段所指向的对象的属性字段。

• $this->representation(attribute)$ 引用触发操作的对象的属性字段的内置表示。例:$ this - > html(name)。

这里查看各种不同的占位符类型

通知测试

为了测试一个操作，你可以使用“测试”和使用测试地址填写“测试收件人”。这种情况下，通知将发送到测试地址中。如果通知测试通过，那么改变它的状态为“生产”，让通知流动到它的实际接收人。

如果你想取消动作，只要把它的状态设置为“停用”。

创建触发器

创建一个新的触发器，在“触发器”选项卡给定的目录下拉菜单中，点击“新建”。出现下面的向导：

需要去选择你想创建的触发器的类型：

• 当新对象被创建的时候 = 触发器 (对象创建时)

• 当对象进入指定状态的时候 = 触发器 (进入指定状态)

• 当对象离开指定状态的时候 = 触发器 (离开指定状态时)

• 当对象通过iTop门户更新的时候 = 触发器 (工单更新时)

• 当解决时间或指派时间达到指定阈值的时候 = 触发器 (基于阈值)

更多的触发器能够通过诸如以下的特定扩展添加：

• 触发器 (日志更新) 通过扩展 Email Reply

• 触发器 (邮件更新) 通过扩展Ticket Creation from eMails

如果您想触发仅限于通过电子邮件创建的工单的通知“(对象创建时)”，请在触发过滤器中使用origin='mail'。

一旦选择了触发器的类型，那么可以得到如下表单：

任何类型的触发器都需要指定三个参数：

• 描述用来进一步标识触发器的用途。

• 类定义此触发器适用的对象的类。

• 过滤器 限制触发器应用的对象.它是一个OQL查询，返回激活触发器的所有对象。留空代表：预期类的所有对象。 

根据触发器的类型，将需要定义附加的参数：

• 进入/离开一个状态时，都需要状态值。对于“状态”来说，输入的值是数据模型中定义的状态的内部代码。状态代码可以在“数据模型”的“生命周期”选项卡的“状态和转换”区域的中看到。状态代码是在括号里面的值。

• 基于阈值需要计时器和阈值。计时器的期望值是一个属性代码。用户请求和事件工单附带两个计时器：tto和ttr。阈值是计时器目标的百分比。使用标准数据模型，可以使用75或100。

“触发器操作”选项卡定义了

“触发器操作”选项卡定义了这个触发器触发时执行的操作。记住，一个操作可以链接到多个触发器，因此一些操作可以复用。“顺序”字段决定了给定触发器触发的操作的执行顺序（操作按照由小到大的顺序执行）。

测试触发器

强烈建议在转移到生产之前使用“测试”状态测试触发器和操作。

对于指定的工单（用户请求，事件，变更），使用在工单详情的选项卡“通知”，可以看到通知已经发送。

你可以使用“管理工具”/“运行查询”页面列出所有已发送和失败的通知，运行查询：
SELECT EventNotification

如果你在Linux上运行iTop，那么要确保在php.ini中的变量“sendmail_path”的值。例如：
sendmail_path = "/usr/sbin/sendmail -t -i"
不同的环境，配置不同。例如：可以使用SSMTP作为真实邮件服务器的代理，像下面的链接中所描述的：http://tombuntu.com/index.php/2008/10/21/sending-email-from-your-system-with-ssmtp/

如果再Window上运行iTop，你需要确保php.ini文件还有下面语句：
SMTP = <smtp server>
smtp_port = 25

为了测试邮件通知，可以使用“测试页面”（在“通知”页面上的链接）或者输入：

http://<itop server location>/setup/email.test.php

这个测试页面执行了PHP配置检查，并且允许发送普通文本邮件到你所选的接收人。对于验证服务器的PHP配置能否正确发送电子邮件是很有用的。

邮件配置

iTop2.0支持两种方式发送邮件：PHP内置的邮件功能或使用Swift Mailer library的SMTP(与iTop一起安装)。配置参数email_transport决定了iTop采用哪种方式发送邮件。如果email_transport的值是PHPMail（默认），那么就采用内置邮件功能。如果是SMTP，就采用Swift Mailer 的SMTP。

如果使用PHP的邮件功能还需要语言设置。从PHP documentation获取更多信息。

使用SMTP传输时，可以在iTop配置文件中设置以下参数：

使用默认配置（PHP邮件）看起来更简单些，缺点是失败后没有报告。例如，对于一个配置问题，你可能得到错误信息“消息没有有效的收件人”。更多信息参考Swift Mailer transports documentation。因此，我们强烈建议使用能返回详细错误信息的SMTP传输。

通知和应用程序响应

发送邮件是相对慢的操作。取决于邮件服务器，发送邮件会花费几秒时间（建立服务器的连接，发送数据，等等）。当一个工单在iTop中创建或更新时，发送几封邮件要取决于你的通知配置。这可能需要几秒钟来完成。为了改善应用程序的响应，可以在Web服务器后台用异步进程发送邮件。激活异步发送通知的方式是，在配置文件里设置 'email_asynchronous' ⇒ true，还要确保后台进程启动和运行。

如果你的通知很多，注意直接使用SMTP要比PHP内置邮件功能（PHPMail）快，所以多一些配置也是值得的。

如果非常依赖于通知，请注意，使用SMTP传输的直接SMTP连接通常比PHP内置的邮件函数(PHPMail)快一些，因此额外的配置工作可能是值得的。

循序渐进的例子

教程：创建第一个通知

原贴链接：https://www.itophub.io/wiki/page?id=2_7_0%3Aadmin%3Anotifications

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:

• 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 all the 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

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.

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.

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

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.

A Step by Step example

Tutorial to create your first notification