事件

Jira 是一个事件驱动系统。这意味着，当一个操作发生时（例如，当创建一个问题时），Jira 会触发一个相应的事件。然后，旨在监听该事件的组件会接收该事件。这些组件称为 监听器。当监听器接收到一个事件时，它将执行其职责，例如保持问题的最新更改或向关注问题的用户发送电子邮件。

这种机制允许 Jira 异步处理操作。这种模式的优势在于，发送电子邮件等操作与 Jira 的核心功能（如创建问题）是分离的。例如，如果邮件服务器出现问题，您不会希望这个问题妨碍用户创建问题。

Jira 中有两种类型的事件：

系统事件：这些是 Jira 使用的内部事件，通常代表 Jira 的主要功能。它们不能添加、编辑或删除。
自定义事件：这些事件由用户创建。它们可以添加和删除，并通过工作流发布函数触发。

作为管理员，您将可以获得 Jira 中所有事件的单页视图。您只需执行以下操作：

浏览到 Jira 管理控制台。
选择系统选项卡，然后选择事件选项。这将弹出 查看事件 页面：

Figure 1. Figure 8.7 – Issue events

每个事件都与一个模板相关联，通常称为 邮件模板。这些模板定义了发送通知时电子邮件的内容结构。对于系统事件，您不能更改其模板（但可以更改模板文件的内容）。对于自定义事件，您可以选择使用现有模板或创建自己的邮件模板。

在下面的章节中，我们将了解如何创建和注册自定义邮件模板、创建新的自定义事件以使用新模板，以及在对问题执行操作时触发新事件。之后，我们将了解如何将事件与通知绑定，以便告诉 Jira 谁应该收到该事件的通知邮件。

使用邮件模板

邮件模板是通过文本编辑器创建和编辑的物理文件。Jira 有一套用于所有系统事件的默认模板。Jira 允许您上传自己修改过的模板版本并覆盖默认值，而不是直接修改它们。要创建新的邮件模板，我们也可以参考这些现有模板，并将其作为起点。您可以按照以下步骤下载默认模板：

浏览到 Jira 管理控制台
选择系统选项卡，然后选择 电子邮件模板 选项
单击 Download.zip 按钮

这将下载一个 .zip 文件中的所有默认模板。解压缩后，你会看到两个主要目录—电子邮件和电子邮件批处理。电子邮件目录是我们现在要关注的，因为它包含了活动的所有邮件模板。在电子邮件目录中，您将看到以下子目录：

css 目录：包含用于为电子邮件应用样式的 CSS 文件
html 目录：当 Jira 以 HTML 发送电子邮件时包含模板
includes 目录：包含一个或多个模板之间共享的共同内容
主题目录：包含用于生成电子邮件主题的模板
文本目录：包含 Jira 以纯文本形式发送电子邮件时使用的模板

我们可以看到，对于问题事件使用的特定邮件模板，至少有三个组件—主题、HTML 和文本。因此，如果要为自定义事件添加新模板，就需要创建这三个文件，并将它们相应地放在这些目录中。如果要修改现有的邮件模板，请确保修改了所有必要的文件，通常是 HTML 和文本两个目录中的文件。

创建新的邮件模板时，最好以问题事件命名模板文件，例如 issueescalated.vm。这将有助于未来的用户了解这些模板的用途。

邮件模板使用 Apache 的 Velocity 模板语言（ http://velocity.apache.org ）。因此，创建新的邮件模板需要对 HTML 和模板编程有一定的了解。

如果您的模板只包含静态文本，您只需在模板中使用标准的 HTML 标记即可。但是，如果你需要将动态数据作为模板的一部分，例如问题关键字或摘要，你就需要使用 Velocity 语法。对 Velocity 的全面解释超出了本书的范围。以下段落快速介绍了如何为 Jira 创建简单的邮件模板。关于 Velocity 及其在 Jira 邮件模板中的使用，你可以在 https://confluence.atlassian.com/adminjiraserver0822/customizingemail-content-1142237912.html 。

在 Velocity 模板中，所有文本都将被视为正常文本。任何以美元符号（$）开头的内容，例如 $issue，都是 Velocity 语句。美元符号告诉 Velocity 引用符号后面的项目，如果再加上句号（.），就可以检索指定的值。例如，模板中的以下代码将从当前问题中获取问题关键字和摘要，并用 - 字符分隔：

$issue.key - $issue.summary

这将产生类似于 DEMO-1 - This is a demo issue。

Jira 提供了一系列 Velocity 引用，您可以用它们来创建邮件模板。这些引用允许您访问正在更新的问题和触发事件的用户等数据。您可以在全面的列表，网址是 https://developer.atlassian.com/server/jira/platform/jira-templates-and-jsps/#email-templates 。

