The Script Event Handlers section in ScriptRunner for Bamboo allows you to perform bespoke actions whenever standard Bamboo system events are fired.

Built-in Scripts

As well as being able to create your own custom event handlers with your own scripts, we’ve added in some built-in ones to help save you some time on the more commonly used listeners. Below is a summary list of the built-in listeners that ScriptRunner for Bamboo currently supports.

Table 1. Built-in Scripts
Script Name Description

Expired JDK Listener

This listener will stop any builds that attempt to run, where they are using an "expired" JDK. You can select which JDK you want to blacklist from the listener configuration.

Conditional Job Killer

Allows you to specify a condition under which a build will be stopped. With this listener you can stop any job you want, for ANY reason. Simply write in your condition, and then every job that runs will be checked against it.

Expired JDK Listener

In order to set up an expired JDK listener…​

  1. Follow the steps below for adding an Event Handler (up to step 4).

  2. When you get to the point of choosing an event handler, simply select Expired JDK Listener (instead of Custom event handler).

  3. You will now be presented with the Expired JDK Listener form (see below)

    ExpiredJDKListenerForm
  4. Enter a "Note" for your your listener. This will help identify it in the list of listeners.

  5. Select the JDK that you wish to block from the list.

    Any builds attempting to run with this JDK will be automatically stopped.

Conditional Job Killer

In order to set up a conditional job killer listener…​

  1. Follow the steps below for adding an Event Handler (up to step 4).

  2. When you get to the point of choosing an event handler, simply select Conditional Job Killer (instead of Custom event handler).

  3. You will now be presented with the Conditional Job Killer form (see below)

    ConditionalJobKillerListenerForm
  4. Enter a "Note" for your your listener. This will help identify it in the list of listeners.

  5. Enter your scripted condition in the "Condition" box. A value of "true" will stop a build whilst a value of "false" will allow the build to proceed.

    This has the capacity to stop EVERY build in Bamboo. If, for example you just put in false it would stop all builds. You should therefore make steps that, if your condition only applies to a subset of builds / plans / e.t.c. that is accounted for in your condition.
  6. Enter a custom error message in the "Error Message" field. This is what will be displayed on the Job when it is stopped by this listener. This will help you to identify when a job was stopped by this listener.

Guides

Adding an Event Handler

  1. Navigate to Admin → Script Event Handlers.

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

  3. Click a heading to add a handler.

  4. Choose one of the build in listeners OR choose Custom Event Handler to use your own scripts to respond to events.

    For the purposes of this tutorial, we will assume you have selected Custom Event Handler
  5. In the Events select box, select the events you want to listen for.

    Some of the built-in content will have different options, and may not ask for the events to listen for
custom event handler form

Working with Custom Event Handlers

The event is contained in the script binding. The event object will have the type corresponding to its name…​ for instance if you are listening for BuildCompletedEvent you will get a BuildCompletedEvent object.

You may choose to have your handler listen for multiple different 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 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

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

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