JQL Issue Select Documentation

1. Description

JQL Issue Select Plugin allows you to use the results of a JQL statement as a selectable list field on JIRA screens. Single-select, multi-select and label field types are supported. 

2. Installation

Installing JQL Select Issue, involves the following steps:
 

1. Log in as a user with the JIRA Administrators.
2. Select Add-ons from the Administration menu at the top right of your screen. 

You can install the Add-On in two ways : Install the Add-On from Marketplace OR Upload an Add-On.

Upload an Add-On:
  

Install the Add-On from Marketplace:

1. Click the Find New Add-ons link.
2. Enter a search string in the Search the Marketplace box.
3. To install an add-on, click the Install button for free add-ons or the Buy Now or Free Trial buttons for paid add-ons. 

3. Configuration

To starting with JQL Select Issue, first the custom field must be added. 

1. Click Settings   >> Issues >> Custom Fields >> Add Custom Field.
2. From the list, select "JQL Filtered Field Lister" for multiple selection and select "JQL Filtered Field Lister Single" for single selection. 
3. After selecting the custom field, define a display name for your custom field. 
4. Select screens where you want to display your custom field. 
5. Click Configure from custom field settings. 
   
   
   
   
   
6. Click the "Edit JQLFilteredField"
   
   
   
   
   
   
   
7. In the configuration screen enter a valid JQL query, View Pattern and Value Pattern. (See below for more information on configuration details) 
   
   
   
   
8. Click Update button to save your configuration. 

4. Configuration Details

Field Types

There are 4 issuetypes introduced by JQL Issue Select.

• "JQL Issue Dropdown Selector (Single Select)" works completely like Select List field type of JIRA.
  
• "JQL Issue List Selector" fields work like list boxes. There are two variations for Single and Multi Select.
  
• "JQL Issue Label Selector" fields work like JIRA Label fields.
  

When the new field is defined and configured, it is ready to be added to JIRA screens.

JQL Query

The results of the JQL query entered here will be presented as selection options to the user.

All valid JQL statements are accepted. ORDER BY clauses are also allowed so the user can determine the order of items in the list. Please note that this field expects a valid JQL and does not check JQL validity until runtime.

summary ~ "Test" order by summary

This JQL returns all issues with the word "Test" in its "Summary" field and presents them as options for the field in summary order.

You can also use values of other fields on the issue to create dynamic queries. The field references in the JQL will be replaced by actual field values of the issue during runtime. This makes it possible to build a dynamic query which will run differently for each issue. Since each issue can have a different reporter, this field can display a different list for each individual issue it is used on.

project = TT and reporter = {issue.reporter}

This dynamic JQL above returns all the issues in project TT which were reported by the reporter of the issue we are currently working on.

View and Value Patterns

These patterns control how the issues from the JQL are displayed on the screen and how selected values are kept in the database.

Both View and Value patterns expect a string from the user. The string contains one or more references to issue fields between curly braces. The field references will be replaced by actual field values when preparing the list for screen.

{issue.summary} {issue.description}

The example View Pattern above will render a list as shown below:

References to issue fields may include system fields, custom fields or both. The following system fields may be referenced by name as below:

{issue.key}
{issue.summary}
{issue.projectkey}
{issue.parentkey}
{issue.assignee}
{issue.created}
{issue.creator}
{issue.description}
{issue.duedate}
{issue.environment}
{issue.id}
{issue.type}
{issue.priority}
{issue.reporter}
{issue.resolution}
{issue.status}
{issue.updated}

Custom fields may be referenced using the custom field ID as below:

{issue.cf_10123}

The comma char (",") is a reserved char and cannot be used in patterns.

Maximum Selection Count

JQL Issue Label Selector custom field has a configuration for limiting the maximum selected issue count on the custom field. 

5. Support for previous JIRA Versions

For the customers are using older JIRA Server versions: Please visit "Version History" page of this plugin and download the compatible version.