[转]Insert the Jira issues macro create and display Jira issues on Confluence pages

本文转自：https://support.atlassian.com/confluence-cloud/docs/insert-the-jira-issues-macro/

Insert the Jira issues macro

If your Confluence site is connected to a Jira application, you can create and display Jira issues on Confluence pages. You can connect Confluence to any Jira application, including Jira Software and Jira Service Desk. 

What you can do with the Jira Issues macro

Using the Jira Issues macro, you can:

• Display a list of issues on your page, based on a Jira Query Language (JQL) search, filter or URL.
• Display a single issue.
• Display a count of issues.
• Create new issues and display the issues on your page without leaving Confluence.

Adding and updating the Jira Issues macro – an overview

Quick guide to using the macro on a Confluence page:

1. In the Confluence editor, choose > Other Macros
2. Find and select the required macro

Speeding up macro entry with autocomplete:

• In the new editor -Type / and the beginning of an element (tool or things in the insert menu) to see a list of suggestions.
• In the legacy editor -Type { and the beginning of the macro name to see a list of suggested macros.

Details are in Keyboard shortcuts, markdown, and autocomplete.

 

To edit an existing macro

Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

Screenshot: Example of Jira issues macro on a Confluence page

Displaying issues via a Jira Query Language (JQL) search

You can use the macro to display a table of issues on your page, based on the results of a search using Jira Query Language (JQL).

JQL is a simple query language that is similar to SQL. A basic JQL query consists of a field, followed by an operator (such as = or >), followed by one or more values or functions.

Examples:

• The following query will find all issues in the 'TEST' project:

  project = "TEST"

• The following query will find all issues in the 'documentation' component of the  'CONF' project:

  project = CONF and component = documentation

For more information about JQL syntax, see Advanced searchingin the Jira Software documentation.

To display a table of issues based on a JQL search:

1. Insert the Jira Issues macro onto your Confluence page, as described above.
2. Choose a Jira server next to the Search button.
3. If prompted, log in to the Jira server.
4. Enter the JQL query into the Search box.
5. Choose Search.
6. If you want to customize the display, choose Display options and adjust the columns and number of issues that will appear in your table of issues.
7. Choose Insert.

Screenshot: Display options in the Jira Issues macro browser.

Displaying issues via a Jira URL

You can paste any of the following Jira application URLs into the Jira Issues macro. Confluence will immediately convert the URL to a JQL search.

• Any URL for an issue search or filter.
• A URL for a single issue.
• The URL of the XML view of a search.

Auto-convert: You can paste URLs directly into the Confluence editor (without calling up the macro browser). Confluence will automatically convert the URL into a Jira Issues macro.

Displaying a single issue, or selected issues

To display a single Jira issue, choose one of the following methods:

• Paste the URL of the issue directly onto the Confluence page. (There is no need to use the macro browser.) Confluence will auto-convert the link to a Jira Issues macro.
• Or: Add the Jira issues macro to the page as described above, and choose Recently Viewed to see the issues you have visited recently. Select an issue and choose Insert.
• Or: Add the Jira issues macro to the page as described above, and paste the issue URL into the search box in the macro browser.
• Or: Add the Jira issues macro to the page, define your search criteria in the macro browser via JQL as described above, then select the check box next to the issue in the search results, within the macro browser.

You can choose to show just the issue key, or the issue key and a summary. Select the macro placeholder and choose Show Summary or Hide Summary. 

To display a subset of Jira issues from your search results:

1. Add the Jira issues macro to the page.
2. Define your search criteria in the macro browser via JQL, as described above.
3. Select the check boxes next to the required issues in the search results, within the macro browser.

Screenshot: Selecting a subset of issues to display

Displaying a count of issues

You can choose to display the number of issues returned by your search, rather than a table of issues. The Jira Issues macro will display a count of issues, linked to the search in your Jira application.

Screenshot: The Jira Issues macro displaying an issue count on a Confluence page

To display an issue count:

1. Add the Jira Issues macro to the page.
2. Define your search criteria in the macro browser via JQL, as described above.
3. Choose Display options, then choose Total issue count next to 'Display options' in the macro browser.
4. Choose Insert.

Creating a new issue 

While editing a Confluence page, you can create an issue in Jira and display it on your Confluence page, without leaving the Confluence editor.

To create an issue and add it to your page:

1. Add the Jira Issues macro to the page, as described above.
2. Choose Create New Issue.
3. Supply the information about your Jira server, project, and issue, as prompted.
4. Choose Insert.

Confluence will send a request to your Jira application, to create the issue, then display the newly created issue on your page.

Limitations

The Jira Issues macro will notify you if it is unable to create an issue in the selected project. This may be because the project has a required field, field configuration or other customization that is not supported by the Jira Issues macro. In this situation you will need to create the issue directly in your Jira application.

Rendering HTML from Jira applications

Formatted fields from Jira can be displayed in Confluence if you set up a Confluence-to-Jira application link. Otherwise, such formatted fields will be escaped within the output of the Jira issues macro. This is to prevent the possibility of malicious HTML being served by an untrusted Jira server. The most likely field where you will notice this is in the description field.

This example shows how a description column may be displayed in Jira:

Description

This is

• the description
• of my issue

If there is no application link between Jira and Confluence, the description will appear in the Jira issues macro like this:

Description

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

Disabling the Jira Issues macro

The functionality is provided by an add-on (plugin) called 'Jira Macros'. To make the macro unavailable on your site, you can disable the add-on. See Disabling and enabling apps.

Wiki markup example

 

Wiki markup is only supported in the legacy editor.

Wiki markup is useful when you need to add a macro outside the editor, for example as custom content in the sidebar, header or footer of a space.

Macro name: jiraissues

Macro body: None.

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

Note: A number of additional parameters that are not available via the macro browser are available in storage format and wiki markup.

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.