Last updated Mar 13, 2024

Bamboo API Changes for Bamboo 2.7

Structure Changes

Bamboo 2.7 involves the introduction of Staged Builds.  Each Plan contains one or many stages, and each stage contains one or many Jobs.   This has involved significant back-end changes to accommodate this feature.  A Build used to be the core object of Bamboo.  This class is now deprecated and in its place are the Chain and the Job.  The functionality of the Build class has been split between these two classes and what the users now see as a "Plan" in the UI is represented by the Chain class.   

Logical Break Up Of Responsibilities During The Build:

Chain

Job

Source Repository For Change Detection
Build Strategy and Triggering
Notifications
Permissions

Source Repository For Checkout
Builder
Requirements/Agent Matching
Artifacts

You will notice in the above table that there is a repository configured for the Chain level and for the Job.   The Chain's repository is used for build triggering and reporting included changes for the Chain result.  The Job's repository is used for checking out the source code and reporting included changes for the job result.  To make maintenance of your plans easier, you can set up your jobs to inherit the repository of the chain, however, this should be transparent to your plugins.

Both the Chain and the Job extend the Plan interface and share the one database table. There have also been two common interfaces introduced to help deal with commonalities between the implementations (TopLevelPlan and Buildable).  As the Build class has now been deprecated most of Bamboo's internals have been updated, this includes managers and our plugin interfaces.   Each case is different, but you will find some methods now deal with Plan, TopLevelPlan or Buildable, others will deal directly with the Chain or Job, whilst others will happily deal with all 5, you just have to tell it which one your after.  When developing your plugin, if you are passed a common interface,  you will need to ensure that the operation you wish to perform is actually applicable to the specific implementation.

Jobs are grouped in a Chain by ChainStages. ChainStages have a specific order inside the Chain, whilst Jobs inside a ChainStages do not have any order. The diagrams below shows the relationships and hierarchy of the new classes (The Build object has been included in the diagram to help explanation)

As jobs are a child of the chain, the identification key of the job also includes the full key of the chain.  For example, a chain is represented by  "BAMBOO-TRUNK" whilst the job is "BAMBOO-TRUNK-UNITTESTS".

The structure of result objects follows the same pattern as the plans.  ChainResultSummary and BuildResultsSummary (Job) share the common interface ResultsSummary.  Job results are grouped by ChainStageResult.

The New Build Process

See: Bamboo's Build Process

Deprecated Classes

If any required functionality can not be found on the replacement classes please let us know.

Deprecated Class

Replacement

Build

Plan, TopLevelPlan, Buildable, Chain or Job

BuildManager

PlanManager

BuildResultSummaryManager

ResultsSummaryManager

BuildPlanConstructorFactory,
BuildPlanConstructor

There is no replacement for this, however the various implementations of the PlanCreationService may provide the required functionality

BuildResults

This class has been deprecated since 2.6. However, in 2.7 there is a new interface to access the few last bits an pieces left stored in these files. Specifically the ExtraBuildResultsData class provides you with the build return code and any build errors. The only reason to go to the BuildResults now, should be to get specific successful test results.  The ExtraBuildResultsData is accessible via BuildResultsSummary.getExtraBuildResultsData()

BaseCustomBuildCompleteAction

use the CustomBuildCompleteAction interface directly.

BuildIdentifierHelper

use the PlanKeys class instead

ExtendedBuildResultsSummary

BuildResultsSummary

Deprecated Methods

Deprecated Method

Replacement

BuildContext.getBuildPlanDefinition()

BuildContext.getBuildDefinition()

CurrentlyBuilding.getBuildTime()

CurrentlyBuilding.getElapsedTime()

DashboardCachingManager.getAllBuilds()

DashboardCachingManager.getAllTopLevelPlans()

Removed Classes

Removed Class

Notes

NotificationCondition

Deprecated since 2.2, The NoticationType module should be used instead.  See Building a Notification Plugin.

BuildPlanCreationService

There is no replacement for this, however the various implementations of the PlanCreationService or the PlanValidationService may provide the required functionality.DashboardCachingManager.getAllTopLevelPlans()

REST Changes

Build resource is replaced by Result resource.

The build resource has been deprecated, however is still operational. All new queries should use /result resource instead. Syntax remains the same.

