Updating JIRA Plugins for JIRA 4.2

JIRA 4.2 Upgrade Guide

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

On this page:

Plugin Developer Notes

JIRA 4.2 introduces several changes that may break existing plugins which are not bundled with JIRA.

If you are using or have been involved in the development of such a plugin, it may need to be updated to work with JIRA 4.2. Please read through the information below to see if any of this content is relevant to your plugin.

If you are using a plugin developed by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.2.

This is not the complete list of changes for JIRA 4.2 — It only describes changes in JIRA 4.2 that will impact plugin developers.

Custom fields that require JavaScript

Use the following pattern to execute JavaScript when dialogs are loaded. The dialogContentReady event is fired after the dialog boxes are loaded. This pattern is mainly useful when adding behaviour to, or interacting with, custom fields/forms.

AJS.$(function () {

    function initMyCustomField(dialog) {
        AJS.$(dialog || document.body).each(function () {
            var $dialog = AJS.$(this);

    // Init the control on DOM ready

    // Bind the init function so it runs when the dialog loads
    AJS.$(document).bind("dialogContentReady", function (e, dialog) {


Custom fields that directly implement GroupSelectorField

To address JRA-20562, the GroupSelectorField marker interface (typically used for User and Group Picker-based custom fields), has been changed to an interface with the following method:

Query getQueryForGroup(final String fieldID, String groupName);

The intention of this method is to return a query that takes into account any case folding that has been done by the underlying custom field type. For instance, JIRA appends _raw to the field id before indexing GroupSelectorField objects. Hence, if you want similar behaviour in your custom field, you would define the following (as used within JIRA):

    public Query getQueryForGroup(final String fieldID, String groupName)
        return new TermQuery(new Term(fieldID+"_raw",groupName));

Custom Issue Operations need to work without an issue being present

JIRA 4.2 permits the use of keyboard shortcuts for custom issue operations on the Issue Navigator. To do this, we render on an Issue Navigator page (but hide from the user) all issue operation links defined in the system, without a specific issue being available in the context for the issue operation. Custom issue operations must be able to gracefully handle this scenario, or they will be ignored from this list and plugin developers will not be able to attach keyboard shortcuts to their issue operations.

Specifically, issue operation web-items need to handle the case where the JiraHelper does not provide an issue in its context!

Furthermore, issue operation URLs need to follow a specific format in order for keyboard shortcut actions to be attached to them via JavaScript. Here is an example of a valid issue operation URL format:

<a id="assign-issue" class="issueaction-assign-issue" href="/jira/secure/AssignIssue!default.jspa?id={0}&returnUrl=/secure/IssueNavigator.jspa"></a>

The corresponding issue operation web-item definition looks as follows:

<web-item key="assign-issue" name="Assign Issue Link" section="operations-top-level" i18n-name-key="webfragments.view.issue.opsbar.operations.top.assign" weight="5">
    <label key="common.words.assign"/>
    <tooltip key="admin.issue.operations.plugin.assign.issue.name"/>
    <link linkId="assign-issue">
    <condition class="com.atlassian.jira.plugin.webfragment.conditions.HasIssuePermissionCondition">
        <param name="permission">assign</param>
    <condition class="com.atlassian.jira.plugin.webfragment.conditions.IsIssueEditableCondition"/>
    <condition class="com.atlassian.jira.plugin.webfragment.conditions.IsFieldHiddenCondition" invert="true">
        <param name="field">assignee</param>

The important part of the Issue Navigator URL is the parameter id={0}. The Issue Navigator will automatically substitute the $issueId variable with {0}. This will then be substituted by the JavaScript triggered by a keyboard shortcut with the currently selected issueId on the Issue Navigator.

On the issue view page, which only deals with a single issue, the $issueId will simply be substituted with the current issue id. The webwork action or servlet (in this case AssignIssue) needs to use the id URL parameter to resolve the issue.

Last modified on Sep 1, 2010

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.