Confluence 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}

CODE

许多无法通过宏浏览器获得的附加参数在存储格式和wiki标记中可用。

查看附加参数...

Parameter name	Required	Default	Parameter description and accepted values
`anonymous`	No	`false`	If this parameter is set to 'true', your Jira application will return only the issues which allow unrestricted viewing. That is, the issues which are visible to anonymous viewers. If this parameter is omitted or set to 'false', then the results depend on how your administrator has configured the communication between the Jira application and Confluence. By default, Confluence will show only the issues which the user is authorized to view. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter.
`baseurl`	No	The value of the 'url' parameter	If you specify a 'baseurl', then the link in the header, pointing to your Jira application, will use this base URL instead of the value of the 'url' parameter. This is useful when Confluence connects to Jira with a different URL from the one used by other users.
`columns`	No	By default, the following columns are shown: type key summary assignee reporter priority status resolution created updated due	A list of Jira column names, separated by semi-colons (;). You can include many columns recognized by your Jira application, including custom columns. Some columns, such as those that need to be calculated by Jira like 'work ratio' or 'time to resolution', can't be viewed in Confluence.
`count`	No	`false`	If this parameter is set to 'true', the issue list will show the number of issues in Jira. The count will be linked to your Jira site.
`cache`	No	`on`	The macro maintains a cache of the issues which result from the Jira query. If the 'cache' parameter is set to 'off', the relevant part of the cache is cleared each time the macro is reloaded. (The value 'false' also works and has the same effect as 'off'.) Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter.
`height`	No	`480` (if render mode is dynamic)	The height in pixels of the table displaying the issues. Note that this height specification is ignored in the following situations: If the 'renderMode' parameter (see below) is set to 'static'. When the issues are displayed in a PDF or Word document, in an email message or in an RSS feed. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter.
`renderMode`	No	`static`	If the value is 'dynamic', the Jira Issues macro offers an interactive display which people can manipulate as follows: Click the column headers to sort the output. Drag and drop the columns into a different order. Temporarily remove a column from the display. View a page of issues at a time, for faster response times. A value of 'static' will disable the dynamic display features. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter.
`title`	No	Jira Issues	You can customize the title text at the top of the issues table with this parameter. For instance, setting the title to 'Bugs-to-fix' will replace the default 'Jira Issues' text. This can help provide more context to the list of issues displayed. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter.
`url`	Yes	none	The URL of the XML view of your selected issues. Note: If the URL in the 'url' parameter does not contain a `tempMax` argument, then the value of `tempMax` will default to 500. If your Jira server is version 3.12 or earlier, this means that the Jira Issues macro will return a maximum of 500 issues. If your Jira server is version 3.13 or later, a value of 500 means that the Jira Issues macro will return a maximum of 500 issues per page.
`width`	No	100%	The width of the table displaying the issues. Can be entered as a percentage (%) or in pixels (px). Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The macro browser does not offer this parameter.