通知

基于触发器的自动通知：触发器决定何时发送，操作决定发送什么。

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

通知机制分为两部分：

  • 触发器定义何时必须发送通知。例如：当工单达到"已分配"状态时。
  • 操作定义将做什么。可用的操作包括：发送邮件、发送内部新闻、激活 Webhook。

对于给定的触发器，可以定义多个要执行的操作及其顺序。此外，一个操作可以由多个触发器执行。

管理通知

使用"管理工具"菜单中的"通知"链接来管理触发器和操作：

  • 触发器选项卡显示所有已创建的触发器，并允许创建新触发器。
  • 邮件操作选项卡显示邮件通知、请求审批邮件通知（由扩展 Approval process automation 引入）、未认证表单邮件通知（由扩展 Follow-up forms 引入）、纯文本邮件通知（由扩展 Plain text emails 引入）。
  • Webhook 操作选项卡显示通用 Webhook 通知、iTop REST API 通知、Slack 通知、Rocket.Chat 通知、Google Chat 通知、Microsoft Teams 通知。
  • 其他操作选项卡显示新闻中心通知、日历邀请通知（由扩展 Calendar invitations 引入）、SMS 通知（由扩展 Sms Notifications 引入）。

创建邮件通知

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

要创建新操作，请转到"操作"选项卡并点击"新建…"。

邮件操作的必填字段：

  • 名称：此操作的标识符，以便检索它。
  • 主题：消息的主题。可以使用占位符动态构建，如下所述。
  • 正文：消息的正文。可以使用占位符动态构建。默认情况下，iTop 以 MIME 类型 text/html 发送所有邮件正文。
  • 发件人（邮箱）：静态邮箱地址或占位符，如 $this->agent_id->email$。请注意，某些邮件服务器会在"发件人"地址无效时拒绝消息。
  • 发件人（标签）：静态标签或占位符，如 $this->agent_id->friendlyname$。

必须至少指定以下 3 个用于邮件收件人的字段之一：收件人（To）、抄送（Cc） 或 密送（Bcc）。

其他字段：

  • 描述：用于标识邮件操作目的的自由文本。不随邮件发送。
  • 状态：
    • 生产中：邮件发送给通过 To、Cc 和 Bcc 检索到的人员
    • 测试中：邮件发送给测试收件人邮箱地址
    • 非活跃：不发送邮件
  • 语言：用于生成邮件中插入的占位符的语言。这主要影响枚举的标签（如工单状态）以及日期和时间格式。
  • HTML 模板：包含 HTML 模板的文件，用于将邮件包装在漂亮的格式中。上传的 HTML 文件可以包含所有常用占位符，以及一个特定的 $content$ 占位符，指示 Body 内容应插入的区域。
  • 测试收件人：当状态为测试中时，用于替代 To、Cc 和 Bcc 的邮箱地址
  • 回复至（邮箱）：静态邮箱地址或占位符，如 $this->team_id->email$。这是邮件消息的标准属性。当用户在邮件客户端中执行"回复"时，邮件工具会自动将其用作地址。如果省略，则使用发件人地址。
  • 回复至（标签）：静态标签或占位符，如 $this->team_id->friendlyname$。这是邮件消息的标准属性。当用户在邮件客户端中执行"回复"时，邮件工具会自动将其用作标签。如果省略，则使用发件人标签。
  • 忽略通知标志：是否在确定要通知的联系人列表时考虑联系人上的"通知"标志。当此字段设置为"是"时，要通知的联系人列表完全由 OQL 表达式指定。如果设置为"否"，则会自动向 OQL 表达式添加条件，以排除"通知标志"设置为"否"的联系人。

定义收件人

“收件人”、“抄送"和"密送"中要通知的联系人由 OQL 查询定义。这允许指定多个通知收件人，例如"附加到工单的所有联系人"或"受影响站点上的所有联系人”。

使用预定义查询

定义谁将接收这些通知的最简单方法是使用放大镜图标检索查询并选择适当的查询。

它会将相应的 OQL 复制到字段中。您可以为每个字段选择不同的预定义查询：

场景OQL 示例
收件人（To）中填入工单报告人SELECT Person WHERE id = :this->caller_id
抄送（Cc）中填入关联到工单的联系人SELECT Contact JOIN lnkContactToTicket AS L ON L.contact_id = Contact.id WHERE L.ticket_id = :this->id
密送（Bcc）中填入工单分配到的团队成员SELECT Person AS P JOIN lnkPersonToTeam AS L ON L.person_id=P.id WHERE L.team_id = :this->team_id