现在，你已经对 Velocity 的工作方式有了基本的了解，你需要为邮件主题的模板。以下代码展示了一个典型的主题模板：

$eventTypeName: ($issue.key) $issue.summary

处理模板时，Jira 将用实际值替代事件类型（如创建的问题）、问题关键字和问题摘要。因此，前面的示例将产生类似于 "问题升级" 的内容：HD-11: Database server is running very slow。

然后，您需要为实际电子邮件内容创建一个模板。在此，您需要创建文本和 HTML 版本。下面的代码显示了一个基于文本的模板的简单示例，其中显示了升级问题的关键字：

Hello, The ticket $issue.key has been escalated and is currently being worked on. We will contact you if we require more information. Regards Support team.

在 Jira 发送电子邮件之前，将对前面的文本进行处理，其中所有的 Velocity 引用（如 $issue.key）都将被转换为适当的值；例如，DEMO-1。

一旦更新或创建了邮件模板，就需要将它们上传到 Jira。具体方法如下：

压缩邮件模板
浏览到 Jira 管理控制台
选择系统选项卡，然后选择 邮件模板 选项
单击 Upload.zip 按钮，上传您创建的 .zip 文件
Jira 验证模板内容后，单击应用按钮

更新的模板上传后，最多需要 5 分钟更改才能生效。如果只是修改现有模板，则只需这样做即可，但如果要添加新模板，则需要在 Jira 中注册。

要注册新模板，请在文本编辑器中找到并打开 <JIRA_INSTALL>/atlassian-jira/WEB-INF/classes 目录中的 email-templates-id-mappings.xml 文件。

在关闭 </templatemappings> 标记之前，在文件末尾添加一个新条目，如下所示：

<templatemapping id="10001">
    <name>Example Custom Event</name>
    <template>examplecustomevent.vm</template>
    <templatetype>issueevent</templatetype>
</templatemapping>

在这里，我们注册了一个新的自定义邮件模板条目。其详细信息如下表所示：

Table 1. Table 8.2 – Email template ID mapping parameters
参数	描述
id	这是模板的唯一 ID。您需要确保没有其它模板映射具有相同的 ID。
name	这是 Jira 要显示的人类可读名称。
template	这些是主题、文本和 HTML 的邮件模板文件名。所有三个模板文件都必须按照此处指定的方式命名。
type	这是模板类型。对于从问题生成的事件，该值将为 issuesevent。

创建模板并将其注册到映射文件后，必须重启 Jira 才能接收更改。新模板将在我们创建新事件时可用，我们将在下一节讨论。

添加自定义事件

Jira 自带了一个全面的系统事件列表，主要针对与问题相关的操作。不过，有时您需要创建代表专门业务操作的自定义设计事件，或者仅仅需要使用自定义电子邮件模板。

执行以下步骤添加新的自定义事件：

浏览到 查看事件 页面。
在 添加新事件 部分输入新事件的名称和描述。
为新事件选择邮件模板。如果您已经注册了新的邮件模板，则可以为事件选择该模板。
单击添加按钮创建新事件：

Figure 2. Figure 8.8 – The Add New Event page

这样，我们就在 Jira 中添加了一个新事件，并为其分配了一个自定义电子邮件模板。我们将在下一节了解如何触发新事件。

触发自定义事件

与系统事件不同，对于自定义事件，您需要告诉 Jira 何时可以触发自定义事件。

自定义事件大多由工作流转换触发。回顾 第 7 章工作流和业务流程，您可以为工作流转换添加后置函数。几乎所有的 Jira 过渡都有触发相应事件的后置函数。重要的是要明白，事件被触发并不意味着需要监听它。

如果您跳过了 第 7 章工作流和业务流程，或者仍然对工作流没有很好的理解，那么现在是回去重温这一章的好时机。

执行以下步骤，从工作流程后置函数触发自定义事件：

浏览到 查看工作流程 页面。
单击将用于触发事件的工作流程的编辑链接。
单击执行时将触发事件的过渡。
单击 后置函数 选项卡。
单击后置函数的编辑按钮，该函数显示 Fire a <event name> event that can be processed by the listeners：

Figure 3. Figure 8.9 – Firing an issue event
从下拉列表中选择自定义事件。
单击更新按钮，对后置函数应用任何更改。
发布工作流程。

现在，每当执行工作流程转换时，post 函数就会运行并触发所选事件。在介绍了事件之后，我们将在下一节了解如何配置 Jira 以监听这些事件并发送相应的通知。