Three ways to take full advantage of Rational Build Forge

Use APIs and integrate a Jazz repository to do more with Build Forge

Many developers use IBM® Rational® Build Forge® to handle software builds through its management console. But it also has includes an excellent set of command line Java and Perl APIs. Plus, it integrates with Jazz technology-based software which can provides a complete and integrated set of test, build, change and release management tools. This article explains how, complete with sample code.

Share:

Ashish Aggarwal (ashisagg@in.ibm.com), System Software Engineer, IBM

author photoAshish Aggarwal, a system software engineer, develops and consults on automation tools for the Systems and Technology Group and has been with IBM for more than three years. He is involved with many IBM forums, such as Quality Software Engineering (QSE) and developerWorks forums.



12 July 2011

Also available in Chinese

About this article

IBM® Rational® Build Forge® is IBM's flagship product for build and release management. It not only provides an amazing potential to automate the build process but also to automate the testing procedures for any team.

For most developers, the use of Build Forge has been confined to using the management console, or the graphical user interface (GUI). Many teams are unaware that Build Forge can also be connected through a client and that it can integrate with IBM® Rational® Jazz™ technology-based software, too. When teams need to create or integrate their custom build and test solutions with Build Forge, application programming interfaces (APIs), known as Build Forge clients and provided by Build Forge, play an important role. The client gives you a simple and robust way to add, update, modify, and interact with the Build Forge objects in the same manner that the management console does.

This article provides details on how teams can use the client and Jazz plug-ins to take better advantage of the potential of Rational Build Forge.


Rational Build Forge overview

Rational Build Forge enables high-performance builds and agile software development. Its adaptiveness helps development teams standardize repetitive tasks, manage compliance mandates, and share information. It automates and accelerates software assembly and delivery processes and streamlines build management.

Build Forge integrates into your current environment and supports major development languages, scripts, tools, and platforms. You can continue using your existing investments, while adding valuable capabilities for process automation, acceleration, notification, and scheduling.

In real-world scenario, each team has its own processes, which are often manual, and essential tools, such bug tracking and source code management, are rarely integrated. But there is an increasing need for more stable and high-quality products, and this requires integration, repeatability, with high reliability.

For such purposes, teams generally have custom scripts, but things are much more complex than just a script, because you often need support for multiple versions, multiple platforms, and multiple editions. This is where Rational Build Forge takes the automation of software assembly processes to new levels, for faster software development and delivery cycles, higher product quality, increased staff productivity, and a shorter time-to-market.

Rational Build Forge can help your team achieve these objectives faster and easier:

  • Reuse existing scripts and infrastructure to support automation
  • Automate, optimize, and standardize complex software delivery lifecycle
  • Integrate diverse tools to manage various project configurations
  • Provides build acceleration, server management, automatic notification, scheduling, robust security, and much more
  • Use the Eclipse IDE plug-in for better management
  • Simplify and reduce administration with a common installation experience for both Microsoft Windows and UNIX operating systems
  • Automate and streamline software assembly processes in enterprise environments
  • Continue the tradition of strong language and multiplatform support

Rational Build Forge architecture

Build Forge architecture is designed in such a way that you can use nearly all of the capabilities on the management console, as well as through the Build Forge client. As Figure 1 shows, the architecture provides a simple access, implement (server), and run (agent) mechanism.

Figure 1. IBM Rational Build Forge architecture
Workflow diagram: access, implement, execute

As Figure 1 illustrates, Build Forge is made up of a web interface component (Apache web server and PHP), a services layer component, and an engine component. The web interface, engine components, and API program clients are clients of the services layer component.

Access

You can communicate with the Build Forge server using the management console or the Build Forge client provided during installation. This helps to manage users and resources, to set up and schedule test projects, and to generate and analyze reports. The management console is http-based web application running on an Apache http server, but the client is available in Java and Perl.

Implement (server)

At the core of the architecture is the Build Forge server, which consists of the web interface component (Apache web server and PHP), a services layer component, and an engine component. The server can be installed on platforms such Microsoft Windows, Linux, IBM® AIX®, and it can be run with many databases, such IBM® DB2®, MySQL, and Oracle. The service layer facilitates connection with the management console as well as the client. This can help in seamless integration with existing IDEs and source code management (SCM) tools.