Currently running builds are available by REST

Runtime information for running builds is available via REST now.  Not all result information is available while the build is running (for example, testResults information) so can not be returned in the REST response .  You will however be able to retrieve other valuable information such as progress of the build, commits and build logs (for Jobs only)

Chain result example:

1
2
http://localhost:8085/bamboo/rest/api/latest/result/CONF-CONFUNIT-6
1
2
<result id="2326529" number="6" lifeCycleState="InProgress" state="Unknown" key="CONF-CONFUNIT-6" expand="changes,metadata,stages,labels,jiraIssues,comments">
<link rel="self" href="http://localhost:8085/bamboo/rest/api/latest/result/CONF-CONFUNIT-6"/>
<buildStartedTime>2010-11-08T15:32:03.953+01:00</buildStartedTime>
<buildDurationInSeconds>0</buildDurationInSeconds>
<buildDuration>0</buildDuration>
<buildDurationDescription>Unknown</buildDurationDescription>
<buildRelativeTime/>
<vcsRevisionKey>132473</vcsRevisionKey>
<buildReason>Manual build</buildReason>
<stages size="1" max-result="1" start-index="0"/>
<labels size="0" max-result="0" start-index="0"/>
<jiraIssues size="1368" max-result="1368" start-index="0"/>
<comments size="0" max-result="0" start-index="0"/>
<changes size="3171" max-result="3171" start-index="0"/>
<metadata size="2" max-result="2" start-index="0"/>
<progress>
<isValid>true</isValid>
<isUnderAverageTime>true</isUnderAverageTime>
<percentageCompleted>0.2066399933736914</percentageCompleted>
<percentageCompletedPretty>20%</percentageCompletedPretty>
<prettyTimeRemaining>3 mins remaining</prettyTimeRemaining>
<prettyTimeRemainingLong>Approximately 3 minutes remaining</prettyTimeRemainingLong>
<averageBuildDuration>277681</averageBuildDuration>
<prettyAverageBuildDuration>4 mins</prettyAverageBuildDuration>
<buildTime>57380</buildTime>
<prettyBuildTime>57 secs</prettyBuildTime>
</progress>
</result>

Job result example

1
2
http://localhost:8085/bamboo/rest/api/latest/result/CONF-CONFUNIT-JOB1-6?expand=logEntries
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
<result expand="jiraIssues,changes,metadata,logEntries" id="2326530" number="6" lifeCycleState="InProgress" state="Unknown" key="CONF-CONFUNIT-JOB1-6">
<link rel="self" href="http://localhost:8085/bamboo/rest/api/latest/result/CONF-CONFUNIT-JOB1-6"/>
<chain rel="self" href="http://localhost:8085/bamboo/rest/api/latest/result/CONF-CONFUNIT-6"/>
<stage>Default Stage</stage>
<buildStartedTime>2010-11-08T15:33:33.168+01:00</buildStartedTime>
<buildDurationInSeconds>0</buildDurationInSeconds>
<buildDuration>0</buildDuration>
<buildDurationDescription>Unknown</buildDurationDescription>
<buildRelativeTime/>
<queueStartedTime>2010-11-08T15:32:02.399+01:00</queueStartedTime>
<queueTimeInSeconds>1</queueTimeInSeconds>
<queueDuration>1532</queueDuration>
<prettyQueueDuration>1 sec</prettyQueueDuration>
<vcsUpdateStartedTime>2010-11-08T15:32:03.931+01:00</vcsUpdateStartedTime>
<vcsUpdateInSeconds>89</vcsUpdateInSeconds>
<vcsUpdateDuration>89237</vcsUpdateDuration>
<prettyVcsUpdateDuration>1 min</prettyVcsUpdateDuration>
<vcsRevisionKey>132473</vcsRevisionKey>
<buildReason>Manual build</buildReason>
<hasExecutableAgents>true</hasExecutableAgents>
<jiraIssues size="1368" max-result="1368" start-index="0"/>
<changes size="3171" max-result="3171" start-index="0"/>
<metadata size="0" max-result="0" start-index="0"/>
<progress>
<isValid>true</isValid>
<isUnderAverageTime>true</isUnderAverageTime>
<percentageCompleted>0.11110951055347683</percentageCompleted>
<percentageCompletedPretty>11%</percentageCompletedPretty>
<prettyTimeRemaining>4 mins remaining</prettyTimeRemaining>
<prettyTimeRemainingLong>Approximately 4 minutes remaining</prettyTimeRemainingLong>
<averageBuildDuration>277681</averageBuildDuration>
<prettyAverageBuildDuration>4 mins</prettyAverageBuildDuration>
<buildTime>30853</buildTime>
<prettyBuildTime>30 secs</prettyBuildTime>
</progress>
<logEntries size="25" max-result="25" start-index="0">
<logEntry>
<log>[INFO]   Confluence Webapp with Cluster</log>
<unstyledLog>[INFO]   Confluence Webapp with Cluster</unstyledLog>
<date>2010-11-08T15:33:35.679+01:00</date>
<formattedDate>08-Nov-2010 15:33:35</formattedDate>
</logEntry>
<logEntry>
<log>
[INFO] ------------------------------------------------------------------------
</log>
<unstyledLog>
[INFO] ------------------------------------------------------------------------
</unstyledLog>
<date>2010-11-08T15:33:36.189+01:00</date>
<formattedDate>08-Nov-2010 15:33:36</formattedDate>
</logEntry>
<logEntry>
...
</logEntry>
</logEntries>
</result>

REST reflects internal structure of chains and jobs.

New expand points have been added for querying chain structure.

For example:

1
2
http://localhost:8085/bamboo/rest/api/latest/project/CONF?expand=plans.plan.stages.stage.plans.plan
1
2
<project name="Confluence" key="CONF" expand="plans">
<link rel="self" href="http://localhost:8085/bamboo/rest/api/latest/project/CONF"/>
<plans expand="plan" size="1" max-result="1" start-index="0">
<plan enabled="true" type="chain" name="Confluence - Confluence Unit Test" key="CONF-CONFUNIT" expand="actions,stages">
<projectKey>CONF</projectKey>
<projectName>Confluence</projectName>
<link rel="self" href="http://localhost:8085/bamboo/rest/api/latest/plan/CONF-CONFUNIT"/>
<isFavourite>true</isFavourite>
<isActive>false</isActive>
<isBuilding>false</isBuilding>
<averageBuildTimeInSeconds>277.0</averageBuildTimeInSeconds>
<actions size="7" max-result="7" start-index="0"/>
<stages expand="stage" size="1" max-result="1" start-index="0">
<stage expand="plans">
<name>Default Stage</name>
<description/>
<plans expand="plan" size="1" max-result="1" start-index="0">
<plan enabled="true" type="job" name="Confluence - Confluence Unit Test - Default Job" key="CONF-CONFUNIT-JOB1" expand="actions">
<projectKey>CONF</projectKey>
<projectName>Confluence</projectName>
<link rel="self" href="http://localhost:8085/bamboo/rest/api/latest/plan/CONF-CONFUNIT-JOB1"/>
<isFavourite>false</isFavourite>
<isActive>false</isActive>
<isBuilding>false</isBuilding>
<averageBuildTimeInSeconds>277.0</averageBuildTimeInSeconds>
<actions size="7" max-result="7" start-index="0"/>
</plan>
</plans>
</stage>
</stages>
</plan>
</plans>
</project>

Job key support

REST honours new key scheme, so Chain keys and Job keys may be used to address proper entity.

isInBuildQueue attribute of RestPlan has been replaced with isActive

Can now pass in plan type to many different queries.

1
2
type=chain|job|build

May be applied to all queries that list plans and results, so /project /plan /result

Test results

Test results information is available only for Job level results. Chain results contain only statistical test results information, so there is no testResults expand point.

1
2
expand=testResults.all|testResults.successful|testResults.failed|testResults.newFailed|testResults.existingFailed|testResults.fixed

May be applied to any Job result or chain result if properly expanded (for Chains it should be prefixed by stages.stage.results.result. )

Only one category of test results can be expanded at a time.

Other Changes

Plan Configuration Changes

In 2.7 Bamboo has lost its Plan Creation Wizard.  It now has a shortened one page form to create a new Plan.  Plugin configuration (except for Builders and Repositories) will not be available at creation time.  This should hopefully make writing these plugins easier as you no longer have to deal with both ways of creating configuration and there will always be a BuildDefinition and Plan object available to you.  

Also, the view of the plan configuration has also been reformatted to a simplified one-page view.  We encourage plugins, to limit the amount of space their view configuration takes up. And, if possible do not show anything if the plugin is not enabled (as opposed to showing "feature X is disabled")

There is also now a new tab on both the Plan and Job Configuration available for plugin developers to put their plugin configuration - the "Miscellaneous" tab.  To make use of this tab, use the Additional Build Configuration Plugin point and/or ensure you plugin class implements MiscellaneousBuildConfigurationPlugin interface.  You will notice that this interface actually provides you with the method isApplicableTo(plan). This method allows you to decide whether you plugin applies to Plans or Jobs or both.

To allow for the condensed creation page there is a new type of template (optional) on the Repository interface. This allows the UI to show the minimum required configuration on the creation page whilst allowing more advanced configuration after creating the initial plan.  If you are extending AbstractRepository, you can just provide the new template type in your plugin definition (see the example below).  If you don't supply the minimal template, the normal edit template will be used. If implementing the Repository interface directly you will need to implement the getMinimalEditHtml() method.

1
2
<repository key="svn" name="SVN Repository"
                     class="com.atlassian.bamboo.repository.svn.SvnRepository">
    <description>A Subversion Repository</description>
    <resource type="freemarker" name="edit" location="templates/plugins/repository/svnRepositoryEdit.ftl"/>
    <resource type="freemarker" name="view" location="templates/plugins/repository/svnRepositoryView.ftl"/>
    <resource type="freemarker" name="minimalEdit" location="templates/plugins/repository/svnRepositoryMinimalEdit.ftl"/>
  </repository>

Method Signature Changes

Base Configurable Plugin, Build Configuration Aware Plugin

Most plugin points which allow you to display content in Bamboo's UI, provide you with a getEditHtml() method to implement.  Many have base implementations inside Bamboo, so it may not effect you.  But, if you have specifically implemented/overridden this method in your plugin you will need to ensure that it properly handles a null plan argument

1
2
/**
    * Returns HTML that represents the form fragment for editing the plugin. No opening and closing form tags are
    * required.
    *
    * @param buildConfiguration BuildConfiguration for which edit HTML has to be rendered.
    * @param plan  Plan for which edit HTML has to be rendered.  May be null during creation phase of plan.
    * @return HTML string. May be null.
    */
   @Nullable
   String getEditHtml(@NotNull BuildConfiguration buildConfiguration, @Nullable Plan plan);

Build Complete Action Module

The CustomBuildCompleteAction interface has been updated to take in a Buildable instead of a Build inline with the new plan class hierarchy.  However we actually suggest you move away from using this plugin point (it can be prone to thread safety problems) and instead use the CustomPostBuildCompletedAction Post-Build Completed Action Module or the Build Processor Server Module.

1
2
/**
     * This action will run when a build completes.
     *
     * @param buildable - the Buildable plan object
     * @param buildResult - the BuildResults object that holds information
     */
    public void run(@NotNull Buildable buildable, @NotNull BuildResults buildResult);

Trigger Reasons

The TriggerReason interface (Trigger Reason Module) has been updated to take in a ResultsSummary instead of a BuildResultsSummary.  You will need to ensure any implementations of this will work with both Chains and Jobs.  Also, it should be noted that Jobs do not have their own Trigger Reason, they will inherit the trigger reason of their parent.

Web Repository Module

The WebRepositoryViewer methods have also been updated to accept a ResultsSummary instead of a BuildResultsSummary and therefore also needs to be updated to support Chains as well as Jobs.

Report Module

The ReportCollector interface has been updated to accept a ResultsSummary instead of a BuildResultsSummary and therefore also needs to be updated to support Chains as well as Jobs.

Notification Changes

Notification Type can now be scoped to determine where it can be configured.  There are three options (though poorly named):

  • Chain - For Plan level notifications
  • Plan - for Job level notifications
  • System - for global notifications (configured in the administration section of Bamboo)

If you don't provide a scope, it will default to a Job level notification. Also, note that whilst there are Job and Plan level notifications, they are both configured at the plan level.  Job notifications will generally apply to all jobs within the Plan.

Rate this page: