WebWork

Purpose of this Module Type

A WebWork plugin module defines a URL-addressible action, allowing Jira's user-visible functionality to be extended or partially overridden.

Configuration

The root element for the WebWork plugin module is webwork1. It allows the following attributes and child elements:

Attributes

1
2
<component-import key="appProps"
interface="com.atlassian.sal.api.ApplicationProperties"/>

Elements

<action> Element Attributes

<action> Element Elements

Example

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.

Sample Code

• The Jira sample plugin shows how to display the project leads in each project Administrator's page
• The WebWork Sample plugin contains many simple examples of using WebWork actions

Notes

• Renderable Views

  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.

• 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. 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>
  

• @SupportedMethods annotation (since 9.0.0)

  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.