Bamboo API Changes for Bamboo 3.0

General Notes

There have been two major features in Bamboo 3.0, Artifact Passing and the new plan/result UI. Both of these have required some core code changes which may affect your plugins.

• As part of the Artifact Passing work, we have moved artifact definitions out of the buildDefinition xml, and they have become an entity in their own right. This has resulted in many API changes around artifacts. Storage of artifacts has also been moved (to a different directory structure).
• The UI work we did may affect the rendering of your pages inside Bamboo, particularly on the Plan, Job and Result views.
• We have moved to AUI Forms which will alter the layout of any form fields your plugin provides
• We have also continued down the path started in 2.7 in removing from Build specific interfaces in favour of the more generic Plan interfaces.
• Several methods/classes deprecated in 2.7 have been removed in 3.0.

Below you can find the details of all the changes we have made, and suggested workaround/replacements. If there is anything that we have missed please let us know.

Changed Classes/Methods

ConfigurablePlugin

Methods on the ConfigurablePlugin interface have been changed from

ConfigurablePlugin.java

1
2
/**
 * Extension point for adding/customizing requirements when editing a build's builder configuration.
 *
 * @param buildConfiguration source of information for customizing build requirements
 * @param requirementSet     requirements to be customized
 */
void customizeBuildRequirements(@NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet);

/**
 * Extension point for removing requirements when given plugin is excluded from build's builder configuration.
 *
 * @param buildConfiguration source of information for customizing build requirements
 * @param requirementSet     requirements to be customized
 */
void removeBuildRequirements(@NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet);

to

ConfigurablePlugin.java

1
2
/**
 * Extension point for adding/customizing requirements when editing a build's builder configuration.
 *
 * @param planKey            key of {@link Plan} for which requirements has to be removed.
 * @param buildConfiguration source of information for customizing build requirements
 * @param requirementSet     requirements to be customized
 */
void customizeBuildRequirements(@NotNull PlanKey planKey, @NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet);

/**
 * Extension point for removing requirements when given plugin is excluded from build's builder configuration.
 *
 * @param planKey            key of {@link Plan} for which requirements has to be removed.
 * @param buildConfiguration source of information for customizing build requirements
 * @param requirementSet     requirements to be customized
 */
void removeBuildRequirements(@NotNull PlanKey planKey, @NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet);

This should be a painless change if your plugin extends BaseConfigurablePlugin, where default implementation calls old methods (see below) however, these old methods are deprecated so you should not rely on them in the future.

BaseConfigurablePlugin.java

1
2
public abstract class BaseConfigurablePlugin extends BaseBuildConfigurationAwarePlugin implements ConfigurablePlugin
{
    public void customizeBuildRequirements(@NotNull PlanKey planKey, @NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet)
    {
        customizeBuildRequirements(buildConfiguration, requirementSet);
    }

    /**
     * @deprecated since 3.0 Use #customizeBuildRequirements(Plan, BuildConfiguration, RequirementSet)
     */
    @Deprecated
    public void customizeBuildRequirements(@NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet)
    {
    }

    public void removeBuildRequirements(@NotNull PlanKey planKey, @NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet)
    {
        removeBuildRequirements(buildConfiguration, requirementSet);
    }

    /**
     * @deprecated since 3.0 Use #removeBuildRequirements(Plan, BuildConfiguration, RequirementSet)
     */
    @Deprecated
    public void removeBuildRequirements(@NotNull BuildConfiguration buildConfiguration, @NotNull RequirementSet requirementSet)
    {
    }
}

Deprecated Classes

Deprecated Methods

Removed Classes/Methods

Build Working Directory API in SystemDirectory.java

Starting with version 2.6, Bamboo build working directory structure has changed. Unfortunately old API to access that directory has not been removed - both old style access via SystemDirectory class and new style access via BuildDirectoryManager were still available. Only the new API guaranteed proper behaviour in all cases. With Bamboo 3.0, we've dropped the methods for build directory retrieval from SystemDirectory. Please use BuildDirectoryManager methods instead.

BuildManager

BuildManager was deprecated in 2.7 and dropped in 3.0.

