variable in confluence jql issues macro

I am building a standard project dashboard for our development projects in Confluence. We use JIRA for tracking, essentially, ANYthing that moves during development. I would like to avoid, when building the template, having to manually create the JIRA queries common to all projects over and over but differing only, for example the JIRA key. With Bob Smith's help, I've been able to use page metadata values I've set to substitute search parameters in SQL queries to suck in project accounting information. I'd like to do the same with JIRA for a variety of issue displays in the dashboard. In detail:

I use the metadata 2 plugin to set page metadata values with the following:

{metadata-list}
| projectcode | A1234 |
| jirakey | BOBO |
{metadata-list}

In the SQL queries, I've been able to use:

select actual from gates where project_code = '{metadata-from:projectcode}' and gate = 'S4'

I want to do the same with the JQL queries; for example:

project = {metadata-from:jirakey} and status != closed

However, when I put this in the JIRA issues macro, It simply reads that as entered and, surprise surprise, the query doesn't work.

Any thoughts on how to use metadata (or any other kind of variable substitution) on an issue query made from Confluence?

3 answers

I figured since we solved this recently, i would add our official solution to this request which allows to inject any number of variables into any JQL filter in a Confluence Template.  Below is the how-to as well as some usage notes i wrote for our company:

First we start out with determining the current syntax of the JQL Issues/Filter macro in confluence:

  1. Install or Enabled the “Confluence Source Editor” plugin
  2. Create new page
  3. Add the JIRA Issue/Filter macro
  4. Use a simple basic query
  5. Click the “<>” button to view the source of the page.
  6. Copy the JIRA Issue/Filter macro syntax to a text editor, e.g.

    &lt;p&gt;
      &lt;ac:structured-macro ac:macro-id="5a45704b-a904-4440-bdc0-da68a22d5802" ac:name="jira" ac:schema-version="1"&gt;
        &lt;ac:parameter ac:name="server"&gt;JIRA&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="columns"&gt;key,summary,type,created&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="maximumIssues"&gt;20&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="jqlQuery"&gt;assignee = abarylak and resolution is EMPTY &lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="serverId"&gt;c8001771-0b52-30e0-9703-562a2820710f&lt;/ac:parameter&gt;
      &lt;/ac:structured-macro&gt;
    &lt;/p&gt;

Then we need to use the above syntax (a little modified) and use that for our macro.

  1. Create a macro with 2 parameters: maxRows, columns
  2. Remove the macro-id from the above syntax
  3. Modify the $body variable to remove unnecessary white space using trim() and html paragraph tags (see below)
  4. Inject the $body into the jqlQuery element in the above syntax
  5. NOTE: The “serverId” parameter may change server to server, so you must get that ID from your current server you want to deploy this to via the source editor plugin.
  6. Results are as follows:

    ## Macro title: JQL Filter Allowing Variables
    ## Macro has a body: Y
    ## Body processing: Rendered
    ## Output: JIRA Issues/Filter Macro w/ injected variables
    ##
    ## Developed by: Adam Barylak
    ## Date created: 2016-05-27
    ## Installed by: Adam Barylak
    
    
    ## This macro will prompt for max number of rows and the column option, then the body will require the JQL with injected variables
    ## @param maxRows:title=Max Rows|type=int|required=true|default=20|desc=Enter the max rows, anything above 1000 will only display 1000 rows.
    ## @param columns:title=Columns|type=string|required=true|default=key,summary,type,status,assignee|desc=Enter  the columns you want returned.  Must be separated by commas, all lowercase, and no quotes. e.g. key,summary,assignee,test author,reporter
    #set ($body = $body.replaceAll("\Q&lt;p&gt;\E",""))
    #set ($body = $body.replaceAll("\Q&lt;/p&gt;\E",""))
    #set ($body = $body.trim())
    &lt;p&gt;
    &lt;ac:structured-macro ac:name="jira" ac:schema-version="1"&gt;
        &lt;ac:parameter ac:name="server"&gt;JIRA&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="columns"&gt;$paramcolumns&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="maximumIssues"&gt;$parammaxRows&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="jqlQuery"&gt;$body&lt;/ac:parameter&gt;
        &lt;ac:parameter ac:name="serverId"&gt;c8001771-0b52-30e0-9703-562a2820710f&lt;/ac:parameter&gt;
    &lt;/ac:structured-macro&gt;
    &lt;/p&gt;

Create the macro in confluence with the following options or similar (change as needed):

  • Macro Name: jira_issue_filter_vars
  • Macro Title: JQL Filter Allowing Variables
  • Description: Insert entire JQL query in body of macro.  Inject template variables as needed.  If quotes needed around variable, insert variable first, then surround variable with quotes.
  • Categories: Reporting
  • Macro Body Processing: Rendered

How to use JQL Filter Macro in Template with Variables:

  1. Get your query working in JIRA in Advanced mode (text based) with your filter(s) for a single run.
  2. Copy advanced JQL text to notepad or clipboard.
    1. Notes for format:
      1.  Do not include any line breaks in the JQL
      2. Ensure all whitespaces are spaces and not tabs or other characters
      3. Ensure all special characters such as parenthesis or quotes are basic text (not the special characters sometimes used by MS Word or MS Outlook)
      4. If all else fails, manually re-type the JQL using temporary placeholders for the variables, then using the “$” keyboard command to place the variables into the JQL statement where necessary
  3. Create template in Confluence with any header level variables needed. (you can create variables with the gui, but using them later requires you to type $ then the variable name or copying and pasting.  If you use the UI again, it will add an additional $ sign to the variable therefore making it a new variable and it won’t work.)
  4. Add the “JQL Filter Allowing Variables” macro with appropriate options. (it is located in the Reporting category)
    1. Max Rows: only allows a max of 1000
    2. Columns: you may need to use a normal JIRA Issue macro and configure it with your specific columns, then view the source to determine the correct name of some fields.  However, the rule so far is that there are no spaces except what is in the field name, and all fields are lowercase, and not surrounded by quotes.  Examples of some fields: key, summary,related requirement/s,test case type,test author
  5. In the body of the macro, paste in your entire JQL query from step 2
    ConfMacro1.png
  6. Inject your variable or variables into the JQL.
    ConfMacro2.png
  7. If you need to include quotes around variable to support spaces in variable text, add them after injecting the variable(s) into the query.
    ConfMacro3.png
  8. Using this method you can inject multiple variables if needed.
    ConfMacro4.png
  9. Save your template and use as needed.

 

Hopefully this helps others accomplish this same task.  This ends up being really useful if you need to repeat a bunch of JQL filters for different things on different pages in Confluence and you don't have to store these filters as saved filters in JIRA either.

I haven't tried this, but here are a couple of suggestions:

  1. Try using the source editor to change the macro definition without having UI try to validate the query
  2. Perhaps you can use the wiki version of the JIRA macro if it supports what you need. If so, wrap it in a wiki macro and then you should be able to use substitutions

 

Thanks Bob. For the nonce, I had to get it the templates out the door and the JIRA queries are manually built by the person implementing the template. However, I've structured how the dashboards work so that they can be just killed and reapplied to the various projects when a new version is developed so I'll keep working on that. I did muck about a BIT with the storage editor and didn't have success but haven't exhausted all possiblities there yet. I did also look at your wiki macro, CLI, and scripting as possible vehicles to a solution. When I get this nailed, I'll post back the solution I find with your suggestions here. mike

I'd be very interested in the solution if you get this working. Thanks.

Found a solution that works: https://docs.servicerocket.com/display/REP/Injecting+Parameters+into+the+JIRA+Issues+Macro

 

The trick was to insert it as wiki markup. Hope this helps.

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted Oct 24, 2018 in Confluence

Atlassian Research opportunity with Confluence templates

Do you use templates with Confluence? Take part in a remote 1-hr workshop. You'll receive USD $100 for your time!   We're looking for people to participate in a   remote 1-hr workshop...

1,527 views 25 14
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you