JIRA 问题（Issues）宏

JIRA 是 Atlassian 提供的缺陷跟踪和项目管理系统。通过向 Confluence 页面中添加 JIRA 问题（Issues）宏，你可以将一个或者多个问题显示到 JIRA 中。你也可以选择从页面的 JIRA 问题（Issues）宏中创建一个 JIRA 问题。

在你使用这个宏之前，你需要将 JIRA 站点通过 应用链接（Application Links）链接到 Confluence 站点中。Confluence 的用户在查看页面的时候将会看到 JIRA 中允许被匿名用户查看的页面。

如果 JIRA 站点被限制查看的话（用户需要具有查看问题权限），用户需要先进行授权。更多有关 JIRA 问题限制查看的问题，请参考下面的内容。

你可以用 JIRA 问题（Issues）宏干什么

使用 JIRA 问题宏你可以：

使用 JIRA Query Language（JQL）查询语句在你的页面中显示 JIRA 的问题列表。
使用 JIRA 的 URL 在你的页面中显示 JIRA 的问题列表。
从 JIRA 站点中显示单一的一个问题或者从 JIRA 查找结果中选择一个的问题。
从 JIRA 站点中显示一系列问题。
在 JIRA 中创建一个新问题同时再你的页面中显示问题。完成上面的过程，你不需要离开 Confluence 页面。

添加和更新 JIRA 问题宏概述

在 Confluence 页面使用 JIRA 问题宏快速指南：

打开你希望编辑 Confluence 页面，然后单击 编辑（Edit）按钮。页面的编辑模式将会被打开。
下一步，在编辑工具栏中单击宏浏览器图标。这时候宏浏览器将会在屏幕的中间打开。
在宏浏览器中，在窗口的右上角的对话框中输入你希望插入的宏的名称。当找到与你输入的宏名称接近的宏后将会在中间的面板上显示。单击需要的宏然后来查看可用进行配置的宏选项，在这里你可以对需要插入的宏设置相关参数，然后单击 插入（insert）来将需要的宏插入到页面中。

屏幕截图：JIRA 问题宏在 Confluence 页面中的示例

通过 JIRA Query Language (JQL) 查找显示问题

你可以使用 JIRA Query Language （JQL）的查询结果在页面中显示 JIRA 的问题列表。

JQL 是一个简单的查询语言，与 SQL 基本上是相同的，只是 JQL 是为 JIRA 服务器的。一个基本的 JQL 查询语句包含有一个字段，然后跟在后面是一个操作符（例如 = 或者 >），最后跟在操作符后面的是变量或者函数。

示例：

下面的查询代码将会在 'TEST' 项目中找到所有的问题：
```
project = "TEST"
```
下面的查询代码将会在 'CONF' 项目的中找到 'documentation' 组件的所有问题：
```
project = CONF and component = documentation
```

有关 JQL 查询使用的句法，请参考 JIRA的文档中有关 JQL 的说明。

基于 JQL 查找显示问题列表：

插入 JIRA 问题宏到你 Confluence 页面中，请参考上面的描述说明。
选择 JIRA 服务器然后选择 查找（Search）按钮。
如果对话框弹出需要用户名和密码，输入用户名和密码登录 JIRA 服务器。
在查找对话框中输入 JQL 查询语句。
选择 查找（Search）进行查找。
如果你希望自定义显示，选择 显示选项（Display options）然后调整显示的列数量和你希望在问题表格中显示的问题数量。
选择插入（Insert）。

屏幕截图：在 JIRA 问题宏浏览器显示选项。

通过 JIRA URL 显示一个问题

你可以粘贴下面的 JIRA URL 到 JIRA 问题宏中。Confluence 将会把这些 URL 转换为 JQL 查询语句。

JIRA 问题查找的的 URL 或者过滤器的 URL。
一个问题的 URL。
一个 JIRA 查找的 XML 视图 URL。

自动转换：你可以粘贴一个 JIRA URL 直接到 Confluence 编辑器中（不需要调用宏浏览器）。Confluence 将会自动将这个 URL 转换为 JIRA 问题宏。

显示一个 JIRA问题或者选择的 JIRA 问题

希望显示一个单独 JIRA 问题，可以选择下面的任意方法：