In order to retrieve Plan information use the PlanManager. In order to retrieve result information use the ResultsSummaryManager for database cached BuildResultsSummaries and BuildResultsSummary.getExtraBuildResultsData() to retrieve the ExtraBuildResultsData (aka BuildResults) from XML file. If the methods you require are not yet on the ExtraBuildResultsData class, check whether or not you can get the information from the BuildResultsSummary if not, you can call Narrow.to(x, BuildResults.class) to retrieve the deprecated BuildResults object (If you need to do this, please raise an issue to let us know).

Methods on BuildPlanDefinition and BuildDefinition

The following methods have been removed from the BuildPlanDefinition and the BuildDefinition interfaces:

BuildPlanDefinition.java

1
2
@Nullable
Collection<Artifact> getArtifactDefinitions();

BuildDefinition.java

1
2
/**
 * Get the custom {@link Artifact}s.
 *
 * @return The collection of artifacts, null, if the build does not have any artifacts
 */
Map<String, Artifact> getArtifacts();

/**
 * Add a new artifact to the existing build artifacts
 *
 * @param artifact
 */
void addArtifact(Artifact artifact);

/**
 * Replace the build's artifacts with these ones.
 *
 * @param artifacts
 */
void setArtifacts(Map<String, Artifact> artifacts);

Please use the ArtifactDefinitionManager to access a Plan's Artifacts.

REST Changes

/build REST endpoint has been removed, please use /result instead. Expand parameters have also been changed from builds.build to results.result

New Plugin Points

Ability to add Tabs to the Bamboo Dashboard

A new web-section has been made available allowing you to add a Web Item Module (tab) on to the Bamboo dashboard. 

Support for Web Panels

Bamboo now provides support for Web Panels. Web Panels allow you to provide arbitrary snippets of HTML to be inserted into a page. There are currently only a few locations available to place these panels, however, we hope to increase this list soon.

*All the locations above are available since 3.0

You can find information on how to use these on the Web Panel Module page.

Build Trigger Condition Module

A new plugin point has been added to provides the ability to gate whether a build should be triggered or not. It uses a preference system so multiple trigger condition plugins can be used to determine the desired result. A build which fails the trigger condition will not be executed, there will be no trace of the existence of this build. For more information on how to create a Trigger Condition Plugin see: Build Trigger Condition Module

Miscellaneous

Context Aware Navigation

In Bamboo 3.0 we have added the Plan Navigator. When moving between Jobs and the Plan (as well as Job Results and Plan Results), the navigator remembers our context i.e. which tab you are on and will attempt to keep you on the same tab. If your plugin UI exists in a location which has the Plan Navigator, you may want to manually define where the Plan Navigator takes you. You can do this via extra properties in you XWork Plugin Module definition. You can find more information on the XWork Plugin Module page.

Changes to Bamboo's Page Decorators

Bamboo will decorate any actions that are part of your plugin. Previously, this decoration usually only provided, for example, the header and footer. In Bamboo 3.0 some decorators are providing a lot more, which will hopefully make the life of the plugin developer easier. Because of these changes you might find some of your pages are displaying strangely. This will mainly effect pages which display a tab menu (Plan, Job, Plan Result, Job Result). Now everything outside the tab content will be provided by the decorator, meaning your plugin only needs to supply the content to go inside the tab.

You will need to ensure your plugins are using the correct decorator, remove any excess html from your plugin which is no longer needed (because the decorator is supplying it) and define which tab will be selected on your page.

You can find more details on using the decorators on the XWork Plugin Module page.

Changes to Form Layout (AUI Forms)

We have changed Bamboo's forms from those old blue background panels, to the Atlassian Standard. The will affect the layout of any forms you might have in your plugins. If you were already using the webwork templates for form elements (e.g. [BAMBOO:@ww.textField .../]) there should be no code changes required. However you might want to assess whether your forms still look good and re-address any custom styling you may have put in place.

If you are not using the built in templates for form elements you will need to use AUI styling to get your forms to match. You can find information and examples about using AUI Forms at Add a Form to Your Plugin.

One thing which is not clear in that documentation is form field lengths. The standard field length is now much shorter than before and if you wish to alter the field lengths you can do so using the cssClass param. The available options are: long-field, medium-field (default), short-field e.g:

1
2
[@ww.textfield labelKey='setup.install.build.directory' name="buildDir" required="true" cssClass="long-field" /]