Every day, a hard working release engineer was actively monitoring our Collaborative Lifecycle Management (CLM) build.  When the build completed, he would comment in our track build item with information about the build including the build’s status, a link to the build, and links to the builds that contributed to it like the Rational Team Concert (RTC), Rational Quality Manager (RQM), and Rational Requirements Composer (RRC) builds.  Since a majority of the team is subscribed to the track build item, commenting in the track build item is a great way for the team to keep tabs on the build.  As you might imagine, actively monitoring builds is a tedious task, and, if the build completed while the release engineer had stepped out for lunch, was busy working on something else, or had logged off for the day, the build results were delayed for the rest of the worldwide team.

As a new member of the release engineering team, I wondered if there was a better way to accomplish this repetitive task of commenting in the track build item whenever a CLM build completed.  While RTC supports automatic notifications like email and pop-up toast notifications out of the box, commenting in a work item is not an out-of-the-box feature.  One of my coworkers introduced me to Jazz Build Engine (JBE) participants, which allow users to create pieces of code that will automatically be executed before, during, or after a Jazz build.  I leveraged build engine participants so that comments are now automatically posted to the track build item when our CLM builds start and complete.  Now, build results are posted immediately, which is an average of an hour faster than when the release engineers were commenting in the track build item manually. Release engineers report a time savings of 20 minutes per day per build as they do not have to spend time manually polling the build to see when it completes and they no longer have to manually gather the contents to include in the comment.

What are build engine participants?

Build engine participants are pieces of code that can be run before, during, or after a build.  The code to be executed is installed as a plugin in the JBE, and the participant is applied to the Jazz build definition so the engine knows to execute the code.  The JBE takes care of notifying the participant that it should be run; all you have to do is write the code that should be executed at the given time in the build process.  The JBE provides an Eclipse extension point for participants, so your plugins can extend the JBE with new behavior.  Your code could pull information out of the build request’s properties or make calls to the Jazz API.  Your build engine participant might create a new work item, comment in an existing work item, or tag a build.  Because you are creating a custom build engine participant, you have the option of customizing what actions are taken based on the build’s properties and/or status.

Getting started with build engine participants

There are four major steps to complete in order to use build engine participants:  writing the build engine participant, installing the build engine participant in the JBE, installing the build definition configuration element and editor extensions in the RTC client for Eclipse, and applying the build engine participant to the build.

Writing the build engine participant

When you’ve decided what action your build engine participant should take, it’s time to get coding.  You will likely want to organize your code into three new plugins:  Common (for code common to both the JBE and the RTC client for Eclipse), RTC client for Eclipse, and JBE.  If you’re unfamiliar with how to create Eclipse plugins or just need a refresher, http://www.eclipse.org/users has tutorials and articles that will get you started.

Your Common plugin will contain code that is common to both the JBE and RTC client for Eclipse.  Inside of the Common plugin’s plugin.xml, create an extension for the com.ibm.team.build.common.buildConfigurationElements extension point.  Here you will create your buildConfigurationElement for your build engine participant.  Build configuration elements define the properties needed by the build engine participant.  Other extensions you write will reference the build configuration element you create here.  For example, your buildConfigurationElement might look like the following code snippet.

<extension point="com.ibm.team.build.common.buildConfigurationElements">
     <buildConfigurationElement
        id="com.ibm.team.releng.example"
        buildPhase="POST_BUILD"
        description="Prints to the build log when build completes"
        name="Print upon build completion" />
</extension>

Also create an extension for the com.ibm.team.build.common.buildDefinitionTemplates extension point.  The build definition template you define here will allow you to create new builds using your custom build engine participant.  For example, the list of available build definition templates can be seen in the New Build Definition Wizard on the “General Information” page.  Some of the common build templates that are available in RTC include “Ant – Jazz Build Engine,” “Command Line – Jazz Build Engine,” “Maven – Jazz Build Engine,” and “Rational Build Forge.”  These build definition templates essentially define which pre-build and post-build options are displayed in the New Build Definition Wizard.  Your buildDefinitionTemplate could be defined similarly to the following code snippet.

<extension point="com.ibm.team.build.common.buildDefinitionTemplates">
     <buildDefinitionTemplate
        id="com.ibm.team.releng.printBuildTemplate"
        description="A build that prints to the build log when it completes"
        name="Example build template">
           <buildConfigurationElement id="com.ibm.team.build.general"/>
           <buildConfigurationElement id="com.ibm.team.build.cmdline"/>
           <buildConfigurationElement id="com.ibm.team.build.schedule"/>
           <buildConfigurationElement id="com.ibm.team.build.properties"/>
           <buildConfigurationElement id="com.ibm.team.releng.example"/>
     </buildDefinitionTemplate>
</extension>

When you have completed all of the steps in this section to write and install your build engine participant, your template will be listed in the New Build Definition Wizard as seen in the image below.

Your RTC client for Eclipse plugin will contain the code that creates the user interface elements in RTC for your build engine participant.  Create a class that implements com.ibm.team.build.ui.editors.builddefinition.IConfigurationElementEditorFactory and returns an AbstractConfigurationElementEditor in the createElementEditor method.  This AbstractConfigurationElementEditor will be displayed as a tab in the build definition’s editor.

Open your RTC client for Eclipse plugin’s plugin.xml.  Create an extension for the com.ibm.team.build.ui.buildConfigurationElementEditors extension point.  Your buildConfigurationElementEditor should contains references to your element editor factory class you just created and the configuration element you created in your Common plugin.  Your buildConfigurationElementEditor will be similar to the following code snippet.

<extension point="com.ibm.team.build.ui.buildConfigurationElementEditors">
     <buildConfigurationElementEditor
        configurationElementId="com.ibm.team.releng.example"
        name="Example Element Editor"
        class="com.ibm.team.releng.rtc.ExampleElementEditorFactory" />
</extension>

Your JBE plugin will contain the code that should be executed at the given point in the build process.  Create a class that extends com.ibm.team.build.engine’s AbstractPreBuildParticipant, AbstractBuildParticipant, or AbstractPostBuildParticipant based on when you want the actions to occur.  Override the preBuild, build, or postBuild method as appropriate.  The JBE will take care of calling this method; all you have to do is implement whatever actions you want to be taken.  Here you can get the build’s properties, find out information about the build such as when it was started or its label, or make calls to the Jazz API or your own methods.  You can customize when the actions are taken based on the conditions of your choosing; for example, perhaps you don’t want the action to be taken if the build is a personal build or if some property is set to false.  You can create build activities in order to indicate what is happening while the build engine participant is running.  The following post-build participant simply prints to the build log when the build completes.

import org.eclipse.core.runtime.IProgressMonitor;
import com.ibm.team.build.common.model.BuildStatus;
import com.ibm.team.build.engine.AbstractPostBuildParticipant;

public class ExamplePostBuildParticipant extends AbstractPostBuildParticipant {

     @Override
     public BuildStatus postBuild(IProgressMonitor monitor) throws Exception {
          getBuildLog().println("The build completed.");
          return BuildStatus.OK;
     }
}

Once you’ve finished writing your code that will take action, open the JBE plugin’s plugin.xml.  Create an extension for the com.ibm.team.build.engine.buildEngineParticipants extension point.  Your buildEngineParticipant element should contain references to the class you just created and the configuration element you created in your Common plugin.  For example, your buildEngineParticpant could look similar to the following code snippet.

<extension point="com.ibm.team.build.engine.buildEngineParticipants">
     <buildEngineParticipant
        id="com.ibm.team.releng.jbe.ExamplePostBuildParticipant"
        class="com.ibm.team.releng.jbe.ExamplePostBuildParticipant"
        buildPhase="POST_BUILD"
        configurationElementId="com.ibm.team.releng.example" />
</extension>

When you’re satisfied with your code, export your plugins to jar files.

Installing the build engine participant in the Jazz build engine

To install the build engine participant jars in your JBE, drop your Common and JBE jars into your JBE’s eclipse/plugins directory.  Start your JBE with the -clean option; you may also want to use the -debug and -consoleLog options to help debug any issues.

Installing the build definition configuration element and editor extensions in the RTC client for Eclipse

You will need to install the build definition configuration element and editor extensions in the RTC client for Eclipse of any user who wants to apply the participant to a new or existing build.  Users who do not have the build definition configuration element and editor extensions installed will still be able to modify the build definition and request builds.  To install the build definition configuration element and editor extensions in your RTC client for Eclipse, drop your Common and RTC client for Eclipse jars into your client’s plugins directory.  You may need to restart your client in order to apply the participant to a build.

Applying the build engine participant to the build

Now you’re ready to apply your custom build engine participant to your favorite build.  In the RTC client for Eclipse, open the Team Artifacts view.  Expand your project area’s Builds node.

To create a new build using your build template for your pre-build, build, or post-build engine participant, right-click on the Builds node and choose New Build Definition….  Choose Create a new build definition and click Next.  Select your template in the list of available build templates and click Next.  You will then have the option to select your custom build engine participant and complete the wizard.

To add your pre-build or post-build engine participant to an existing build, right-click on the build definition and choose Open Build Definition.  At the top of the build definition editor, click on the down arrow next to Build Definition.  While holding down the control button on your keyboard, click Edit Configuration.  You can then choose to apply your pre-build or post-build engine participant and click OK.  Note that if you do not hold the control button while clicking Edit Configuration, you will only be able to choose participants that were specified in the original build template; using the control button allows you to see all available participants.  You should only use the control button technique when you are certain that the build engine participant is compatible with the build’s template; otherwise, your build may have unexpected results.

Run your build and watch the magic happen.

Check it out!

Are you curious how we’re using build engine engine participants?  You can visit our track build item (see comments 76-78) to see how we’re automatically adding comments when the CLM and build verification tests (BVT) builds complete.  Look for comments from Mr. Build; yes, we named our build account user Mr. Build.  For a better understanding of how our build engine participants work and to see how we customize our comments based on the build’s properties and status, visit our wiki page.

Give build engine participants a try and let us know how you’re leveraging them to improve your processes and save time.

Lauren Schaefer,
Jazz Developer