A WebWork plugin module defines a URL-addressible action, allowing Jira's user-visible functionality to be extended or partially overridden.
The root element for the WebWork plugin module is webwork1
. It allows the following attributes and child elements:
Name | Description |
---|---|
class | The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the module. For this module, it's fine to use Required: yes Default: - |
key | The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.
In the example, Required: yes Default: N/A |
i18n-name-key | The localisation key for the human-readable name of the plugin module. Required: - Default: - |
name | The human-readable name of the plugin module. I.e. the human-readable name of this module. This must be unique across all Jira add-ons. Required: - Default: The plugin key. |
roles-required | The roles-required attribute can be used to only allow access to certain web actions to users which have been granted certain permissions. See Notes for more information. Required: - Default: - |
Name | Description |
---|---|
description | A human-readable description of this WebWork module. May be specified as the value of this element for plain text or with the Required: - |
actions | Specifies WebWork 1 <action>s to define. Must contain at least one <action> element. Required: yes |
<action>
Element AttributesName | Description |
---|---|
name |
The full name of the class that implements the WebWork action.
Actions in Jira must extend the Required: yes |
alias | The path from which this action may be invoked in Jira. For example, an action with alias Required: yes |
roles-required | The roles-required attribute can be used to allow access to certain web actions only to users which have been granted certain permissions. See Notes for more information. Required: - |
<action>
Element ElementsName | Description |
---|---|
view | Directs where to send the user when the action completes. The Required: - |
Here is a sample WebWork plugin module that is placed in atlassian-plugin.xml:
1 2<webwork1 key="qquserissue" name="Quick Create User Issue" class="java.lang.Object"> <actions> <action name="com.atlassian.jira.toolkit.action.QuickCreateUserIssueAction" alias="QuickCreateUserIssue"> <view name="createuserissue">/templates/quickcreateuser.vm</view> </action> </actions> </webwork1>
WebWork plugins effectively extend the actions defined in the Jira WEB-INF/classes/actions.xml
file. You should look
there for examples of what is possible. There is also
a WebWork Sample plugin that contains
many other basic examples.
Use your own package for your action classes!
In the past, plugin authors could rely on a bit of magic: putting their action class in the
package com.atlassian.jira.web.action
was enough to have Jira find it without specifying the fully qualified class
name in <action name="">
. This was never a good idea, and in a Plugins2 plugin, it will simply not work. Always create
a separate package space for your code and stay out of the com.atlassian
namespace.
Make sure your template names are unique!
Your views are placed in a common pool, and Jira retrieves the first template that fully matches the path. If
there are two apps using the /templates/admin.vm
template, one of them will be hidden by the other.
Avoid complex inheritance!
You can override existing actions, but you can’t override an action that’s already been overridden. Jira's WebWork implementation can’t resolve polymorphic action hierarchies.
The value of <view>
should be a Velocity template;
in the above example, the template templates/quickcreateuser.vm
lives in the plugin artifact under that path. JSP
views cannot be used from inside plugins; they can be used if they are installed into the Jira webapp, but this
complicates installation, upgrading, and troubleshooting. Use Velocity if you can.
The roles-required attribute can be used to only allow access to certain web actions to users which have been
granted certain permissions. The permissions are the short names of com.atlassian.jira.security.Permissions
based
permissions, and will only work for global based permissions. The three that are most useful are "admin", "sysadmin"
, and "use".
You can add a roles-required attribute to the parent WebWork element, or to a child action element (or both!).
1 2<webwork1 key="reference-actions" name="Reference WebWork Action" class="java.lang.Object" roles-required="use"> <actions> <action name="com.atlassian.jira.dev.reference.plugin.actions.PreparedReferenceAction" alias="PreparedReferenceAction" roles-required="sysadmin"> <view name="success">templates/actions/prepared-reference-action.vm</view> </action> <action name="com.atlassian.jira.dev.reference.plugin.actions.ReferenceAction" alias="ReferenceAction"> <view name="success">templates/actions/reference-action.vm</view> </action> </actions> </webwork1>
Before Jira 9.0.0, all commands in WebWork actions handled all HTTP methods exactly the same.
Now, actions and action commands will support only explicitly specified methods.
The com.atlassian.jira.security.request.SupportedMethods
annotation specifies the methods that
an action or command will support.
If no annotation is present, only the POST
method will be accepted.
You can place annotations on the class and method levels, with annotations on the method level taking
precedence over the class level.
Additionally, multiple methods can be specified. For example:
1 2@SupportedMethods({RequestMethod.GET}) static class SampleAction extends JiraWebActionSupport { @SupportedMethods({RequestMethod.POST, RequestMethod.PUT}) public String doTest(){ return INPUT; } }
SampleAction.jspa
and SampleAction!default.jspa
will work only for GET
requests.
SampleAction!test.jspa
will work for POST
and PUT
requests.
If the action is called with an unsupported method, the server will return the “405 Method Not Allowed” HTTP response code.
Rate this page: