Updating JIRA Plugins for JIRA 4.1

On this page:

Plugin Developer Notes

JIRA 4.1 introduces several changes that may break existing plugins. If you are using a plugin that is not shipped with JIRA, the plugin may need to be updated to work with JIRA 4.1. If the plugin was written by you, please read through the information below and see if any of it is relevant to your plugin. If you are using a plugin written by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.1.

Please note that this is not the complete list of changes for JIRA 4.1; it is just the changes that plugin developers are likely to encounter most often.

Dashboard API changes

The PortletConfigurationStore has had the following method renamed in JIRA 4.1:

• old name (introduced in JIRA 4.0): addLegacyGadget
• new name (changed in JIRA 4.1): addLegacyPortlet

In JIRA 4.1 the PortalPage interface has also been updated to become a final concrete class. The PortalPageImpl has been removed. Instances of the PortalPage final class can now be constructed using the PortalPage.Builder class. If your plugin was using the PortalPage interface it will need to be re-compiled against JIRA 4.1 to use the new PortalPage class.

Issue Operation module type is no longer available

The IssueOperation module type, which allowed plugin developers to add their own links to the "Issue Operations" list on the "View Issue" screen, is no longer available. In JIRA 4.1+ any plugin that needs to add a new issue operation to the "View Issue" page will need to be updated to use a Web-Item module instead.

So for example to convert the existing "Edit Issue" operation you would have to change the following plugin defintion:

    <issue-operation key="edit-issue" i18n-name-key="admin.issue.operations.plugin.edit.issue.name" name="Edit this issue" class="com.atlassian.jira.issue.operations.EditIssueOperation" state='enabled'>
        <resource type="velocity" name="view" location="templates/plugins/operations/editissue.vm" />
        <order>80</order>
    </issue-operation>

...to be a Web-Item:

            <web-item key="edit-issue" i18n-name-key="webfragments.view.issue.opsbar.operations.top.edit" name="Edit this issue" section="operations-top-level" weight="1">
                <label key="common.words.edit"/>
                <tooltip key="admin.issue.operations.plugin.edit.issue.name"/>
                <link linkId="edit-issue">
                    /secure/EditIssue!default.jspa?id=${issue.id}
                </link>
                <condition class="com.atlassian.jira.plugin.webfragment.conditions.IsIssueEditableCondition"/>
                <condition class="com.atlassian.jira.plugin.webfragment.conditions.HasIssuePermissionCondition">
                    <param name="permission">edit</param>
                </condition>
                <condition class="com.atlassian.jira.plugin.webfragment.conditions.ContextContainsCondition" invert="true">
                    <param name="context-key">display-context</param>
                    <param name="context-value">view-issue</param>
                </condition>
            </web-item>

The backing EditIssueOperation class required previously by the Issue Operation Module is no longer required.

Issue Operation Web-Items need to be added to an appropriate Web Section. The default structure for the issue operation sections is as follows:

• web-section key="opsbar-operations" name="Ops Bar Operations Section" location="view.issue.opsbar"
  • web-section key="operations-top-level" name="Ops Bar Operations Top level Section" location="opsbar-operations"
  • web-section key="operations-work" name="Ops Bar Operations Work Section" location="opsbar-operations"
  • web-section key="operations-attachments" name="Ops Bar Operations Attachments Section" location="opsbar-operations"
  • web-section key="operations-voteswatchers" name="Ops Bar Operations Votes & Watchers Section" location="opsbar-operations"
  • web-section key="operations-subtasks" name="Ops Bar Operations Subtask Section Section" location="opsbar-operations"
  • web-section key="operations-operations" name="Ops Bar Operations Operations Section Section" location="opsbar-operations"
  • web-section key="operations-delete" name="Ops Bar Operations Delete Section Section" location="opsbar-operations"

This structure gives the following default menu:

Plugin developers can add an issue operation web-item to any of the default menu sections, or define their own menu web-section and add it there.

IssueService should be used for performing issue operations

JIRA 4.1 introduces a new IssueService for performing operations (e.g. create/read/update/delete) on issues, which makes it much easier to perform issue operations from within a plugin. Plugin developers are strongly encouraged to change their plugins to use the new IssueService. The existing "back-end Actions" (e.g. ISSUE_UPDATE, ISSUE_DELETE) have been deprecated in favour of the new IssueService and may be removed in future releases of JIRA. The IssueManager class should also no longer be used directly to create or retrieve issues, as the new IssueService provides more robust validation and error handling.

For more information please see the detailed documentation on the IssueService.

User & Date Customfields

With the new View Issue page in JIRA 4.1, Date and User fields are grouped together in their own sections.

In order for Customfields to be placed in either section, their implementation of CustomFieldType must also implement either DateField or UserField.

/**
 * A marker interface to mark all date fields available in the system.  Please note that for custom fields, the
 * custom field type needs to be marked by this interface.
 *
 * @since v4.0
 */
public interface DateField
{
}

/**
 * A marker interface to mark all user fields available in the system.  Please note that for custom fields, the
 * custom field type needs to be marked by this interface.
 *
 * @since v4.0
 */
public interface UserField
{
}

Form Token Handling

JIRA 4.1 employs a new token authentication mechanism, which is used whenever JIRA actions are performed either through link request or form submission. This provides JIRA with the means to validate the origin and intent of the request, thus adding an additional level of security against cross-site request forgery. While the core JIRA product and its bundled plugins use this token handling mechanism by default, non-bundled plugins or those developed by third parties may not.

Therefore, if you are a JIRA plugin developer, please refer to the Form Token Handling documentation for details on how to incorporate this token handling mechanism into your JIRA plugin.

If you choose to implement form token handling into your JIRA plugin, please be aware of the following points:

• Any functions that use screen scraping, such as the 'create sub-task' function in FishEye, will be broken.
• REST API end points will not be affected unless they use form encoding.

JIRA 4.1 Early Access Program (EAP)

Pre-release versions of JIRA 4.1 can be downloaded from our main Atlassian website or from one of the links below.

JIRA plugin developers and other interested parties can download and install these pre-release versions to:

• Help update plugins for JIRA 4.1 compatibility and
• Check out JIRA 4.1's new features.

You can download one of the following pre-release JIRA beta distributions that best suits your needs:

• JIRA 4.1.0-beta Enterprise - WAR/EAR (TAR.GZ Archive)
• JIRA 4.1.0-beta Enterprise - WAR/EAR (ZIP Archive)
• JIRA 4.1.0-beta Enterprise - Standalone (ZIP Archive)