JIRA Plugin

JIRA issues can be displayed as a TWiki table, based on a JQL (JIRA Query Language).

Introduction

JQL is JIRA Query Language for advanced search, which "allows you to use structured queries to search for JIRA issues." See the documentation at the Atlassian's website for details.

With this plugin, you can specify any JQL and display the issues found by the search.

Example

%JIRA{
  "http://my-jira-server/jira"
  jql="project = xyz and status in (resolved, closed)"
}%

The specified URL should be the common prefix of all the contents in your JIRA server. For example, if a project's "browse" URL is http://server/path/to/jira/browse/XYZ, the common URL is likely to be http://server/path/to/jira.

The above example will generate a table of issues found by the JQL:

Type	Key	Assignee	Summary	Status	Priority
Bug	XYZ-3	abcdef	A bug reported by a user	Resolved	Major
Issue	XYZ-2	abcdef	A minor issue	Closed	Minor
New Feature	XYZ-1	ghijkl	A new feature	Resolved	Minor

Fields

The columns to display can be selected by fields parameter.

%JIRA{
  "%JIRAURL%"
  jql="project = xyz and status in (resolved, closed)"
  fields="key, summary, updated"
}%

The fields parameter accepts comma-separated list of the available fields below:

Custom fields such as "customfield_12345" can also be used as field names.

"all" can be used as a field name to indicate all the fields including custom fields. This is useful to temporarily display the table to see all the available fields. If "all" is used together with any other fields (e.g. fields="id, status, all"), the "all" portion indicates all the other fields than the explicitly specified fields.

Field options

Each field name can be followed by an option to control the display format. For example, the type field is displayed as both icon and text like " Bug" by default, and it can be written as type_icon to display only the icon, or type_text to display only the text.

Below are all the available field options. In addition to these, for any of the fields, _raw or _id can be specified to use the raw value provided by the server.

Date

For the fields of the Date type, dateformat parameter can also be used to control how the dates are displayed (unless the explicit options such as _date, _full, etc. are used).

The date format follows the rule of strftime. In addition, since the percent sign (%) tends to collide with the TWiki syntax, the dollar sign ($) can also be used instead of each percent sign. (For example, dateformat="$Y-$m-$d $H:$M:$S" or dateformat="$F $T")

The timezone is based on the JIRA server, so that all the dates look the same as what are displayed in the JIRA pages.

Format

The way each JIRA issue is displayed can be customized by header, format, and footer parameters. The format parameter will be applied for each JIRA issue one by one.

In the parameters, a dollar sign ($) followed by a field name (such as $varname; see above for field names) can be used as a variable that will be replaced by the actual value of the field. The format options such as _icon and _mixed can also be used.

%JIRA{
  "%JIRAURL%"
  jql="project = xyz and status in (resolved, closed)"
  format="---++++ $type_icon $key $n   * $summary $n   * $status $n"
}%

You can omit fields parameter because the variables in format tell the plugin which fields you need.

The generated format will look as below:

XYZ-3

• A bug reported by a user
• Resolved

XYZ-2

• A minor issue
• Resolved

XYZ-1

• A new feature
• Resolved

Special variables

In addition to the field variables, special variables are available:

Context	Variable	Description
Anywhere	$header	Represents a table header based on the fields (such as =	*Type*	*Key*	...	=, not including the line break)
Anywhere	$n	A line break
Anywhere	$dollar	A dollar sign ($)
Anywhere	$percnt	A percent sign (%)
Each issue	$row	Represents a table row that would be generated by default (such as =	...	...	=, not including the line break)
Each issue	$all	Represents a table row corresponding to the special field name "all" (see the previous section for details). Any fields excluded from the field "all" (because they are explicitly specified next to "all") will also be excluded from $all.
Each issue	$url	URL for browsing the issue

Pagination

The JQL search results can be paginated, utilizing TWiki:TWiki.SearchResultsPagination.

%INCLUDE{"%SYSTEMWEB%.SearchResultsPagination" section="preamble"}%<nop>
%CALCULATE{$SET(limit, %URLPARAM{"limit" default="10"}%)}%<nop>
%JIRA{
  "http://my-jira-server/jira"
  jql="project = xyz"
  start="%CALCULATE{$GET(start)}%"
  limit="%CALCULATE{$GET(limit)}%"
  footer="$percntCALCULATE{$SET(ntopics, $total)}$percnt"
}%
%INCLUDE{"%SYSTEMWEB%.SearchResultsPagination" section="postamble"}%<nop>

The two parameters start and limit control the pagination. (Default: limit="10" start="0")

Pagination-related variables are available for format, header, footer, etc. as below:

Grouping issues by a field

The JIRA issues found by JQL can be classified into multiple groups with groupby parameter. This parameter takes one field name, followed by an optional keyword "asc" or "desc" to specify the order (ascending or descending, respectively). If the ordering keyword is not specified, the result is based on the order of occurrence in the JQL result.

If the groupby parameter is specified, custom format can be specified by groupheader and groupfooter parameters, similarly to header and footer parameters.

In each of the group formatting parameters, the variable name for the groupby field can be used. For example (below), the variable $status can be used in the groupheader parameter because groupby is set to "status". The field options such as _icon and _text are also available in the group formatting parameters.

