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 for configuration:
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 | Full name of the class that implements the WebWork action. Actions in JIRA must extend the class 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 only allow access to certain web actions 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 3 4 5 6 7
<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.
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
<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>