Confluence Fields plugin for Atlassian JIRA

Please watch introduction video to see what this addon can do for you.

Every Confluence Field custom field that you create in your JIRA application should be configured. Below is a sample configuration dialog screenshot:

images/wiki/download/attachments/44696004/configuration.png
Configuration Dialog
  • Confluence

In case that your JIRA is linked to multiple Confluence instances you may use the Confluence field to specify the instance that you want to provide data for your custom field. By default it will use the primary Confluence instance.

  • Filter

You may specify CQL (Confluence Query Language) clause to filter Confluence pages according to your requirements. The clause will be applied to every query that your JIRA executes. For example, if you set your field’s filter value to space=”DS” and label=”client” and type mesilat while editing the custom field, than the resulting CQL-query will be type=”page” and title~”mesilat” and space=”DS” and label=”client”. The field’s dropdown control will list only those Confluence pages that match this query.

  • Test

Use this field to test your Confluence connection and your CQL-filter validity. If your JIRA is authorized to call the Confluence instance’s API and your filter is valid than you will get a list of Confluence pages that match your query. The test field behaves exactly the same way as your custom field when you edit a JIRA issue.

If your JIRA is not authorized by Confluence than you will get an error:To fix the error please follow the link provided in the message to start the OpenID “dance” and authorize your JIRA. It should be noted that authorization is individual for every JIRA user.

images/wiki/download/attachments/44696004/authorization-error.png
Authorization Error

If your filter CQL is invalid you will get a syntax error:Refer to Confluence documentation (or use the link provided above) to fix the error.

images/wiki/download/attachments/44696004/syntax-error.png
CQL Syntax Error

Substitution Variables

It is possible to reference other fields in your JIRA issue in your CQL filter. The addon currently supports referencing text fields and selects. To reference a text field you would use a substitution variable, for example ${customfield_10000} where customfield_10000 is JIRA identifier of your text field.

To reference a select field value you would use a .value suffix to your substuitution variable, for example ${customfield_10000.value}.

images/wiki/download/attachments/44696004/configuration-2.png
Configuration Dialog

Testing your CQL filter that uses substitution variables will not work but you may temporarily replace the variables with constant values and revert when you are done.

Other useful substitution variables are ${id} for issue id and ${key} for issue key, as well as project-related variables ${project.key}, ${project.name}, ${project.projectTypeKey} and ${project.projectCategory.name}. You may find more substitution variables by browsing JIRA API at <jira home>/plugins/servlet/restbrowser#/resource/api-2-issue-issueidorkey (you may need to install REST API Browser plugin).

  • Select Multi

By default Confluence field will take multiple values (multi-select). You may choose to restrict it to just one value by unchecking this checkbox.

  • Auto Filter

Auto filter option is only meaningful when you use substitution variables referencing other issue fields. If this option is checked and the field you reference in your substitution variable changes value, then your Confluence field will be automatically tested against resulting CQL. If the fields’ value does not match the CQL, then the field will be automatically cleared. If the field is a multi-select, then values that do not match the CQL will be removed, while values that do match will be preserved.

  • As Definer

By default JIRA will query Confluence using current user’s credentials. In some cases (such as JSD Customer Portal) it is desirable to use the administrator’s credentials instead. Check this checkbox to enable JIRA to query Confluence using the custom field definer’s credentials.

images/wiki/download/attachments/44696004/configuration-3.png
Configuration Dialog
  • Project-Specific Settings

You may want to override global Confluence field settings with project-specific settings. To define project-specific settings for a Confluence field please navigate to JIRA project settings page, select Fields then click Configure Confluence field link.

images/wiki/download/attachments/44696004/configuration-4.png
Configuration Link