可以根据需要修改查询。

编写自己的查询

您可以从头开始编写自己的查询并进行测试：有关编写 OQL 查询的更多信息，请参阅 OQL 文档。

此 OQL 查询必须返回包含单个邮箱属性的对象列表，即：

  • Contact
  • Person
  • Team

例如，要通知所有姓名以 John 开头的人员，收件人字段可以包含：

SELECT Person WHERE name LIKE 'John%'

要通知所有附加到工单所影响 CI 的人员，使用：

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 3.1.0 起，可以通过将该操作的"忽略通知标志"字段设置为"否"来实现相同的结果。

使用占位符

查询可以包含引用以下内容的占位符：

  • 正在发送通知的当前对象。语法为 :this->attribute。
  • 在事件起源处执行操作的当前联系人。语法为 :current_contact->attribute。

例如，仅当代理没有自己触发事件时才向他发送通知，收件人字段将包含：

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

此语法也适用：:current_contact_id，等同于 :current_contact->id。

消息内容和占位符

消息正文使用所见即所得的 HTML 编辑器编辑。

自 iTop 3.1.0 起，您还可以上传自己的 HTML 模板用于邮件。HTML 模板和正文字段可以通过在 HTML 模板中插入 $content$ 占位符来组合。正文字段的内容将替换 $content$ 占位符。

“主题"和"正文"部分可以通过使用占位符动态构建。此类占位符的语法为 $xxxx$。

占位符使用位置语法差异示例
收件人查询（TO、CC、BCC…）在 OQL 中，占位符以冒号开头例如 :current_contact->friendlyname
消息部分（主题、正文）在 HTML 文本中，占位符以 $ 开头和结尾例如 $current_contact->friendlyname$

占位符有几种类型：

  • $CONSTANT$ 指命名常量的固定值。
  • $this->function()$ 指在当前触发操作的对象上下文中执行的内置函数。
  • $this->attribute$ 指触发操作的对象的字段属性。
  • $this->attribute_external_key->attribute$ 指由 attribute_external_key 指向的对象的字段属性，而 attribute_external_key 本身是触发操作的对象的字段。
  • $this->representation(attribute)$ 指触发操作的对象的字段属性的内置表示。例如：$this->html(name)$。
  • 特定的 $content$ 占位符只能在 HTML 模板内使用，以指示在生成邮件时 Body 应插入的位置。

有关这些各种占位符类型的详细信息，请查看占位符文档。

测试通知

要测试新操作，可以使用状态"测试中"并用测试地址填写"测试收件人”。在这种情况下，通知将发送到此测试地址。测试完成后，将状态更改为"生产中"，使通知流向实际收件人。

如果要停用某个操作，只需将其状态设置为"非活跃"。

配置通知 CSS

iTop 配置中有一个变量 email_css，允许重载邮件通知使用的默认 CSS。

创建新闻通知

负责配置 iTop 通知的用户可以创建新的"新闻中心通知"操作，这与"邮件通知"非常相似：

字段差异

  • 标题：文本信息。这是用户将看到的主要信息。使用与邮件标题相同的逻辑是有意义的。
  • 描述：不是 HTML，而是使用 Markdown 格式，因此使用返回文本值的占位符。
  • 优先级：定义新闻向用户显示的顺序，以及用于区分它们的有色圆点。
  • 图标：如果未设置，则自动使用触发该新闻的类的图标。
  • 此类操作触发时，会为每个用户生成一个通知（而邮件操作生成单个邮件通知）。

收件人

  • 收件人：必须是返回 Person 对象的 OQL 查询。
  • 可以使用 OQL 占位符，如 :this->caller_id。
  • 尽管 Person 存在于 iTop 中，但如果该 Person 未链接到任何活动用户，则不会生成新闻。
  • 如果此活动用户无权访问 iTop 后台，则无法看到新闻。

一个 Person 对应多个用户

如果一个 Person 链接到多个用户：

  • 所有用户都会看到新闻并可以管理它们，但新闻属于该 Person，因此如果一个用户将其标记为已读，则对其他用户也是已读；如果一个用户删除新闻，则对该 Person 的所有用户都删除。
  • 订阅和取消订阅频道可以由任何用户执行，但这适用于链接到该 Person 的所有用户。

测试模式

  • 在测试模式下，新闻是为在测试收件人中选择的 Person 生成的，无论其是否有关联用户。因此，如果忘记为该 Person 创建用户，可以在之后创建，新闻仍然会存在。

创建触发器

要创建新触发器，请在"触发器"选项卡中给定类别的操作下拉列表中点击"新建"。

