Configuring PocketQuery for your Project
Queries maintained by Jira administrators are parameterized and executed using the PocketQuery add-on. This page describes how to configure queries in your project settings.
Enabling Queries within your project
Within any Jira project you can enable your queries by navigating to Project Settings > PocketQuery settings. There you can choose what locations to render your queries in:
Center (Option 1 in the picture)
Right Sidebar (Option 2 in the picture)
Tab (Option 3 in the picture)
Each location can be given a section title that will be displayed in the issue view. If you do not choose a name "PocketQuery" will be displayed instead.
When viewing an issue these are the locations that your queries will be rendered in (left = "Center", right = "Right Sidebar", tab = "Tab"):
To enable a new query within your project choose a query via clicking on "Choose a new query" and the location you want by clicking on "Choose a location". You can then click on the "Add" button and your query should appear in your location of choice.
Query Options
PocketQuery allows you to set different options for your queries. Double click on your query, or click on the downward arrows on the right of your query to see its options.
Query Name: Name of the target query defined by a PocketQuery administrator. All queries available are provided in the select box "Choose a query".
Query Location: Location of the target query to be defined in the "PocketQuery project settings". All locations available are provided in the select box "Choose a location".
Settings: Optional settings are the fields "Headline" and "Issue Types". If a headline is given it is displayed above the query result. You can leave this blank if you do not need any headline. If the filed "Issue Types" is given, the query will only be displayed at issues of one of the selected types. If left blank, the query will be displayed for all types.
Query Parameters: If the query selected above requires one or more parameters they can be set here. Several wildcards can be used as parameters (see below).
Dynamic Load: Make the contents of the query load asynchronously in the background (using Ajax). With this checked, the page load will not be delayed by the loading of the PocketQuery add-on. This will be a performance benefit, especially, if you have multiple PocketQuery add-ons in one issue.
Debug Mode: Shows debug information in the issue for error analysis.
The following wildcards can be given as parameters:
@username - the username of the current Jira user
@userfullname - the full name of the current Jira user
@useremail - the email address of the current Jira user
@issue.id - the ID of the current Jira issue
@issue.summary - the summary of the current Jira issue
@issue.description - the description of the current Jira issue
@issue.status.id - the ID of the current Jira issue status
@issue.status.name - the name of the current Jira issue status
@project.key - the key of the current Jira project
@project.name - the name of the current Jira project
@issue.assignee - the username of the current Jira issue assignee
@issue.assignee.name - the username of the current Jira issue assignee
@issue.assignee.email - the email address of the current Jira issue assignee
@issue.reporter - the username of the current Jira issue reporter
@issue.reporter.name - the username of the current Jira issue reporter
@issue.reporter.email - the email address of the current Jira issue reporter
@issue.duedate - the due date of the current Jira issue
@issue.resolutiondate - the resolution date of the current Jira issue
@issue.cf_{CUSTOM FIELD ID} - the value of a custom field. You need to specify the ID of your custom field. (e.g. "@issue.cf_12345")
These wildcards will be replaced with their actual value before the query is executed.
For users that are not logged into Jira @username, @userfullname and @usermail will return "anonymous".
Dynamic Load
If the option "Dynamic Load" is enabled the issue containing the PocketQuery will not have to wait for the PocketQuery data to be loaded. Instead, the page will completely load first and PocketQuery will fetch its data in the background, showing a loading icon in the meantime.
This will be a tremendous performance improvement if your results are comprising in size.