Run (agent)

Build Forge executes the command on the end server with the help of Build Forge agents. An agent takes the order from the Build Forge engine, runs the specified commands on the system under test, and returns the result to the engine. Agents can run in several environments, such as Windows, Linux, AIX, Solaris, HP-UX, IBM® System z® series, IBM® System i®, and Macs.


Introducing the Build Forge client

Rational Build Forge is the workflow engine in the architecture. It is a straightforward product that you can use to specify projects that contain steps to be executed. The steps can be one or more commands that will be executed on a selected server in the test infrastructure. But currently, all of these operations are initiated mainly from the Build Forge management console, which minimizes the possibility of integration with integrated development environments (IDEs), software configuration management (SCM) tools, and so forth.

However, you can resolve this problem by using the Build Forge client, which can help in providing seamless integration with other tools. The client also provides a simple yet robust way of accessing any of the Build Forge objects and does almost all of the operations that you normally do by using the console.

The Build Forge Version 7.0.1 release introduces a service layer that runs in the Apache Tomcat servlet container. Build Forge APIs are available as Java clients and Perl clients, which are built on top of a service layer. Before the 7.0.1 release, only Perl APIs were available (not the Perl client).

Getting started with the Build Forge client

  1. Download the client file from this location:
    http://server_name:server_port/clients/.
  2. Download the Java or Perl client under the Services Layer section, as required.
    • To use the Java client, download the client file, extract the rbf-services-client.jar file, and put it in appropriate build path of the Java project.

      Note:
      JDK 1.5 or above is required to use Build Forge Java client.
    • To use the Perl client, extract the .zip file, go to the rbf-services directory, and run the command shown in code Listing 1 (you need Perl 5.8 or above to use it):
  3. The Build Forge client communicates with the services layer directly. During installation, the Apache Tomcat server is configured to listen on particular ports. Therefore, those ports must be open for the client to communicate with Build Forge. By default, the ports are set to the following:

    3966 (non-secure)
    49150 (secure, SSL-enabled)
Listing 1. Installing the Perl client
perl Makefile.PL
make
make install

Tips:

  • Along with clients, you can also download client reference files.
  • In the remaining sections, we provide the examples using the Java client, but you can also use the Perl client for the same purpose.

To starting working with the Build Forge client, you need to first connect with the Build Forge Services Layer.

  1. In the code example in Listing 2, just provide the Build Forge server name and port number (which is optional in case of default port number).
Listing 2. Connect to Build Forge
import java.io.IOException;

import com.buildforge.services.client.api.APIClientConnection;
import com.buildforge.services.common.ServiceException;

public class ConnectToBuildForge {
  public static void main(String[] args) {
    try{
      APIClientConnection conn = new 
      APIClientConnection(<server_name>,<port_number>);
      // In case of default port, do not specify any port number
			
      String login_token = conn.authUser(<username>,<password>);
      // Return value is a login token returned by the services layer
			
    }catch (ServiceException e) {
      System.out.println("Service Exception:" + e.getMessage());
    }catch (IOException e) {
      System.out.println("IOException Exception:" + e.getMessage());
    }
  }
}

Possible race conditions when using clients

The process of fetching data through the API is simple. However, there is an important concept to remember: After data is pulled from the Services Layer through the API (and through the web interface), it is stale until refreshed.

The API does not automatically refresh data objects after they are initially retrieved; data objects are updated only when they are retrieved again. In essence, when an object is pulled from the services layer, a local copy is created to operate on. This behavior can lead to race conditions and problems, such as modifications getting overwritten, depending on how and when the data is accessed. This is the nature of a concurrent user application and should be taken into consideration with any API program that modifies data.

  1. Next, provide a username and password to authenticate.
  2. After authentication, it's important to save the APIClientConnection object for future a purpose. Make sure that the authenticated user has the appropriate privileges to work with Build Forge objects. To provide or check privileges, go to User > Access Groups.

Note:
Client objects and management console objects use the same session; therefore, the same user cannot authenticate in parallel from both ways.

Working examples

In the following code listings, we will illustrate some of commonly used operations, such as create, update, list, and delete.

Note:
We used the Build Forge 7.1.1.4 Java client for the purpose