必须选择要创建的触发器类型：

  • 当对象进入给定状态时 = 触发器（进入状态时）
  • 当对象离开给定状态时 = 触发器（离开状态时）
  • 当创建新对象时 = 触发器（对象创建时）
  • 当删除对象时 = 触发器（对象删除时）
  • 当在日志中提及对象时 = 触发器（对象提及时）
  • 当修改对象时 = 触发器（对象更新时）
  • 当下载附件时 = 触发器（对象附件下载时）
  • 当下载文档时 = 触发器（对象文档下载时）
  • 当达到解决时间（TTR）或拥有时间（TTO）的给定阈值时 = 触发器（阈值时）
  • 当工单需要审批时 = 触发器（请求审批时）（由扩展 Approval process automation 引入）
  • 当在控制台中更新日志时 = 触发器（日志更新时）（由扩展 Email Reply 引入）
  • 当通过邮件更新日志时 = 触发器（通过邮件更新时）（由扩展 Ticket Creation from eMails 引入）
  • 当从 iTop 门户更新对象时 = 触发器（从门户更新时）

更多触发器可以由其他扩展添加。例如：Notify On Expiration & Send updates by email。

通用字段

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

  • 描述：留给您进一步标识此触发器的目的。
  • 目标类：定义此触发器适用的对象类。
  • 过滤器：限制触发器适用的对象。它是一个 OQL 查询，返回所有将激活触发器的对象。留空表示：目标类的所有对象。

过滤器

OQL 过滤器不应引用当前对象，这是无用且无效的。执行 OQL 时，iTop 将检查当前对象是否属于范围。

示例：由请求人提交的 User Request，其本身属于负责交付该服务子类别工单团队的成员（注意：这是一个非标准数据模型，但有意义！）

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

无需对当前对象添加任何条件。

上下文

上下文允许您指定触发器应在哪些上下文中激活。

  • 警告：某些上下文在触发器上不可用（无法指定特定的数据同步或特定的 CRON 任务）
  • 旧版本扩展带来的触发器不会提供上下文。
  • 对于阈值触发器，上下文是 CRON，所以如果定义了上下文，请确保包含它。
  • 对于 Email Reply，上下文按扩展设计仅限于 Console。
  • 对于其他如"Notify on Expiration"，上下文按扩展设计是 CRON。

订阅策略

  • 触发器可以定义用户是否允许从所有通信渠道取消订阅、保留至少一个或不允许取消订阅。
  • 例如"On Mention"触发器通常不应允许完全取消订阅，因为用户会不理解为什么提及从未到达其目标。

触发的操作

  • “触发的操作"选项卡定义当此触发器触发时将执行哪些操作。请记住，一个操作可以链接到多个触发器，因此可以重用某些操作。
  • “顺序"字段确定给定触发器的操作执行顺序（操作按升序启动）。

对象更新触发器

此触发器允许指定目标字段。不指定任何字段意味着任何字段更改都会触发触发器。否则，至少有一个指定的字段需要更改才能激活触发器。

进入/离开状态触发器

这两个触发器都需要状态。要输入的"状态"值是数据模型中定义的状态的内部代码。状态代码可以在"数据模型"的"生命周期"选项卡"转换"部分查看。值代码是括号中列出的值。

阈值触发器

此触发器需要一个秒表和一个阈值。秒表的期望值是一个属性代码。User Request 和 Incident 工单带有两个秒表：tto 和 ttr。阈值是秒表目标的百分比。使用标准数据模型时，可以使用 75 或 100。

日志更新时触发器

此触发器需要在类上指定日志代码属性。然后，仅当配置了触发器和活动操作时，它会在控制台中编辑该日志时添加一个复选框，允许用户手动禁用通知（如果他们愿意）。

对象提及时触发器

此触发器需要指定提及过滤器，这是一个 OQL 查询，指定可以在特定目标类对象上提及的对象（通常是 Person）。此查询可以使用占位符根据目标类对象的属性限制返回的 Person。

行为

设置此类触发器后，当编辑日志时，如果用户输入特殊字符（Person 默认为 @，在配置文件中定义）后跟几个字符，则 iTop 会搜索匹配输入字符的 Person。返回的 Person 可以由现有的触发器（对象提及时）限制。

  • 触发器必须适用于当前对象类，因此目标类是编辑对象的父类或类本身。
  • 提及过滤器必须返回 Person（或 Contact 或任何类）
  • 当有多个适用的触发器（对象提及时）时，iTop 会执行各种提及过滤器的并集
  • 返回的 Person 数量受配置参数 max_autocomplete_results 限制
  • 即使未链接到活动邮件通知，适用的触发器也会被考虑用于过滤 Person