将问题的 URL 直接粘贴到 Confluence 页面中（这种方式不需要使用宏浏览器）。Confluence 将会自动将问题转换为 JIRA 问题宏。
或者：使用上面的描述说明添加一个 JIRA 问题宏，然后选择 近期查看（Recently Viewed）的内容来查看你最近在 JIRA 中查看的内容。选择一个问题，然后单击 插入（Insert）。
或者：使用上面的描述说明添加一个 JIRA 问题宏，然后将问题的 URL 粘贴到宏浏览器的查找对话框中。
或者：使用上面的描述说明添加一个 JIRA 问题宏，通过上面描述的方式定义一个 JQL 查询语句。然后在宏浏览器中显示的查询结果列表中，你希望插入到页面的问题。

从你的查询结果中选择几个 JIRA 问题进行显示：

向页面中添加一个 JIRA 问题宏。
在你的宏浏览器中通过 JQL 定义查询语句，请参考上面的描述说明。
在宏浏览器中，选择查询结果中的复选框。

屏幕截图：选择一系列子问题

显示问题的数量

你可以在页面中显示你查询结果返回的数量，而不是一个问题的列表。JIRA 问题宏将会在页面中显示的数量，然后将这个数量链接到 JIRA 的查询中。

屏幕截图：JIRA问题宏在一个 Confluence 界面中显示问题的数量

希望在页面中显示问题的数量：

将 JIRA 问题宏添加到页面中。
在你的宏浏览器中通过上面描述的方式定义一个 JQL 查询语句。
选择 显示选项（Display options），然后选择在宏浏览器下面的显示选项中的总计问题数量（Total issue count）。
选择 插入（Insert）。

在编辑器中新建一个 JIRA 问题

通过编辑 Confluence 页面，你可以直接在 Confluence 页面中创建一个 JIRA 问题，而不需要离开 Confluence 编辑器。

希望向 JIRA 中插入一个问题：

使用上面的描述说明添加一个 JIRA 问题宏。
选择 创建一个问题（Create New Issue）。
提供有关你 JIRA 服务器的信息后，需要输入的项目和问题将会被显示出来。
然后选择插入（Insert）。

Confluence 将会把请求发到 JIRA 上来将你输入的问题插入到 JIRA 系统中。Confluence 页面也将会显示 JIRA 问题的结果。

注意：