Listing 3. Create a user
import java.io.IOException;

import com.buildforge.services.client.api.APIClientConnection;
import com.buildforge.services.client.dbo.User;
import com.buildforge.services.common.ServiceException;

publicclass CreateUser {

/**
* Creates a new user
* @param args
*/
  publicstaticvoid main(String[] args) {

    try{
      APIClientConnection conn = new 
      APIClientConnection(<server_name>,<port_number>); 
      // In case of default port, do not specify any port number
      conn.authUser(<username>,<password>);
	   
      User user = new User(conn);
      user.setLogin(<login_name>);
      user.setPassword(<password>);
      user.setEmail(<email>);
      user.setName(<name>);
      user = user.create();
      user.addAccessGroup(<access_group>);
	
    }catch (ServiceException e) {
      System.out.println("Service Exception:" + e.getMessage());
    }catch (IOException e) {
      System.out.println("IOException Exception:" + e.getMessage());
    }
  }
}
Listing 4. Update a test project
import com.buildforge.services.client.api.APIClientConnection;
import com.buildforge.services.client.dbo.Project;

publicclass UpdateTestProject {

/**
* Creates a new test project
* @param args
*/
  publicstaticvoid main(String[] args) {
    try{
      APIClientConnection conn = new 
      APIClientConnection(<server_name>,<port_number>); 
      // In case of default port, do not specify any port number
      conn.authUser(<username>,<password>);
	   
      Project project = new Project(conn);
      project.setName(<project_name>);
      project.setSelectorUuid(<selector_uuid>);
      project.setBuildClassUuid(<buildclass_uuid>);
      project.setActive(true);
      project.setLevel(<level>);
      project = project.update();
	
    }catch (ServiceException e) {
      System.out.println("Service Exception:" + e.getMessage());
    }catch (IOException e) {
      System.out.println("IOException Exception:" + e.getMessage());
    }
  }
}
Listing 5. List environment values
import java.util.List;

import com.buildforge.services.client.api.APIClientConnection;
import com.buildforge.services.client.dbo.Environment;
import com.buildforge.services.client.dbo.EnvironmentEntry;

public class ListEnvironmentEntries {

/**
* Returns the list of all Environments Entries in an Environment
* @param args
*/
  public static void main(String[] args) {
    try{
      APIClientConnection conn = new 
      APIClientConnection(<server_name>,<port_number>);
      // In case of default port, do not specify any port number
      conn.authUser(<username>,<password>);
      Environment env = Environment.findByUuid(conn, <env_uuid>); 
      // Find environment
	   
      if(env!=null){ // Find environment entries only if environment exists
        List<EnvironmentEntry> ls = env.getEntries(); // Get environment entries
        for(EnvironmentEntry env_entry : ls){
          System.out.println("Environment Entry Uuid:" + env_entry.getUuid());
          System.out.println("Environment Uuid:" + env_entry.getEnvironmentUuid());
          System.out.println("Environment Entry Parameter Name:" + 
          env_entry.getParameterName());
          System.out.println("Environment Entry Parameter Value:" + 
          env_entry.getParameterValue());
        }
      }
    }catch (ServiceException e) {
      System.out.println("Service Exception:" + e.getMessage());
    }catch (IOException e) {
      System.out.println("IOException Exception:" + e.getMessage());
    }
 }
}
Listing 6. Fire project and find results
import java.util.List;

import com.buildforge.services.client.api.APIClientConnection;
import com.buildforge.services.client.dbo.Build;
import com.buildforge.services.client.dbo.Project;
import com.buildforge.services.client.dbo.Result;

publicclass FireProjectAndFindResults {

/**
* Fire project and find corresponding results
* @param args
*/
  publicstaticvoid main(String[] args) {
    try{
      APIClientConnection conn = new 
      APIClientConnection(<server_name>,<port_number>);
      // In case of default port, do not specify any port number
      conn.authUser(<username>,<password>);
	  
      Project project = Project.findByUuid(conn,<project_uuid>);
	
      if(project!=null){ // Fire project if only it exists
        Build build = project.fire();
        // Sleep for some seconds
        List<Result> ls = build.getResults();
        Result result = null;
		
          for(Result result : ls){
            System.out.println("Build Uuid:" + result.getBuildUuid());
            System.out.println("Result Step Description" + result.getDescription());
            System.out.println("Result Step Duration" + result.getDuration());
            System.out.println("Result" + result.getResult().name());
          }
      }
	
    }catch (ServiceException e) {
      System.out.println("Service Exception:" + e.getMessage());
    }catch (IOException e) {
      System.out.println("IOException Exception:" + e.getMessage());
    }
  }
}