使用此机制，如果您将 iTop 用作服务提供商，可以避免在属于另一个不相关客户的工单上提及客户联系人。

当然，相同的行为适用于 Person 以外的其他类，如果配置文件提及其他允许类及其自己的特殊字符。

配置

此触发器有特殊的自动配置：

// mentions.allowed_classes: 可以通过日志中的自动完成提及的类。
// 数组的键必须是触发自动完成的单个字符，
// 值必须是 DM 类（例如 "@" => "Person", "?" => "FAQ"）
'mentions.allowed_classes' => array('@' => 'Person'),

在 iTop Setup 过程中，对于每个具有案例日志的类，会自动为此类创建一个触发器（对象提及时）作为目标类。

  • 触发器的范围不受限制。我们认为在该类的日志中提及某人的功能适用于所有对象，但这可以更改。
  • 提及过滤器设置为检索当前用户组织的任何活动人员。如果目标类有 org_id 字段，则当前对象的组织的任何活动人员也会被提议。
SELECT Person WHERE ((`status` = 'active') 
AND ((`org_id` = :current_contact->org_id) OR (`org_id` = :this->org_id)))

每个触发器都链接到一个创建的邮件通知：

  • 发件人：提及该 Person 的人员的邮箱，即当前用户
  • 收件人：被提及的 Person，可以通过以下方式获取：SELECT Contact WHERE id = :mentioned->id
  • 主题：“You have been mentioned in XXXX”，XXXX 是在其日志中提及您的对象的名称
  • 邮件正文：
Hello $mentioned->first_name$,
You have been mentioned by $current_contact->friendlyname$ in $this->hyperlink()$

注意占位符 $mentioned->attribute$ 用于从收件人 Person 获取字段。对于任何消息，您可以使用标准占位符（见下文）。

当然可以自定义主题和正文，但不建议更改收件人！

您还可以将此通用通知拆分，为使用它的每个触发器创建一个，以便提供更准确的修改信息，例如最后一个案例日志条目。

文档下载时触发器

当有人在后台或最终用户门户中下载文件属性（例如 Document File 类上的 File）时，触发器（对象文档下载时）被激活。

此触发器在操作中提供了新的占位符（标准占位符仍然可用）：

  • $file->mime_type$：文件的 MIME 类型（例如 “image/png”）
  • $file->file_name$：文件名，按上传时的名称。
  • $file->downloads_count$：文件被下载的次数。注意这是当前下载之前的计数，因此如果超过阈值，可以挂钩一些检查来阻止它。
  • $file->data$：文件的二进制内容
  • $file->data_as_base64$：文件的 Base64 编码内容，对于与其他应用集成很有用

附件下载时触发器

当有人在后台或最终用户门户中下载附件时，触发器（对象附件下载时）被激活。

此触发器在操作中提供了新的占位符（标准占位符仍然可用）：

  • $attachment->xxx$：与 $this->xxx$ 相同的可能性，但针对附件本身（$this 是附件所附加到的对象）
  • $attachment->mime_type$：文件的 MIME 类型（例如 “image/png”）
  • $attachment->file_name$：文件名，按上传时的名称。
  • $attachment->downloads_count$：文件被下载的次数。注意这是当前下载之前的计数，因此如果超过阈值，可以挂钩一些检查来阻止它。
  • $attachment->data$：文件的二进制内容
  • $attachment->data_as_base64$：文件的 Base64 编码内容，对于与其他应用集成很有用

测试触发器

您可以在给定工单（User Request、Incident、Change）的详情中的"通知"选项卡中查看已发送的通知。

邮件发送配置

通知与应用响应性

发送邮件是一个相对较慢的操作。根据您的邮件服务器，发送一封邮件可能需要几秒钟（建立连接、发送数据等…）。当在 iTop 中创建或更新工单时，根据配置的通知，可能会发出多封邮件。这可能需要几秒钟才能完成。为了提高应用的响应性，通知可以由在 Web 服务器上运行的后台进程异步发送。要激活通知的异步发送，请在配置文件中设置 'email_asynchronous' => true，并确保后台进程正在运行。

通知与对象

在触发了通知的 iTop 对象上，您可以在专用选项卡中查看它们。

原文：https://www.itophub.io/wiki/page?id=3_2_0:admin:notifications

版本：3_2_0/admin/notifications.txt · Last modified: 2026/03/10 13:16 by 127.0.0.1