Run a precondition before the build to reduce the risk of build failure

Use Apache Ant to add a pre-test to a Rational Team Concert build process

The continuous software build automation feature in Rational Team Concert can be run according to a schedule or on demand. Takehiko Amano describes how to run a precondition to reduce the risk of build failure by using the Apache Ant build mechanism before running the actual build process. He includes an example of running a query for work items that are going to be included in the current build, checking the status of each work item, and then running the build.


Takehiko Amano (, IT Specialist, IBM

author photoTakehiko Amano is an IBM solution architect at the Software Development Laboratory in Tokyo, where he works as a member of Unleash the Labs initiative. One of his interests is global collaborative software development tools and processes.

10 July 2012

Also available in Chinese Russian


Running a build process according to certain defined event, such as a nightly build or on demand, is common practice of software development. In a large software build, it can take hours or even days. Frequently, the build fails. This is huge waste in terms of lean management practice. This is especially true when the build is run in a cloud infrastructure, where the cost is charged based on CPU use.

Running a precondition reduces the risk of build failure. In some cases, the build requires an approval process. This might be true for a release build, because if the release build contains unwanted changes, the recovery cost after the release tends to be sizable and adds another unexpected cost. Therefore, it is a good to run a precondition to check the validity of the build before running the main build process.

Rational Team Concert build example setup

Figure 1 shows the example setup used for this article, with an IBM® Rational Team Concert™ server and a Jazz™ Build Engine (jbe-engine). The server requests build though an Apache Ant build definition (ant-build).

Figure 1. The build example setup used in this article
Rational Team Concert build workflow example

In this example, the Jazz Build Engine runs on a Microsoft Windows server. The build engine is defined as jbe-engine. The build is defined as ant-build, which uses jbe-engine to run an Apache Ant build. In this example, build.xml used in build process is not under source control to keep this explanation as simple as possible.

Running a precondition in Rational Team Concert Ant build

Rational Team Concert supports various build mechanisms. This article illustrates using Ant build process, but this example applies to most of the supported build processes.

The Ant build has a dependency mechanism. For example, a .java class must be generated before creating a .jar file. To do this, Java compiles the .java file by creating a .class file. This article uses this dependency mechanism to run a precondition. Listing 1 illustrates the basic building block of the build.xml file used in the example.

Listing 1. The build.xml file building block
<?xml version="1.0" encoding="UTF-8"?>
<project name="buildtest" default="main">
    <target name="main" depends="pre-condition" description="">
            Main build activities
    <target name="pre-condition">
            Precondition for build

In this example, before entering the main target, pre-condition is evaluated and executed. When a precondition succeeds, the main target is run. Listing 2 is a result of log file of this build.xml run from the Rational Team Concert build engine.

Listing 2. The build result of file shown in Listing 1
Buildfile: C:\BUILDS\build.xml

     [echo] 			Precondition for build

     [echo] 			Main build activities


To illustrate how it works, add the <fail/> task, as shown Listing 3. This tells Ant to fail with an error status.

Listing 3. A sample build.xml file that fails in a precondition target
<?xml version="1.0" encoding="UTF-8"?>
<project name=" 
			Main build activities
	<target name="pre-condition">
			Precondition for build

An echo statement in main in the example will not be printed. Also, the Rational Team Concert client build status red icon (see Figure 2) indicates that the build has failed.

Figure 2. Builds view in Rational Team Concert shows that the build failed
Red circle with white X icon indicates failed status for the build

This article explores using a precondition target by explaining several (hopefully practical) examples directly linked to Rational Team Concert artifacts.

Example 1. Check work item approval status

This example uses Java code. The entire source code is attached to this article (see the Downloads section). The scenario in this example is:

Check that the specified work item status is "Approved."

Java code runs with Rational Team Concert Java client library. This example code takes five arguments (simplified command line):

java CheckWorkItemState <repository> <project-name> <userid> <password> <work item-id>

For example, suppose that there is work item number 123, and the Approved state is required. The command execution returns status 0 when the status of work item is "Approved."

 > java –Djava.ext.dirs=%JAVA_HOME%/lib/ext;C:/BUILDS/RTC-ClientLib -cp . 
CheckWorkItemState https://localhost:9443/ccm RTC Project jazzadmin jazzadmin 123

The Approved state string is hard-coded in the example code. The status string can be specified in a build parameter and then passed to this build process.

This command is called from the Ant build script with the Rational Team Concert build capability. When the build script is invoked, several parameters are passed to the process. For example, the <repository> parameter is passed as ${repositoryAddress}. For a full list of parameters, see the Rational Team Concert online information center. Some parameters must be defined in the build definition. To be able to run the example code, the following parameters shown in Table 1 must be defined in the build definition

Table 1. Build parameters used in the example
NameExample valueDescription
buildFolder C:\BUILDS Top folder name to hold build tools. This folder must contain the Rational Team Concert Java client plain library
projectName TEST Project area name.
workItemID ID number of work item. This is kept blank.

The work item number should be specified in a build parameter, either as it is in this example or in another way, for automation. You can implement a precondition target as Listing 4 shows.

Listing 4. Portion of the build.xml file for the precondition target
<java classname="CheckWorkItemState" fork="yes" failonerror="true">
            <pathelement path="${buildFolder}/commands" />
        <jvmarg value=
            "-Djava.ext.dirs=${java.home}/lib/ext;${buildFolder}/RTC-ClientLib" />
    <arg line="${repositoryAddress}"/>
    <arg line="${userId}" />
    <arg line="${password}" />
    <arg line="${projectName}" />
    <arg line="${workItemId}" />

The full build.xml file used in this example is attached to this article (see Downloads). Figure 3 shows the Request Build dialog window. In this example, the work item ID is specified as a build parameter. In the example, ID = 116 is passed.

Figure 3. A dialog window specifying work item 116 for the build
specify 116 as the Value

The code simply checks whether the specified work item is Approved or not. If the status is not Approved, the build fails. Result A, in Listing 5, shows the result of build when a work item status is New. As it is shown, the build fails.

Listing 5. Result A, when the status of work item is not Approved
     [echo] 		Checking work item status ...
     [java] Status check work item: New.
     [java] Bad state build fails

C:\BUILDS\build.xml:31: Java returned: 1

When the work item status is moved to the Approved state, the main target starts (Result B, Listing 6). Result B shows that when a specified work item status is Approved, a precondition target is passed, and then the main target is started. The build status shows BUILD SUCCESSFUL.

Listing 6. Result B, when the status of work item is Approved
     [echo] 		Checking work item status ...
     [java] Status check work item: Approved.
     [java] Good state build starts

     [echo] 		Build Main started ...

In the example, the main target always succeeds. In a real situation, it might fail, depending on various conditions.

This example can be used in many situations. For example, a release engineer might want to control a build by work item status. Trivial use is to use this example in a release build where a strict approval process is required before running release build. A release engineer might want to make sure that the product owner has reviewed what is going to be in the build, and then approve the build.

Example 2. Run query and check status of work items

When a Rational Team Concert Ant build is set up to use Rational Team Concert SCM, (software configuration management), it can be configured to run accept and load. An accept command means the workspace is set up to use the latest source codes in the stream. A load command means to load the contents of the workspace into a specified directory in the build definition. Depending of process configuration, a change set may be associated with a work item, such as Task, Defect, or Enhancement.

Rational Team Concert has a feature called personal build, which allows checking whether the modification to the code passes the criteria set. The criteria examples are to pass unit tests, to verify defect resolutions, and so on. It is best to run a personal build. Then the developer normally changes the status of work items associated with change sets to Resolved and delivers change sets to the stream. However, some developers might forget to change the status of work items.

In other cases, developers might accidentally deliver codes without testing, thus keeping work item in the In Progress status or even in New. This oversight might cause build failure, because the codes are not tested.

The example in this section checks that all work item status is resolved and associated with Accept operation. This enables a release engineer to know as soon as possible if developers forget work item state change operations, without a manual check of work items.

To list what work items are going to be incorporated into the build, the scm compare command can be used. The scm compare command has an option to list work items (-I w) to be incorporated into build. The Accept operation accepts the change sets from the stream. For example, suppose there is a stream called MAIN that is the target stream of the Deliver operation, and BUILD is a workspace for the release build. So we will compare the build workspace (BUILD) with the stream (MAIN) as shown in Listing 7.

Listing 7. List of work items that will be incorporated into the build
>scm compare -I w workspace BUILD stream MAIN -u jazzadmin -P jazzadmin 
Work Item 19: This is a task 
Work Item 26: This is yet another task

This list shows that work item numbers 19 and 26 are going to be incorporated into a new build. The result of the scm compare command must be parsed to obtain just work item numbers. By using a regular expression tool and splitting by white space, and eliminating ‘:’, work item numbers can be obtained (see the example Perl script in Listing 8).

Listing 8. Example Perl code to obtain work item number
while (<> ) { 
    @wi_info = split(/ /, $_); 
    print $wi_info[2], "\n"; 

By extending the Example 1 code, it should be straightforward to check whether these work items are the same status or not. The code can be extended to loop every work item.

The example code is not explained in this article to let readers implement it and see results first-hand.


The author expresses sincere thanks to Paul Weiss and Ken Kumagai for their guidance in writing this article.


Source code for this articlereduce-risk-build-failure.zip3KB



Get products and technologies

  • Download Rational Team Concert from and try it free on up to 10 projects for as long as you want (requires registration).
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Run a precondition before the build to reduce the risk of build failure