Support for Server products ended Feb. 15, 2024. Learn what this means for you.

XWork plugin module

Available:	Bamboo 1.0 and later
Changed:	Bamboo 3.0 added context aware navigation and decorators, both described below.

Description

Each XWork module is deployed as a plugin module of type xwork and contains one or more XWork package elements. The XWork plugin module allows you to define your own XWork package and actions that you can access.

To build the action into the system, you will typically need to add a Web Item Module to link to your action.

Below is an example atlassian-plugin.xml file containing a single XWork module.

Sample Module Descriptor Element

1
2
<xwork key="viewCloverResult" name="View Clover Result">
    <package name="cloverPlugin" extends="buildView">
      <action name="viewCloverResult" class="com.atlassian.bamboo.build.ViewBuildResults">
        <result name="success" type="freemarker">/plugins/clover-plugin/viewCloverResult.ftl</result>
        <result name="error" type="freemarker">/error.ftl</result>
      </action>
    </package>
  </xwork>

Available:

Bamboo 3.0 and later

Only applicable to people adding web items to Plan/Job/Result tabs

Some pages in Bamboo have a Plan Navigator. When moving between Jobs and the Plan (as well as Job Results and Plan Result), the navigator remembers our context i.e. which tab you are on and will attempt to keep you on the same tab. There is some default behaviour available to determine which page to navigate to (and hence which tab), however, if you would like your plugin to dictate exactly where to go, you can manually define the corresponding page to navigate to via your xwork action definition.

For each xwork action you can define the jobEquiv and chainEquiv parameters. The chainEquiv will be used when navigating to the Plan (or Plan Result), the jobEquiv when navigating to the Job (or Job Result). Note that even though you are already on a Job level page, you can set the jobEquiv to be something different for other Jobs in the Plan.

You can use the markers ${planKey} and ${buildNumber} as place holders in the equivalent URL.

Examples:

1
2
<action name="viewChainAuditLog" class="com.atlassian.bamboo.ww2.actions.chains.admin.ViewChainAuditLog">
  <param name="jobEquiv">/build/admin/edit/editBuildDetails.action?buildKey=${planKey}</param>
  <param name="chainEquiv">chain/admin/config/viewChainAuditLog.action?buildKey=${planKey}</param>
  <result name="success" type="freemarker">/chain/edit/viewChainChangeHistory.ftl</result>
</action>

1
2
<action name="viewBuildResultsSuccessfulTests" class="com.atlassian.bamboo.build.ViewBuildResultsSuccessfulTests">
  <param name="chainEquiv">/browse/${planKey}-${buildNumber}/test</param>
  <param name="jobEquiv">/browse/${planKey}-${buildNumber}/test</param>
  <result name="success" type="freemarker">/build/result/viewBuildResultsSuccessfulTests.ftl</result>
  <result name="error" type="freemarker">/error.ftl</result>
</action>

If Bamboo can not figure out where to take the user, it will default to the first tab on the page.

Using Bamboo's Decorators

Available:

Bamboo 3.0 and later

Bamboo will decorate any HTML returned by your action. In most cases this will just be the Header and Footer, however there are a few decorators which do much more than this. There are two ways to control the decoration occurring on your page.

URL Mapping - Each decorator is mapped to a specific URL pattern, if your action URL matches that pattern it will use that decorator.

Manual Specification - If your action URL does not match the required pattern, you will need to manually define which decorator you want Bamboo to use.

1
2
<head>
    <meta name="decorator" content="<decorator-name>">
</head>

Available Decorators

Decorator Name	Notes
`plan`	For Plans and Job, provides Breadcrumbs, Plan Navigator and Tab menu Default URL Mappings: <pattern>/build/.action</pattern> <pattern>/chain/.action</pattern>
`result`	For Plan Results and Job Results, provides Breadcrumbs, Status Ribbon, Plan Navigator and Tab menu Default URL Mappings: <pattern>/chain/result/.action</pattern> <pattern>/build/result/.action</pattern>
`atl.admin`	For Administration Pages, provides Admin menu Default URL Mappings: <pattern>/admin/*.action</pattern>
`atl.general`	The default decorator (Header + Footer only) Default URL Mappings: Everything
`none`	Will not provide any decoration

Tabs and Decorators

If the decorator is providing a row of tabs to your page, you will need to manually define on their page which tab is selected as follows:

1
2
<head>
    <meta name="tab" content="<web-item-name>"/>
</head>

OGNL Class Allowlist

Available:

Bamboo 11.0 and later

The Struts web framework is underpinned by an expression language technology known as OGNL. Historically, the OGNL technology has been the source of numerous critical vulnerabilities. Atlassian has developed a number of security measures to protect against the reoccurrence of such vulnerabilities.

One such measure is the OGNL class allowlist. The allowlist is a list of classes that are permitted to be used in OGNL expressions. The allowlist comprises classes from the following sources:

Pre-defined list of classes, designated as safe by Atlassian and Struts
Classes defined as an Action or other Struts package component in a XWork module.
Classes returned by an Action class getter, annotated with @StrutsParameter
Classes listed in struts.allowlist.classes in a XWork module
Classes belonging to a package listed in struts.allowlist.packages in a XWork module

Generally, defining your Struts package components in a XWork module descriptor and annotating all your Struts parameters with @StrutsParameter will be sufficient to allow your plugin to function as expected. However, some Struts functionality may require additional classes to be added to the allowlist. Please observe the log output for warnings and add classes to the allowlist as appropriate. Plugins usually only need to allowlist model or DTO classes.

Avoid allowlisting classes which contain privileged or dangerous members. Examples of a privileged member may be a method which writes to disk or performs some administrative task. Such members should be defined in a class that is not allowlisted and outside your Action class which is allowlisted by default.

1
2
<xwork name="security-struts" key="securityStruts">
    <constant name="struts.allowlist.classes" value="com.plugin.MyDtoClass" />
    <constant name="struts.allowlist.packages" value="
                                                      com.plugin.dto,
                                                      com.plugin.model
    "/>  
</xwork>

People using web items to add to the Plan/Job/Result tabs should use the plan or result decorator