JIRA Plugin

Display JIRA issues using JQL search

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


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.


  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


The columns to display can be selected by fields parameter.

  jql="project = xyz and status in (resolved, closed)"
  fields="key, summary, updated"

Key Summary Updated
XYZ-3 A bug reported by a user 17/Oct/2011
XYZ-2 A minor issue 12/Oct/2011
XYZ-1 A new feature 30/Sep/2011

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

Name Type
priority Icon+Text
status Icon+Text
project LinkedText
components List
attachmentNames List
reporter UserName
key LinkedText
assignee UserName
summary Text
updated Date
Name Type
id Integer
votes Integer
fixVersions List
affectsVersions List
description Text
environment Text
created Date
resolution Text
type Icon+Text
duedate Date
Name Type
timeEstimate Text
timeOriginalEstimate Text
timeSpent Text
aggregateTimeEstimate Text
aggregateTimeOriginalEstimate Text
aggregateTimeSpent Text

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

IDEA! "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.


Option Description
_mixed (default) Icon + Text
_icon Icon only
_text Text only
_id or _raw Integer ID


Option Description
_mixed (default) [[URL][Text]]
_url or _href URL only
_text Text only


Option Description
_mixed (default) [[URL][FullName]]
_url or _href URL only
_text FullName only
_id or _raw UserName only


Option Description
_date (default) DD/MMM/YYYY (e.g. 05/May/2011)
_long YYYY-MM-DD HH:mm 'ZZZ'
_full YYYY-MM-DD HH:mm:ss 'ZZZ'
_ts Integer timestamp
_id or _raw YYYY-MM-DD'T'HH:mm:ss.uuu'Z' (e.g. 2011-09-21T03:58:35.000Z), based on GMT

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")

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


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.

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

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

The generated format will look as below:


  • A bug reported by a user
  • Resolved


  • A minor issue
  • Resolved


  • A new feature
  • Resolved

Special variables

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

ContextSorted ascending 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


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>
  jql="project = xyz"
  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:

Variable Description
$start Starting index (0-based). Same as the start parameter.
$end Ending index (usually start + limit, except for the last page)
$total Total hits found by the JQL. It can be greater than limit.
$result Number of issues returned by the server for the current search (limit or less).
$count Number of issues in each group, if used in the groupby context. Otherwise, it is the same as $result.

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)").

  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


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


Type Key Summary Priority
XYZ-2 A minor issue Minor


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:

ReOpened"/> 0 - ReOpened

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


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

Name Description
groupby Comma-separated list of field names to group the results by
grouplimit Limit the number of issues in each group. (default = no limit; i.e. limit is only based on the limit parameter)
groupheader Header format for each group
groupfooter Footer format for each group
groupseparator Separator between each group of rows
groupdefault Default value for the field given for groupby, so as not to exclude issues that do not have the values

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.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip JiraPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/JiraPlugin.txt Plugin topic
      data/TWiki/VarJIRA.txt JIRA variable documentation topic
      lib/TWiki/Plugins/JiraPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/JiraPlugin/Handler.pm Perl module
      lib/TWiki/Plugins/JiraPlugin/Client.pm Perl module
      lib/TWiki/Plugins/JiraPlugin/Field.pm Perl module
      pub/TWiki/JiraPlugin/*gif Image files
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Configure additional plugin settings in the Extensions section if needed.
    • Test if the installation was successful using the example above.

  • Documentation hook:
    • Set JIRAPLUGIN_SUPPLEMENT variable to a topic name to include the topic as a supplemental documentation at the top of this page (e.g. intranet-specific notice). It is expected to configure the JIRAPLUGIN_SUPPLEMENT variable in the preference topic of $cfg{LocalSitePreferences} (or Main.TWikiPreferences by default) so that it is effective when this documentation is displayed.

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:

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

This topic: TWiki > JiraPlugin
Topic revision: r0 - 2013-03-15 - TWikiContributor
This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.JiraPlugin