Create software builds with Jazz Team Build

A guide to using the Jazz Team Build feature in Rational Team Concert

Veena H. Balakrishnaiah gives an overview of how to configure source control and Jazz Team Build components of Rational Team Concert to define and manage your build. Jazz builds run against files that come from a designated build repository workspace and include traceability between change sets and work items. Jazz Team Builds provide support for the automation, monitoring, and awareness of a team's regular builds.


Veena H. Balakrishnaiah (, Build and Release Engineer, IBM

author photoVeena H. Balakrishnaiah is part of the Operations Software Engineering Service team at the IBM Software Labs in India, where works on various product builds. Veena has a master's degree in software systems. She is experienced with SCM and automation tools, including IBM Rational ClearCase. IBM Configuration Management Version Control (CMVC), Rational Team Concert, and Rational Build Forge.

31 July 2012

Also available in Chinese Portuguese


This article explains the Team Build feature of the Jazz™ technology platform that provides support for the automation, monitoring, and awareness of a team's regular builds. The Jazz Team Build provides a model for representing the team's build definitions, build engines, and build results. Although the build toolkit is best suited for Apache Ant builds, you can use any scripting technology that can invoke Ant. For example, a team can use Perl, DOS batch files, or Make to create build scripts that interact with Jazz Team Build.

A team typically has a build system that runs builds from a dedicated build machine. All build-related items belong to a project area. Build-related operations are governed by the project's process.

Configure Rational Team Concert components

This section explains how to configure source control and Builds components of IBM® Rational Team Concert™. Jazz builds can include traceability between change sets and work items. You typically run a build against files that come from a designated build repository workspace that has incoming flows from the team's main development stream.

Before running the build, all of the latest changes are accepted from the team's stream and a reproducible snapshot of the files is created. The change sets and work items included in the build are recorded to view.


This article is based on these assumptions:

  • The Rational Team Concert server is already set up, and you have access to the server through Rational Team Concert Eclipse client.
  • The required source code for build is present in the Rational Team Concert project area source control
  • The Build System Toolkit has been installed by using the IBM Installation Manager.

Working with the repository workspace

  1. Launch the Rational Team Concert Eclipse client.
  2. Log in and connect to the existing repository connection, based on your team invitation.
  3. Connect to the existing project areas or create a new project area by using the Scrum template.
  4. Create a new repository workspace from the required stream of the source control component, which acts has a local copy or development workspace where the changes can be made on the repository files:
    1. From the required stream, right-click and select New.
    2. Choose Repository Workspace from the next menu, as shown in Figure 1.
    3. Enter an appropriate name in the Repository Workspace Name field, and click Next (Figure 2).
    4. In next dialog windows, leave the default selections.

If you are not the administrator and not able to create the project area, send a request to the Rational Team Concert project admin to create a project area with the default Scrum template.

Figure 1. Source Control menus
Create a new repository workspace
Figure 2. Create a new repository workspace
Repository Workspace Name field entry
  1. Select the components that need to be added to the My Repository Workspace. If you want all of the components to be added, choose the Select All option or select the components one by one, based on the requirement, and click Finish (see Figure 3).
Figure 3. Select components to add to the new repository workspace
Components to Add view with list of components
  1. From the list of options in the Load Repository Workspace window, select an option to load the selected components that you selected in the previous step, and click Next, as shown in Figure 4.

If you choose "Load the root folders of the components as projects" (Figure 4), the root folder is the name of the component in Rational Team Concert source control. It is left to you to select the other loading options, based on how the project folders are defined.

  1. After choosing one of the load options, you will prompted to select which folders of each component need to be loaded into the Eclipse workspace, as shown in the Load Repository Workspace view in Figure 5.
Figure 4. Load all of the projects within the components
Selected: Load component root folders as projects
Figure 5. Folders to load into the Eclipse workspace
Select repository folders to load
  1. To view the component that is loaded, navigate toward the lower right section of the Eclipse client window. Right-click the component name, select Show, and choose Repository Files to view all files and folders in that component.
Figure 6. Repository component expanded to list repository files
Component name selected, two drop-down menus
  1. Expand the folders to view the desired file. Right-click on the file, and click Open Local file to open it in edit mode. If you simply want to view the file, double-click on the filename.
Figure 7. Open the local repository file to make changes
Repository file opened in write mode
  1. Make necessary code changes to the file, Save and close the file.
  2. Click the Pending Changes tab, and expand the folder.
  3. Right-click on the modified file, and then select Check-in and Deliver to integrate the changes with the main stream of Rational Team Concert source control. Add a comment as necessary in comment section.
Figure 8: Check-in and Deliver option on the Pending Changes menu
Check-in and Deliver selected
  1. To deliver the changes, the file has to be associated with a Rational Team Concert work item. If a work item is already created, choose Select an existing work item option; otherwise, select Create a work item so you can associate the changes that you made, as shown in Figure 9.
Figure 9. Associating changes with a work item
Associate Work item dialog window
  1. While you are creating a work item, fill in all of the mandatory fields, including Summary and Filed Against, and then click Finish, as shown in Figure10.
Figure 10. New Work Item dialog window
Mandatory fields: Summary, Filed Against

Changes will be reflected in the main integration stream of the connected project area's source control, and they will be associated with the work item that you created.

Using the Rational Team Concert Builds component

  1. To create a new build engine, expand Builds, right-click on Build Engines, and select NewBuild Engine.
  2. In the New Build Engine dialog window (Figure 11), enter the ID, which will be the build engine name. From "Available build engine types," select Jazz Build Engine and then click Finish.
Figure 11. Available build engine types
Jazz Build Engine selected
  1. After you save the build engine configuration, because the Jazz Build Engine is not running, you will see this warning: The build engine process may not be running.
    1. Run the Jazz Build Engine (JBE) from the command line in the Build System Toolkit installation directory (words in italics vary according to your environment):

      Click to see code listing

      Usage: jbe -vm "location of Java developer kit" 
      –repositoryrepository URL-userIdbuild username-passbuild user password-engineIdBuildEngine_Identifier
    2. To create an encrypted password file, from the command line type (pass.txt can be any filename):
      jbe -createPasswordFile pass.txt
    3. When prompted, type the password. The password is encrypted and stored in a pass.txt file that is located in the Build System Toolkit installation directory.

      Click to see code listing

      Usage: jbe -vm "location of Java developer kit" 
      –repositoryrepository URL-userIdbuild username-passwordFilebuild user password file -engineId BuildEngine_Identifier

Location of Java developer kit is the path of the jdk folder included in the Rational Team Concert Eclipse client download.

Figure 12. Run the Jazz Build Engine from the command line with the encrypted password file
jbe command executed with arguments

After the build engine is created, it gets displayed under Builds in the Build Engine view of the project area.

  1. To create the new build definition, right-click Builds, and select New Build Definition.
  2. In the New Build Definition window, choose the available build templates from the list based on the build tool used for the builds, as shown in Figure 13.
    • If you are using Ant as build tool, the build template will be Ant-Jazz Build Engine.
    • If you are using any other tool or scripting language, choose Command Line-Jazz Build Engine, so you will be able to run scripts or commands to run a build.
Figure 13. Creating a build definition with Command Line - Jazz Build Engine
New Build Definition window with list of templates
  1. In this step, you will be prompted to customize the build definition based on the option that you chose in Step 5. Select Jazz Source Control if customization is required, and click Finish.
  2. Enter the respective details in the Build Definition dialog window:
    1. Under the Overview tab, select the build engine that is created by clicking the Edit button. If you want to create new build engine, click on the Create button.
    2. Under the Schedule tab, define the scheduled timing based on which build definition will be executed.
    3. Under the Properties tab (Figure 14), add the name and values of the property as demanded by build scripts.
Figure 14. Properties tab of the Build Definition dialog window
Add name and value properties
  1. Still in Build Definition window, if you have chosen Jazz Source Control as mentioned in Step 6, fill in the Workspace and Load Directory fields, as shown in Figure 15:
    1. For Build Workspace, click Select, and choose the workspace or stream from the drop-down menu.
    2. In the Load Directory field, mention the absolute directory where the local copy of the stream has to be loaded.
      • Choose Delete directory before loading if the folder already exists and needs to be deleted before loading.
      • Choose Create folders for components if the folder has to be created for each component, which resolves conflict when the folder name for two or more components is same.
    3. Under the Accept Options section, to accept the changes automatically before loading, click both check boxes listed.

If you want to create builds on a snapshot instead of working on the main stream, create a snapshot from the stream:

  • Right-click on the stream, select New, and choose Snapshot.
  • Later, in the Jazz Source Control tab, select the snapshot that you have created rather than the stream.
Figure 15. Jazz Source Control tab of the Build Definition view
Jazz Source Control tab view
  1. In the Command Line tab of the Build Definition window shown in Figure 16:
    1. Enter the build script or build file or the build command in the Command field. This script or command will be invoked when users request a build.
    2. In the Arguments field, enter the command line arguments, if any.
    3. In the Working directory field, enter the working directory to be used by the invoked command.
    4. If any external properties file that the build is using, mention the file name in Properties file field.

In the Command field, you can directly specify the Ant file (build.xml) or any script that invokes Ant.

Figure 16. Command Line tab of the Build Definition
Command line tab view
  1. After you have entered all information in the Build Definition tabs, Save the definition.
  2. To request a build, right-click on the build definition that you created, and select Request Build from the drop-down menu.
  3. In the Request Build window, Browse for the build engine created under Build options. Mention the build properties, if any, in Build Properties, and click Submit.
Figure 17. Request a build with the available build engine
Request Build dialog window

For the build to be started, make sure that the Jazz Build Engine (JBE) is running with the same username as the owner of the workspace.

  1. The build starts with loading the source files to the local build machine and then executes the build command.
  2. After the build is finished, the screen displays details, along with log file (Figure 18).

If work item needs to be created, you can do it by clicking Create Work item or Associate on existing work item.

Figure 18. Rational Team Concert summary of the build status
Green area shows Completed as build status



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). If you would prefer, you can try it in the sandbox instead, without installing it on your own system.
  • 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=Create software builds with Jazz Team Build