These examples show some of the operations on the Build Forge objects, using the Java client. You will find it helpful to explore more such operations and use them to their maximum potential. See the help provided with the Java and Perl client.


Connect with Jazz products to get a complete set of tools

In the previous sections, you worked with the Java or Perl client just to connect with Build Forge. But Rational Build Forge also provides a very robust integration with some of the useful software based on the Jazz foundation, such as IBM Rational Quality Manager and IBM Rational Team Concert.

  • Rational Quality Manager is the hub of test activity. It can help you plan the tests, manage requirements, develop test cases and test suites, maintain test execution records, manage lab resources, and submit and track defects.
  • Rational Team Concert can help you manage source code, as well as track defects, work items, and iteration plans. This helps testers, developers, architects, and managers work together more effectively.

Therefore, integration of Rational Quality Manager and IBM Rational Team Concert with Rational Build Forge can help any team provide a complete set of tools for change and release management.

Note:
We are using Build Forge 7.1.1.4 to achieve the integration.

Integration with Rational Quality Manager

  1. Edit the buildforge.conf file in Build Forge installation (which can be found at ../buildforge/apache/tomcat/webapps/rbf-services/WEB-INF/classes/buildforge.conf in windows installation) and add the following line:

    db_system_password password

    where "password" is the password used to integrate Build Forge and Rational Quality Manager (RQM).
  2. If Build Forge and Rational Quality Manager are installed on same server, then open the server.xml file (…/apache/tomcat/conf/server.xml), and change the port number from 8005 to 8007 in this line:
    <server port="8005" shutdown="SHUTDOWN">
  3. Open integration_config.xml in Rational Quality Manager, and delete the <!-- and --> tags at the start and end of the code. Then provide the Build Forge server name inside of the <hostname></hostname> tag and the password that you mentioned in buildforge.conf file within the <password></password> tag.
  4. Give a meaningful name for the Build Forge server within the <instanceID></instanceID> tag.

Listing 7 shows an example.

Listing 7: integration_config.xml file
<?xml version="1.0" encoding="UTF-8"?>
<RTLMExtensionAPIRegistration>
<adapter>
<name>Build Forge RQM Integration </name>
<version>1.0</version>
<APIVersionSupported>1.0</APIVersionSupported>
<inventoryExtensionId>com.ibm.rational.test.lm.spi.bf.v71.inventory
  </inventoryExtensionId>
<automationExtensionId>com.ibm.rational.test.lm.spi.bf.v71.automation
  </automationExtensionId>
<pluginId>com.ibm.rational.test.lm.spi.bf.v71</pluginId>
<instance>
<instanceId>some meaningful name</instanceId>
<hostname>Build Forge server name</hostname>
<port>Build Forge server port</port>
<offline>FALSE</offline>
<credential>
<username>Build Forge server username</username>
<password>Integration password</password>
</credential>
</instance>
</adapter>
</RTLMExtensionAPIRegistration>

Note:
In case Rational Quality Manager is installed on an IBM® WebSphere® Application Sever, provide the path integration_config.xml in the Java system property at Application servers > server1 > Process Definition > Java Virtual machine > Custom Properties, and add a custom property named com.ibm.rational.test.lm.spi.xml.location.

Integration with Rational Team Concert

Rational Team Concert (RTC) integration helps to integrate Build Forge automation and the traceability and collaboration that you get with Team Concert. When the build is triggered in Build Forge, the RTC-Build Forge plug-in keeps updating each step and its results to provide real-time status. At the end of the build, step results and logs and BOM data will be in the Rational Team Concert Build Result.

For complete integration steps, see the first link in the Resources section.

Resources

Learn

Get products and technologies

  • Check the Trials and Demos page for Rational software.
  • 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

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=696523
ArticleTitle=Three ways to take full advantage of Rational Build Forge
publish-date=07122011