[转]Confluence Jira Issues Macro（Jira Issues宏）

本文翻译自官方文档：https://confluence.atlassian.com/pages/viewpage.action?pageId=139380

将Jira Issues宏添加到页面以显示来自Jira的信息。您可以根据JIRA Query Language (JQL)搜索、筛选器或URL显示单个Issue、Issue列表或统计值。

这非常适用于：

该宏可以显示来自任何连接的 Jira 服务器、数据中心或云应用程序的问题，包括 Jira Software 和 Jira Service Management。

团队会议和回顾
项目状态报告
release notes和客户文档
与组织中不经常使用Jira的人员共享更新

该宏可以显示来自任何已连接的Jira系统数据，包括Jira Software和Jira Service Management。

截图：带有Jira Issue宏的项目状态页面，显示必须在发布前解决的Issue。

连接Confluence和Jira

在您可以使用此宏之前，您的Confluence和Jira系统必须通过Application Links来连接。查看页面的人将看到有权限访问的Issue相关的图表。如果您的Jira系统需要验证查看Issue的权限，那么他们需要在查看图表之前进行身份验证。

更多信息，请参阅Use Jira applications and Confluence together。

在页面中添加宏

在页面中添加Jira Issues宏：

从编辑器工具栏中，选择插入(Insert) > 其它宏（Other Macros）。
从Development类别中选择Jira。
输入筛选器或搜索Jira问题。
点击Insert。

然后，您可以发布您的页面以查看宏的效果

截图：配置 Jira Issues宏以显示Issue列表。

通过Jira Query Language（JQL）搜索来显示问题

根据使用JIRA Query Language（JQL）的搜索结果，您可以使用宏在页面上显示Issue列表。

JQL是一种类似于SQL的简单查询语言。基本的JQL查询由field、operator（例如 = 或 >）和一个或多个values或functions组成。

例子：

以下查询将查找“TEST”项目中的所有Issue：
```
project = "TEST"
```
以下查询将查找“CONF”项目的“文档”模块中的所有Issue：
```
project = CONF and component = documentation
```

关于JQL 语法的更多信息，请参阅 Jira Software 文档中的Advanced searching。

要显示基于JQL搜索的Issue列表：

如上所述，将Jira Issues宏插入您的Confluence页面。
选择“Search”按钮旁边的Jira系统。
如果出现提示，请登录Jira系统。
在Search框中输入JQL查询语句。
点击Search。
如果要自定义显示，请设置“Display options”并调整将出现在Issue列表中的列和Issue数量。
点击Insert。

截图：在Jira Issues宏浏览器中的Display options。

通过Jira URL显示Issue

您可以将以下任何Jira系统中的URL粘贴到Jira Issues宏中。Confluence会立即将URL转换为JQL搜索。

Issue搜索或筛选器的URL。
单个Issue的URL。
搜索结果的XML视图的URL。

自动转换：您可以将URL直接粘贴到Confluence编辑器中（无需调用宏浏览器）。Confluence会自动将URL转换为Jira Issues宏。

显示单个Issue或选定的多个Issue

要显示单个Jira Issue，请选择以下方法之一：

将Issue的URL直接粘贴到Confluence页面上。（无需使用宏浏览器。）Confluence会自动将链接转换为Jira Issues宏。
或者：如上所述在页面中添加Jira Issues宏，然后选择“Recently Viewed”以查看您最近访问过的问题。选择一个Issue并点击Insert。
或者：如上所述将Jira Issues宏添加到页面，然后将Issue URL粘贴到宏浏览器的搜索框中。
或者：如上所述将Jira Issues宏添加到页面，通过JQL在宏浏览器中定义搜索条件，然后在宏浏览器中选择搜索结果中Issue旁边的复选框。

您可以选择仅显示Issue关键字，或Issue关键字和概要。选择宏占位符并选择显示概要或隐藏概要。

要显示搜索结果中的一部分Jira Issue：

将Jira Issues宏添加到页面。
如上所述，通过JQL在宏浏览器中定义搜索条件。
在宏浏览器中，选中搜索结果中所需Issue旁边的复选框。

截图：选择要显示的Issue子集

显示Issue数量

您可以选择显示搜索返回的Issue数量，而不是Issue列表。Jira Issues宏将显示Issue数量，并链接到您的Jira中的搜索页面。

截图：显示issue数量的Jira Issues宏。

要显示Issue数量：

将 Jira 问题宏添加到页面。
如上所述，通过 JQL 在宏浏览器中定义搜索条件。
选择显示选项，然后选择宏浏览器中“显示选项”旁边的总问题计数。
选择插入。

将Jira Issues宏添加到页面。
如上所述，通过JQL在宏浏览器中定义搜索条件。
设置Display options，在宏浏览器中选择“Display option”旁边的“Total issue count”。
点击Insert。

创建新Issue

在编辑Confluence页面时，您可以在Jira中创建Issue并将其显示在您的Confluence页面上，而无需离开Confluence编辑器。

要创建Issue并将其添加到您的页面：

如上所述，将Jira Issues宏添加到页面.
点击Create New Issue。
根据提示提供关于您的Jira系统、项目和Issue的信息。
点击Insert。

Confluence将向您的Jira系统发送请求，以创建Issue，然后在您的页面上显示新创建的Issue。

限制

如果Jira Issues宏无法在所选项目中创建问题，则会通知您。这可能是因为项目具有 Jira Issues宏不支持的必填字段、字段配置或其它自定义配置。在这种情况下，您需要直接到Jira系统中创建Issue。

配置应用程序链接以显示受限Issue

在您可以使用此宏之前，您的Confluence和Jira站点必须通过Application Links连接。

如果Jira站点允许匿名用户查看Issue，则必须配置应用程序链接，但无需在Jira和Confluence之间配置任何传入或传出身份验证。查看Confluence页面的人将看到可公开访问的Issue。

如果您的Jira站点限制查看，或者如果某些项目或Issue仅限某些人查看，那么在看到受限Issue之前，系统会提示用户Log in & Approve。

从Jira渲染HTML

如果您设置了一个Confluence到Jira的应用程序链接，来自Jira的格式化字段可以在Confluence中呈现。否则，此类格式化字段将在Jira Issues宏的输出中进行转义。这是为了防止不受信任的Jira系统提供恶意HTML的可能性。您最有可能需要注意的字段是描述字段。

此示例显示了在Jira中的描述字段：

Description

This is

the description
of my issue

如果Jira和Confluence之间没有设置应用程序链接，则在Jira Issues宏中的描述字段显示为：

Description

<p>This is<ul><li>the description</li><li>of my issue</li></ul></p>

禁用Jira Issues宏

该功能由名为“Jira Macros”的系统插件提供。要使宏在您的网站上不可用，您可以禁用该插件。请参阅Disabling and enabling apps。

注意

HTTPS：如果Confluence服务器配置为接受Jira SSL证书，则Jira Issues宏可以访问在SSL下运行的Jira站点。请参阅Connecting to LDAP or Jira applications or Other Services via SSL。

自定义字段可以作为列添加到表中，只需使用不带引号的字段名称即可。早期版本的宏要求您使用自定义字段的ID，例如：customfield_10100。

其它添加方式

用键盘输入添加宏

输入左大括号{，然后输入宏名称的几个起始字符，就可以看到一个相关的宏列表。

通过wiki标记添加宏

当您想在编辑器之外添加宏时，这非常有用。例如作为侧边栏、空间页眉或页脚中的自定义内容。

Macro name: jiraissues

Macro body: None.

此示例使用Jira筛选器。

{jiraissues:anonymous=true|url=https://jira.atlassian.com/issues/?filter=41225}