Heads up! ScriptRunner for Bamboo documentation has moved to https://docs.adaptavist.com/sr4bam. Adaptavist will keep this site up for a bit, but no future updates to documentation will be published here. ScriptRunner 6.20.0 will be the last release to link to scriptrunner.adaptavist.com for in-app help.

Using Listeners in ScriptRunner for Bamboo, you can perform custom actions whenever standard Bamboo system events are fired. There are built-in listeners, or you can create a custom listener.

Adding a Listener

  1. Navigate to Admin > Listeners.

  2. Select the Add New Item button to expand the listeners available to create.

  3. Choose a Custom Listener or a built-in listener.

Custom Listeners

You can create custom listeners with your own scripts. To add a custom listener, follow these steps:

  1. Select Custom Listener.

    custom event handler form
  2. In the Events field, select the events you want to listen for.

    The event is contained in the script binding. The event object has the type corresponding to its name. For example, if you are listening for BuildCompletedEvent you get a BuildCompletedEvent object.

    You may choose to have your listener look for multiple events. If you need to do different things depending on the type of event, you can check that with instanceof.

    Alternatively, you can type your event to the most specific superclass. In in the above example that would be BuildEvent.

    For example, to get the page content for both BuildCompletedEvent and BuildDeletedEvent:

    def event = event as BuildEvent(1)
    def content = event.content.bodyAsString
    
    // do something with the page content
    1 - event is passed in the binding. This line is only used to give type information when using an IDE, and has no functional impact

Built-in Scripts

In addition to custom listeners, there are built-in ones to help save you time on more commonly used listeners.

Conditional Job Killer

This listener allows you to specify a condition to stop a build. You can stop any job that you want for any reason. Write in your condition, and then every job that runs is checked against it.

Follow these steps to set up a Conditional Job Killer:

  1. When you get to the point of choosing a listener, select Conditional Job Killer.

    The Conditional Job Killer form appears:

    ConditionalJobKillerListenerForm
  2. Enter a Note for your your listener.

    This helps identify it in the list of listeners.

  3. Enter your scripted condition in the Condition field.

    A value of true stops a build and a value of false allows the build to proceed.

    This has the capacity to stop every build in Bamboo. If you only enter true, it would stop all builds. If your condition only applies to a subset of builds/plans/etc, make sure that is accounted for in your condition.
  4. Enter a custom error message in the Error Message field.

    This message appears on the job when it is stopped by this listener.This helps you identify when a job was stopped by this listener.

Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.

Ask a question about ScriptRunner for JIRA, Bitbucket Server, or Confluence.

Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.