这个特性最好是在 JIRA 的问题类型没有被修改过的情况下使用。如果你修改了 JIRA 问题的 'Component/s' 或者 'Fix Version/s' 字段的话，JIRA 问题宏的这个特性可能不能够正常工作，你在 JIRA 中新加入的 JIRA 问题类型有可能是必填字段而导致插入失败。(例外：自定义的 'Component/s' 和 'Fix Version/s' 字段是可以接受的。）
如果你的 JIRA 项目工程有自定义字段的话，JIRA 问题宏将不会要求你输入自定义字段的信息。换句话说，自定义字段中要求输入的内容将不会在这个宏中显示。

配置应用链接来显示受限制的 JIRA 问题

在你使用这个宏之前，你需要配置 JIRA 站点连接其他应用程序中说明的内容。

如果一个 JIRA 站点运行你们访问问题，你也必须要配置这个连接，但是不需要在 JIRA 和 Confluence 之间配置授权。人们在查看 Confluence 页面的时候将会看到 JIRA 站点允许匿名访问的 JIRA 问题。

如果你的 JIRA 站点被限制查看或者一些 JIRA 问题被限制为只有特定的人能够查看的话，你需要首先进行登录后进行查看。

在一些情况下，Confluence 应用链接的外连授权确定 JIRA 问题宏如何处理问题查看的限制：

如果Confluence 应用链接的外连授权为 信任的应用（Trusted Applications），用户可以直接访问 JIRA 中受限制的问题，但是前提条件是用户的 JIRA 用户名和密码与 Confluence 中的用户名和密码一致，同时这个用户还具有查看受限制问题的权限。
如果Confluence 应用链接的外连授权为 OAuth 授权（OAuth）, 用户需要选择 登录和许可（Login & Approve）来获得 JIRA 服务器上受限制的问题。
如果Confluence 应用链接的外连授权为 基本访问（Basic Access） ，用户需要登录才能给查看 JIRA 中受限制的问题。

从 JIRA 中重构 HTML

如果你在 Confluence 和 JIRA 中设置了应用连接，那么 Confluence 的格式化字段也可以在 JIRA 中显示的。否则的话，格式化字段将会在 JIRA 问题宏中输出内容的时候忽略。

这个主要被用于防止 HTML 注入攻击，如果你包含了不信任的站点，那么很有可能 HTML 代码中含有恶意代码。

下面的代码示例说明了信任站点如何在 JIRA 中显示 HTML 内容：

描述

This is

the description
of my issue

下面的代码示例说明了不信任站点如何在 JIRA 中显示 HTML 内容：

描述

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

禁用 JIRA 问题宏

这个参数由插件 'JIRA Macros' 控制显示。这个宏也可以在 JIRA 问题宏中使用。

希望将 JIRA 图表宏禁用，你需要将这个插件禁用。

注意

HTTPS: JIRA 图表宏可以访问使用了 SSL 安全套接字的 JIRA 站点。Confluence 服务器被配置可以接受 JIRA SSL 套接字证书。

自定义字段可以被添加到列表中，你可以通过在字段名字前加入引号。在早期的版本中，自定义字段是需要通过字段 id 引用的。例如：customfield_10100.

代码示例

下面的代码是提供给希望进一步编辑 Confluence 页面的高级用户使用的。

宏名称： jiraissues

宏内容： None.

注意：下面的内容是在存储格式和Wiki 格式中使用的一些可用的参数。

参数名字

是否必须

默认值

参数描述和可以接受的值

`anonymous`	No	`false`	如果这个参数被设置为 'true'的话，JIRA 将会返回仅仅能够被不收取查看的问题。问题的查看是否能够被查看是根据 JIRA 的查看显示来确定的。如果这个参数被设置为 'false'的话，能查看什么和不能查看什么是根据系统管理员在 JIRA 和 Confluence 进行配置的情况下确定的。默认情况下，Confluence 将会仅仅显示被授权查看的问题。注意：这个参数仅仅在你使用维基标记格式或者编辑存储格式页面的时候可用。图形化的用户界面（宏浏览器）中将不会显示这个参数。
`baseurl`	No	'url' 的参数	如果你指定了 'baseurl' 参数，那么在链接的前面将会指向到你的 JIRA 站点将会使用你输入的 URL 参数。当 Confluence 和 JIRA 实例使用不同的 URL ，同时还是不同的人进行维护的时候。
`columns`	No	在默认情况下，下面的列将会被显示： type key summary assignee reporter priority status resolution created updated due	JIRA 问题列表中显示的列。使用分号进行分隔。你可以使用你 JIRA 站点中的任意列，其中也包括自定义列。请查看 JIRA 管理员文档来获得有关的列名称。
`count`	No	`false`	如果这参数被设置为 'true' 的话，问题列表将会显示 JIRA 的问题数量，通过单击这个问题数量可以链接到 JIRA 站点。
`cache`	No	`on`	这个宏维护了 JIRA 的查询缓存。如果 'cache' 参数被设置为 'off' 的话，有关缓存的内容将会在每次查询的时候不被存储（使用值 'false' 和 'off' 都可以）。注意：这个参数仅仅在你使用维基标记格式或者编辑存储格式页面的时候可用。图形化的用户界面（宏浏览器）中将不会显示这个参数。
`height`	No	`480` (如果动态重载)	JIRA 问题显示宏的表格高度。注意，这个参数在下面的情况下会被忽略：如果 'renderMode' 参数被设置为 'static'。当 JIRA 问题在 PDF 或者Word 文档中显示或者在 email 或者 RSS 中显示。注意：这个参数仅仅在你使用维基标记格式或者编辑存储格式页面的时候可用。图形化的用户界面（宏浏览器）中将不会显示这个参数。
`renderMode`	No	`static`	如果这个值被设置为 'dynamic'，JIRA 问题宏将会提供给用户多个显示方式：单击列名对输出进行排序。可以对列进行拖放。从显示中临时移除一列。查看问题的时间，为了能够得到更快的响应。如果这里被设置为 'static' 的话，所有的动态属性将会被禁用。注意：这个参数仅仅在你使用维基标记格式或者编辑存储格式页面的时候可用。图形化的用户界面（宏浏览器）中将不会显示这个参数。
`url`	Yes	none	在你使用 JIRA 问题导航器的时候的XML 视图 URL。注意：如果 'url' 的 URL 参数没有`tempMax` 参数，那么 `tempMax` 将会默认使用 500。如果你的 JIRA 版本为 3.12 或者早期版本，JIRA 问题宏将会最多返回 500 个问题。如果你的 JIRA 服务器版本是 3.13 或者以上版本，这个地的值 500 表示的是 JIRA 问题宏将会在每一页最多返回 500 个问题。
`width`	No	100%	JIRA 问题宏中显示的表格宽度，可以使用百分比（%）和像素（px）。注意：这个参数仅仅在你使用维基标记格式或者编辑存储格式页面的时候可用。图形化的用户界面（宏浏览器）中将不会显示这个参数。

来源：http://cwiki.ossez.com/pages/viewpage.action?pageId=2393283