Any issues that do not have the groupby field value will be excluded. In order to include those issues, groupdefault parameter can be specified as the default value (e.g. groupby="version" groupdefault="(no version)").

%JIRA{
  "%JIRAURL%"
  jql="project = xyz"
  fields="type_icon, key, summary, priority"
  groupby="status asc"
  groupheader="---++++ $status $n $header"
}%

In Progress

Type	Key	Summary	Priority
	XYZ-4	An improvement	Major

Resolved

Type	Key	Summary	Priority
	XYZ-3	A bug reported by a user	Major
	XYZ-1	A new feature	Minor

Closed

Type	Key	Summary	Priority
	XYZ-2	A minor issue	Minor

Troubleshooting

General troubles

If you encounter any troubles with your JQL query (e.g. if you see 400 Bad Request), please try visiting your JIRA site and pasting the query in the advanced search. It might show you some useful error message.

The search form is found if you navigate from Issues -> Search for Issues, and then click on "advanced searching" (if you are in the "simple searching" mode).

Issues are not found

Sometimes, JQL may not seem to work with something simple like type = Bug and status in (Resolved, Completed). It is probably because your JIRA instance uses custom values, such as "Task Completed", "Intermittent Bug", etc., which may seem to be the same things as Completed, Bug, etc. but are not the same.

When you have difficulty, try using the fields="all" to dump the matched results temporarily in your TWiki page. Alternatively, visit your JIRA site and paste the query in the advanced search, as it is likely you can find more information there (see above on how to try the advanced search).

As documented in the Atlassian's website, the safest way is to use an integer value (no matter how it looks cryptic). If you think your custom values will not change that often, you can use the text value in full, but remember that, if somebody ever modifies the custom value on the JIRA side, then your JQL query will stop working all of a sudden.

Double quotes in JQL

Although the "advanced search" may suggest to use double quotes for multi-word values, TWiki does not allow you to use it inside the jql="..." parameter.

Please either escape the double quotes, or use single quotes instead:

%JIRA{... jql="status = \"blah blah blah\""}%
%JIRA{... jql="status = 'blah blah blah'"}%

WikiName breaks a hyperlink

If any of the value contains a WikiName (such as "ReOpened"), it may be converted in an unintended way:

Status
ReOpened"/> 0 - ReOpened

In this case, please use the <noautolink> tag:

<noautolink>
%JIRA{
  ...
}%
</noautolink>

Parameter Reference

Query parameters

Name	Description
(default) *	Common URL prefix for the JIRA server. The above example demonstrates how to specify the correct URL.
jql *	JQL query (see Advanced Searching for details)
limit	Limit the number of JIRA issues found by the JQL. (default = "10")
start	Offset index (0-based) for pagination. (default = "0")
timeout	Timeout in seconds for retrieving the results from the JIRA server. (default = "20")

* denotes required fields.

Formatting parameters

Name	Description
fields	Comma-separated list of field names to specify columns (default = "type, key, assignee, summary, status, priority")
header	Header format. (default = "$header" unless format is provided)
format	Record format, applied for each row of a JIRA issue
footer	Footer format.
separator	Separator between each row. (default = "$n" unless format ends with "$n"; otherwise default = "")
dateformat	Date format (strftime), where the dollar sign ($) can also be used instead of each percent sign (%)
icons	Specify "off" to turn off icons unless _icon or _mixed options are explicitly used. (default = "on")

Grouping parameters

Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

Show details Hide details

Plugin Info

One line description for extensions repository catalog:

• Set SHORTDESCRIPTION = Display JIRA issues using JQL search

Many thanks to the following sponsors for supporting this work:

• Morgan Stanley

Plugin Author:	TWiki:Main.MahiroAndo
Copyright:	© 2012 TWiki:Main.MahiroAndo © 2012 TWiki:TWiki.TWikiContributor
License:	GPL (Gnu General Public License)
Plugin Version:	2013-03-15

Show Change History Hide Change History

Change History:
2013-03-15:	TWikibug:Item7194: Search result pagination -- TWiki:Main.MahiroAndo
2013-03-08:	TWikibug:Item7154: Fix a minor doc bug -- TWiki:Main.MahiroAndo
2013-02-01:	TWikibug:Item6991: Fix a minor issue in error message when a wrong URL is specified -- TWiki:Main.MahiroAndo
2012-11-13:	TWikibug:Item7020: Categorize TWiki Variable JIRA -- TWiki:Main.PeterThoeny
2012-10-31:	TWikibug:Item6991: Use updated TWiki::Func::getExternalResource() instead - TWiki:Main.MahiroAndo
2012-10-16:	TWikibug:Item6991: Leverage TWiki::Func::getLWPRequest() - TWiki:Main.MahiroAndo
2012-10-05:	TWikibug:Item6953: Add VarJIRA
2012-09-21:	TWikibug:Item6940: Initial version

Dependencies:	CPAN:Date::Parse, CPAN:DateTime, CPAN:LWP::UserAgent, CPAN:Sort::Versions, CPAN:XML::LibXML
Plugin Home:	http://twiki.org/cgi-bin/view/Plugins/JiraPlugin
Feedback:	http://twiki.org/cgi-bin/view/Plugins/JiraPluginDev
Appraisal:	http://twiki.org/cgi-bin/view/Plugins/JiraPluginAppraisal

Related Topics: VarJIRA, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences