Bamboo Event Listeners

Available:

Bamboo 2.2 and later

Changed:

Bamboo 3.1 added the ResultLabelAddedEvent, ResultLabelRemovedEvent, PlanFavouriteAddedEvent and PlanFavouriteRemovedEvent events.
Bamboo 4.0 added the BuildCommentDeletedEvent, FailedStageRestartEvent, ManualStageResumedEvent, StoppedOnManualStageEvent events.
Bamboo 4.1 added the PlanSuspensionRequestedEvent event.
Bamboo 4.2 added the MultipleJobsDeletedEvent and MultipleChainsDeletedEvent events.

On this page:

Description

The Bamboo Event Listener module allows developers to register an event listener against any event that is currently thrown in Bamboo and perform arbitrary operations. Some examples include sending off notifications or terminating a build when it hung.

It would be wise to note that currently Bamboo does not support using Atlassian Event 2.x listeners or events from this extension type.

Interface

All event listener modules implement the com.atlassian.event.EventListener interface or alternatively the com.atlassian.bamboo.event.HibernateEventListener which will automatically provide you with a hibernate session to access to the database (required for writing notification plugins).

Sample Module Descriptor Element

<bambooEventListener key="buildHungNotificationListener" name="Build Hung Notification Listener"
               class="com.atlassian.bamboo.notification.buildhung.BuildHungNotificationListener">
    <description>Listens for if a build has hung.</description>
</bambooEventListener>

Example Event Listener

In the example below the CustomerListener class implements HibernateEventListener. By overriding the getHandledEventClasses method you can filter which events this listener will handle. In this case it the BambooErrorEvent event. In the handleEvent method the code checks the event to ensure it is an instanceof the BambooErrorEvent. In this example it is redundant since it should only be the BambooErrorEvent due to the implementation of the getHandledEventClasses method. However, if the class were implemented to listen for multiple events then the check using instanceof for each event would be necessary.

Example Event Listener
public class CustomListener implements HibernateEventListener {

    @Override
    public Class[] getHandledEventClasses() {
        return new Class[]{BambooErrorEvent.class};
    }

    @Override
    public void handleEvent(Event event) {

        if (event instanceof BambooErrorEvent) {
            BambooErrorEvent errorEvent = (BambooErrorEvent) event;

            ErrorDetails details = errorEvent.getErrorDetails();
            // do something with ErrorDetails
        }
    }
}

Available Events to listen to

There is a number of events currently available in Bamboo. Each event contains information regarding the context in which it was thrown.

Event

Notes

AgentConfigurationUpdatedEvent

Occurs when a specific agent is updated (e.g the agent has been create or disabled)

AgentOfflineEvent

Occurs when a specific agent goes offline

AllAgentsUpdatedEvent

Occurs if there is an update that will effect all agents e.g. disabling/enabling all agents or updating capability sets

BambooErrorEvent

These are any errors generated by the Bamboo system. These are the same errors which are displayed as System Errors in the Bamboo UI. This may include failing checkouts, agents going offline etc.

BuildCanceledEvent

Occurs when a Job or Build is canceled via the PlanExecutionManager

BuildCommentDeletedEvent

Occurs when a comment on ResultsSummary has been removed

BuildCommentedEvent

Occurs when a result has been commented on by the User

BuildCompletedEvent

Occurs after a Job or Build has completed and results saved to the database but not necessarily before or after any CustomBuildCompleteActions are performed

BuildConfigurationUpdatedEvent

Occurs when the the build configuration has been updated

BuildCreatedEvent

Occurs when a Job or Build has been created

BuildDeletedEvent

Occurs when a Job or Build has been deleted

BuildFinishedEvent

Occurs when BuildExecutionManager.finishBuild() has been called on a Job or Build. This is guaranteed to be fired even if the system has encountered an irrecoverable error and as such a corresponding BuildResultSummary may not be available.

BuildQueuedEvent

Occurs when a Job or Build has been queued

BuildQueueTimeoutEvent

Occurs when a Job or Build has timed out whilst being on the queue.

BuildHungEvent

Occurs when Bamboo's build monitoring detects the build has met the configured build hanging criteria

BuildRequirementUpdatedEvent

Occurs when a Requirement has changed on a Job or Build

BuildResultDeletedEvent

Occurs when a result for a Job or Build has been deleted

BuildResultsSummaryUpdatedEvent

Occurs when a result for a Job or Build has been updated. Currently the only way to edit a build summary is editing the JIRA issues associated with the build.

BuildsMovedEvent

Occurs when moving plans between projects.

BuildTriggeredEvent

In Bamboo 2.6 and earlier, this event occurs after a bamboo has detected that the Build needs building, before the build is placed on the queue. In Bamboo 2.7 and later, this event occurs when a job has been executed.

ChangeDetectionRequiredEvent

Event which signifies that Bamboo should check repositories for changes

ChainCompletedEvent

Occurs when a Plan finishes executing

ChainCreatedEvent

Occurs when a Plan is created

ChainDeletedEvent

Occurs when a Plan is deleted

ChainResultDeletedEvent

Occurs when a Plan Result has been deleted

DeletionFinishedEvent

Occurs after the deletion action has finished

ElasticConfigUpdatedEvent

Occurs when an Elastic Configuration has been updated

EmailEvent

Occurs when an email is to be sent

FailedStageRestartEvent Occurs before a failed stage is restarted

IMEvent

Occurs when an instant message is to be sent

InitialBuildRequiredEvent

Occurs when bamboo detects that an initial clean build is required for a plan (usually after plan creation or importing data)

JobCompletedEvent

Occurs when a [BAMBOO:Job] has finished executing

ManualStageResumedEvent Occurs before a manual stage is resumed
MultipleChainsDeletedEvent Occurs when lots of Chain are deleted.
MultipleJobsDeletedEvent Occurs when multiple jobs are deleted
PlanFavouriteAddedEvent Occurs when a user favourites a Plan
PlanFavouriteRemovedEvent Occurs when a user removes a favourite from a Plan
PlanSuspensionRequestedEvent Occurs when a plan is requested to be suspended.

PostBuildCompletedEvent

Thrown after the build is saved AND the build process has been completely cleaned up

ResultLabelAddedEvent

Occurs when a Label is added to a ResultsSummary

ResultLabelRemovedEvent

Occurs when a Label is removed from a ResultsSummary

ServerStartedEvent

This event is fired when the Bamboo server has completed its initialisation process — that is, after Bamboo has completed the following tasks:

  • connected to its database
  • initialised all plugins
  • local agents have started

StageCompletedEvent

Occurs when a stage has completed executing

StoppedOnManualStageEvent

Occurs after a chain stops on manual stage This event will be triggered after any StageCompletedEvent and before any ChainCompletedEvent related to the same build.

Most of these events either extend a BuildEvent (build key available) or a BuildResultEvent (build key and build number available).

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport