Integrating Rational Team Concert and Hudson builds

Spencer Murata, IBM
Last updated: May 9, 2012
Build basis: Rational Team Concert 4.0, Hudson 2.2

IBM Rational Team Concert supports integration with a Hudson deployment. Currently, the integration is compatible with both Hudson and Jenkins. However, for the purposes of this article, assume that a Hudson version 2.2 deployment is the build tool.

What is the Hudson integration?

The purpose of the integration is to use the build capabilities of Hudson in such a way that Rational Team Concert can easily access them. By using a Hudson Build Participant, you can start a build in Rational Team Concert, generate a matching build in Hudson, and link the two build results together. Additionally, you can use the Rational Team Concert Build Toolkit Ant tasks to round trip source files and build artifacts to and from Rational Team Concert and Hudson. This article walks through the basics of the integration and getting into some more complex round-trip build artifact synchronization.

Setting up a simple build

For the purposes of this article, assume that a Jazz server is already installed and that a project area is set up.

1. Create a build engine.
   1. In the Team Artifacts view, under the expanded node for the project area, expand the Builds folder and right-click New Build Engine.
   2. Click Create a new build engine and then click Next.
   3. For the ID, type Hudson Engine; for the type, select Hudson/Jenkins Engine; and click Finish. A build engine named “Hudson Engine” is created.
   4. In the resulting build engine editor, click the Hudson/Jenkins tab. Type the URL that points to the Hudson deployment. If user credentials are required to log on to Hudson, a user information field passes in the Hudson user credentials. If your Hudson deployment requires a user, enable the Authorization Required button and type in your user and password information.

      

   5. After you enter the required information, click Test Connection. If the information is correct and the Hudson server is running, the message Test connection SUCCESSFUL is displayed with header information about the Hudson version. If the connection is successful, click Save.

      

2. Create a Hudson job that you can link to Rational Team Concert. To do so, you must switch to your Hudson deployment and create a job there.
   1. Open your web browser and go to the Hudson main page.
   2. Click New Job.
   3. In the Job name field, type RTC Job, and then click Build a free-style software project and click OK. The configuration page of the new Hudson job opens.
3. Modify the configuration page of the Hudson job so the build will display the message Hello World.
   1. In the Build section, click Add build step.
   2. If you use a Windows system, click Execute Windows batch command; if you use Linux system, click Execute Shell.
   3. In the Command field, type echo Hello World!.
   4. Test the build by clicking Build Now from the left menu. A new build is displayed that has the echo command.

      You have created and configured your Hudson build engine, and you have a Hudson job. Now, you need a build definition.

4. Create a build definition to use the new build engine and Hudson job:
   1. Right-click the Builds folder and click New Build Definition.
   2. Click Create a new build definition, and then click Next.
   3. In the ID field, type Hudson Build; for the template, click Hudson/Jenkins Build; and click Finish. A build definition named “Hudson Build” now exists.
5. In the resulting Build Definition editor, add your Hudson engine to the Hudson build definition.
   1. Click Add and select your Hudson engine.
   2. Click the Hudson/Jenkins tab and click Get Jobs. The Job list is populated by the jobs on the Hudson server.
   3. In the list, click RTC Job. Save the build definition.

      

The integration is now set up, and you can start a build. You can start a build in many ways, but for the purposes of this example, take these steps:

1. Right-click the Hudson build build definition, click Request Build, and click Submit. You do not need to select anything before you click Submit because you are requesting a simple build. The build is displayed in a pending state in Rational Team Concert.
2. Click Refresh a few times. The build transitions to the running state and then to the complete state.

   

   In the Builds view, the label of the job is “RTC Job,” and the job number is next to the job name. If you open the build, you can find a log and a link attached to the build. The link opens the Hudson job result on the Hudson console, and the log is the console build log. The console log in the Rational Team Concert build result was copied from Hudson to Rational Team Concert and now exists in Rational Team Concert.

Setting up a more complicated build

Now that you have set up a simple build, you can take the integration deeper. In the next procedure, you expand your example to involve more complex tasks and to synchronize the build between the two platforms.

For the purposes of this article, assume that you already configured the Hudson Java developer kit and Ant global build properties. Ant is not part of Hudson; you must install it separately from Hudson in order for this example to work.

1. Download and extract the HudsonIntegration.zip file somewhere on the Hudson server. This file contains the example Ant build file and the source files that you will build. The build.xml in the HudsonIntegration.zip builds the Java files and packages them into a JAR file. The Ant script runs through various targets, each of which is associated with an Rational Team Concert build activity. At the end, the JAR file is published back into Rational Team Concert. The build.xml file is set up with ADMIN as the password. If the requesting user’s password is not ADMIN; for example, if user is not the default ADMIN user; the password field must be updated to the requesting user’s password.
2. Edit your Hudson job to allow Rational Team Concert build properties to be passed into the Hudson build.
   1. Open the Hudson Job configuration page and click This build is parameterized to enable Rational Team Concert to pass parameters to the Hudson job.
   2. Declare the parameters in Hudson. If you do not declare the parameters, Hudson cannot use them in the build, even if the parameters are sent. The following variables are sent by Rational Team Concert. These parameters are case sensitive.

      Variable	Description
      requestUUID	UUID of the build request
      buildResultUUID	UUID of the build result
      buildDefinitionId	ID of the build definition
      repositoryAddress	Address to the build web application that requested the build
      buildEngineId	ID of the build engine
      buildEngineHostName	Host name of the Hudson serverM
      buildRequesterUserId	ID of the user who requested the build

      The Ant script uses three parameters: buildResultUUID, repositoryAddress, and buildRequesterUserId.

   3. Set up the three parameters by clicking Add Parameter and clicking String Parameters for the RTC Job, making sure to match the cases.
   4. Add your Ant script to the Hudson job.
      1. Return to the Build section. Click Add build step and click Invoke Ant.
      2. For the targets, type clean publish -lib path to the RTC buildtoolkit. For example, your path to the build toolkit might be C:ibmBuildToolkitbuildsystembuildtoolkit.
      3. For the build file, type the path to the build.xml file that has been extracted from the HudsonIntegration.zip.
   5. Start another build. If you refresh frequently, you can see the build progress through different stages. The stages correspond to the build activities that you defined in the Ant script.

      

   6. When the build is complete, open the build and check the Activities tab. The build activities correspond to the activities that are defined in the Ant script. The Downloads tab contains the helloWorld.jar file from the script. If you view the Logs tab, you can see the full Ant log that describes the build process.

      

Summary

Now that the more complicated example is complete, you have a working Hudson and Rational Team Concert integration. You have seen how the Rational Team Concert Hudson build definition sends build parameters to the Hudson job, which can then be used with the Ant tasks of the Rational Team Concert Build Toolkit to contribute artifacts and build entries back to the Rational Team Concert build. By using the framework described in this article, you can expand the example to address your build needs.

For more information, see these resources:

• Hudson Eclipse website
• Jenkins website

About the author

Spencer Murata is part of the Rational Team Concert Level 3 team in Littleton, MA. You can contact Spencer at murata@us.ibm.com.

© Copyright 2012 IBM

Feedback

Was this information helpful? Yes No 7 people rated this as helpful.

Let us know how we can improve this information.