Introduction

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.

Back to top

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).

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.

<?xml version="1.0" encoding="UTF-8"?>
<project name="buildtest" default="main">
    <target name="main" depends="pre-condition" description="">
        <echo>
            Main build activities
        </echo>
    </target>
    <target name="pre-condition">
        <echo>
            Precondition for build
        </echo>
    </target>
</project>

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.

Buildfile: C:\BUILDS\build.xml

pre-condition:
     [echo] 
     [echo] 			Precondition for build
     [echo] 		

main:
     [echo] 
     [echo] 			Main build activities
     [echo] 		

BUILD SUCCESSFUL

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

<?xml version="1.0" encoding="UTF-8"?>
<project name=" 
			Main build activities
		</echo>
	</target>
	<target name="pre-condition">
		<echo>
			Precondition for build
		</echo>
		<fail/>
	</target>
</project>

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.

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

Back to top

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

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.

<java classname="CheckWorkItemState" fork="yes" failonerror="true">
        <classpath>
            <pathelement path="${buildFolder}/commands" />
        </classpath>
        <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}" />
</java>

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.

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.

pre-condition:
     [echo] 
     [echo] 		Checking work item status ...
     [echo] 	
     [java] Status check work item: New.
     [java] Bad state build fails

BUILD FAILED
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.

pre-condition:
     [echo] 
     [echo] 		Checking work item status ...
     [echo] 	
     [java] Status check work item: Approved.
     [java] Good state build starts

main:
     [echo] 
     [echo] 		Build Main started ...
     [echo]

Note:
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.

Back to top

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.

>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).

while (<> ) { 
    @wi_info = split(/ /, $_); 
    chop($wi_info[2]); 
    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.

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

Back to top

Acknowledgement

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

Back to top

Download

Information about download methods

Resources

Learn

• These articles on Jazz.net are also helpful:
  • Getting Started with Setting up Jazz Builds
  • Extending Rational Team Concert 3.x
  
  
• For more about Rational Team Concert:
  • Find Rational Team Concert articles and links to many other resources on IBM developerWorks, and check the product overview page, features and benefits, system requirements, and the user information center.
  • Check the Rational Team Concert page on Jazz.net.
  • Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Subscribe to the developerWorks weekly email newsletter, and choose the topics to follow. Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  • Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
  • Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  
  
• Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
  
  

Get products and technologies

• Download Rational Team Concert from Jazz.net 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.
  
  

Discuss

• Join the Rational Team Concert forum discussions on Jazz.net.
  
  
• Rate or review Rational software. It’s quick and easy.
  
  
• Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
  
  
• Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
  
  
• Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
  
  
• Get connected. Join the Rational community to share your Rational software expertise and get connected with your peers.
  
  

About the author

Takehiko 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Rational Team Concert build example setup
• Example 1. Check work item approval status
• Example 2. Run query and check status of work items
• Acknowledgement
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Team Concert
• Demo: Rational and Jazz
• Webcast: Agile development with IBM Rational Synergy and IBM Rational Team Concert
• Buy: Rational Team Concert

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers