Configuring RTC to call Build Forge
using a Simple Example
This document can be used for training on RTC and Build Forge. This document includes
both end user and administrator information including an explanation of RTC related Ant
targets used by the Build Forge project to allow for progress monitoring, source code
checkout, and build result publishing
Version 1.0 – December 10, 2013
Author: Bruce Besch
Table of Contents
CONFIGURING RTC TO CALL BUILD FORGE USING A SIMPLE EXAMPLE ...................................... 3
CONFIGURATION OF RTC AND BUILD FORGE ..................................................................................... 3
CREATE THE PROJECT AREA AND USER(S) WITHIN RTC .................................................................... 3
CONFIGURE RTC SOURCE CONTROL ..................................................................................................... 5
CREATE THE PROJECT AND USER FOR CONNECTION IN BUILD FORGE ........................................ 7
Creating a local Build Forge User for RTC .................................................................................................. 7
Setting up the Build Forge Project to be leveraged by RTC ......................................................................... 9
THE ANT TASKS LEVERAGED BY BUILD FORGE TO TALK TO RTC ................................................17
Generic Ant Targets for Progress Monitoring ........................................................................................... 20
RTC Source Control Ant Targets ................................................................................................................ 21
Publishing Build Results and Contributions Ant Targets ........................................................................... 23
RTC Ant Target Reference ................................................................................................. ......................... 25
CREATE THE RTC “BUILD ENGINE” AND “BUILD DEFINITION” FOR USE WITH BUILD FORGE
........26
Creating the Build Forge “Engine” in RTC ............................................................................................. 26
Creating the RTC “Build Definition” to point at the Build Forge Server ............................................... 28
REQUESTING THE BUILD AND VIEW THE RESULTS OF THE INTEGRATION ...............................33
Configuring RTC to call Build Forge using a Simple Example
The purpose of this document is to provide a handy step-by-step guide for the configuration and
setup of RTC calling out to Build Forge for build or deploy automation. I found information on
how to do this work scattered in many different documents and decided that creating this
instruction guide would be helpful for those struggling to understand how to set this up. The
steps include setting up the RTC build engine, build definition, properties to pass to Build Forge,
as well as how to setup the Build Forge project. This document does not cover the installation of
RTC or Build Forge as other documents cover this in detail.
Configuration of RTC and Build Forge
For the purposes of this document, our installation of RTC 4.0.1 and Build Forge 7.1.3.4 were
completed on the same machine. Some important points from a Build Forge perspective that
will make your life a lot easier when attempting to configure this integration:
a) Do not configure Build Forge to leverage SSL
b) Do not configure Build Forge to use the non-standard Apache/Tomcat web server that comes
with the product out-of-the-box.
Create the Project Area and User(s) within RTC
A new RTC project was created based off the Scrum process template. Users from the Money
that Matters Sample project were then added to the new project area. Steps performed:
1. Login to the RTC Eclipse client as clmadmin/clmadmin.
2. Create the project area. Right-click on [email protected] connection and click
New > Project Area.
3. Name the project, if this example the project is named “HelloWorldAnt_SCM” . Select Scrum
Process template and click finish.
4. Review or add process roles. Right click HelloWorldAnt_SCM and select Open. Click the
Process Configuration tab. In the Configuration section, select Roles.
5. Optional – Create Team Areas. In this example the following Teams were created,
Development, Production, and QA. In the Project Area editor, click Show in Team Organization
at the top of the editor window.
6. Optional - In the Team Organization view, expand the HelloWorldAnt_SCM project. Right-click
the HelloWorldAnt_SCM project, and click New > Team Area to create a top-level
HelloWorldAnt_SCM team. Create substeams by right-clicking HelloWorldAnt_SCM Team and
clicking New > Team Area.
7. Add users to team areas and assign process roles.
Configure RTC Source Control
This section documents how to check the source code for HelloWorldAnt_SCM into Rational
Team Concert. You will need to unzip HelloWorldAnt_SCM into a location on your file system.
Peform the following steps:
1. Login to RTC Eclipse client as clmadmin/cladmin.
2. Open the Java perspective, and go to the Package Explorer view.
3. Right-click in the Package Explorer view, and click New > Java Project.
4. In the New Java Project window, name the project HelloWorldAnt_SCM. Accept the default
values for all other entries, and then click Finish.
5. In the Package Explorer view, click HelloWorldAnt_SCM > src.
6. Right-click the src folder, and click Import.
7. In the Import window, click General > Filesystem. Click Next.
8. In the From Directory field, specify the location of the HelloWorldAnt_SCM souce code folder.
(The location you unzipped HelloWorldAnt_SCM earlier.)
9. In the Into Folder field, ensure that HelloWorldAnt_SCM/src is specified and click Finish.
10. In the Package Explorer view, right click the HelloWorldAnt_SCM project folder, and then
click Team > Share Project.
11. Select Jazz Source Control as the repository type and click Next.
12. Expand HelloWorldAnt_SCM Stream Workspace and select HelloWorldAnt_SCM Default
Component as the location to share this project. Click Finish.
13. In the Pending Changes view, expand the HelloWorldAnt_SCM workspace and default
component, and right-click the Outgoing folder. Click Deliver.
14. Optional – Create new snapshot for start of project.
Create the Project and User for connection in Build Forge
This section documents how to setup the Build Forge Project to execute a build that is invoked
by RTC. It also describes how to create a local Build Forge user account that is leveraged by the
RTC “build engine” for remote connection.
Creating a local Build Forge User for RTC
When RTC connects to the Build Forge Server, you should create a unique user for these RTC
connections in the Build Forge administrative web console. To do this, follow these steps:
1. Login to the Build Forge web console as root.
2. Click on Administration in left-hand navigation menu.
3. The “Users” view should appear. Click “Add User”
4. Create a user “build” and specify a name of “build” and password of “build”.
5. Set “Password Expires” to “No”.
6. Set “User Type” to “API_User” (if possible).
7. Click “Save”
NOTE: when you create the Build Forge user for access from RTC, you should make sure this
user is an API user (assuming the customer is using Build Forge 7.1.3 or later) to avoid someone
accidentally logging it off by logging into the Build Forge UI. Finally, an API user is not allowed to
login to the Build Forge console which can be helpful too from a separation of duty perspective.
You may want to modify the “groups” he has access to all roles and privileges for the demo. To
do this, click “Change Groups” for the build user and then move everything to the right side as
shown below.
You are finished!
Setting up the Build Forge Project to be leveraged by RTC
The Build Forge project for this example compiles a simple HelloWorld java program. To invoke
the build, I will leverage ANT and this is required for many of the RTC related integrations. I will
discuss those integration points as I describe this Build Forge project.
Install the Build Forge Agent and Create the Build Forge Server Object
I installed the Windows agent on the same machine as the RTC Server and Build Forge Server.
After doing this installation, I then followed these steps:
1. Install the Windows version of the Build Forge agent. Take the defaults to run it as a service
and leverage port 5555.
2. Create a Build Forge “Server Auth” object
3. Create the C:\builds folder on the file system of the build machine and make sure it has the
appropriate permissions for read, write, execute.
4. Create a Build Forge “Server” object pointing at the agent I just installed. Select our new
“Server Auth” and set the Path directory to C:\builds.
5. Test the connection and ensure it can connect to the agent without any issues.
6. Create a Build Forge “Selector” object to point at this Server Object.
You are finished with this step!
Create the Build Forge E_HelloWorldJava_Ant_SCM Environment Group
Before I create the Build Forge Project, create a Build Forge “Environment Group” that can be
empty without a single variable in it. In my case, I created “E_HelloWorldJava_Ant_SCM”.
Leave it empty for now and let’s continue with creation of the Project.
Copy Supporting Build Files to C:\builds
Before I begin the creation of the Build Forge project, I need to copy two files needed for the
build to succeed to the C:\builds folder.
1. Copy “build.xml” to C:\builds
2. Copy “MANIFEST.MF” to C:\builds
The build.xml is an ANT based file that contains various targets for performing the build. In the
design of this solution, I made the decision to not check in this build.xml into the source control
although it certainly can be checked in. What I do is leverage Build Forge to create a clean
“sandbox” directory under C:\builds every time is a build is invoked. The “build.xml” file is
copied to this “sandbox” and then I invoke the targets to pull down the source into the
“sandbox” directories and compile the code.
The MANIFEST.MF is used when generating the JAR file for the build. Here is the contents of the
file:
Manifest-Version: 1.0
Main-Class: com.hello.world.HelloClient
I can now continue with the creation of the project in Build Forge.
Create the Build Forge HelloWorldJava_Ant_SCM Project
Follow these steps:
1. Click on Projects in the Build Forge web interface navigation bar on left
2. Click “Add Project”
3. Give the Project a name, HelloWorldJava_Ant_SCM
4. Set your selector to “localhost” or whatever you created earlier.
5. Set your environment to “E_HelloWorldJava_SCM”
6. Click Save
7. This will take you to the Project view. Before I continue, change the Tag for the project to
“HelloWorldJava_Ant_SCM_$B” as shown in the screen shot below:
8. Back in the Project view, create your first step as shown below to copy the build.xml and
MANIFEST.MF file to our relative path “sandbox” created in the
C:\builds\HelloWorldJava_Ant_SCM\HelloWorldJava_Ant_SCM_1 folder.
NOTE: I embed the build tag into the J2EE manifest of the JAR in the example above
9. The next two steps will be used to check out the code from the RTC SCM repository. It
involves an “accept” and then a “fetch” action. This step performs the “accept”:
NOTE: that I created an “ANT_Filter” log filter to search for “BUILD FAILED” from ANT so it
would mark the step as failing.
NOTE: I am using the –D option to ant to pass a variable to the build.xml script. It is necessary
to pass –lib with the path to the RTC build toolkit as well.
10. The next step does the RTC fetch:
11. This will result in the source files for the build being placed in this directory at build
execution time to the local “sandbox”
(C:\builds\HelloWorldJava_Ant_SCM\${BF_TAG}\HelloWorldAnt_SCM\src\com\hello\world):
12. Our final step will do the compile, jar, and publish of the jar back to RTC as shown below:
13. At runtime of this build, this step (above) will generate the “helloWorld.jar” file in the
directory that looks like this:
As you can see, this is a simple build process but it helps to highlight the integrations between
RTC and Build Forge. I will dig into the integrations in more detail shortly.
Here is a screen shot of the ANT_Filter:
You now have the Build Forge project ready to go. Before I continue, I need to discuss the
build.xml file that contains the ant targets to call back to RTC.
The ANT tasks leveraged by Build Forge to talk to RTC
The build.xml file describes to ANT various targets that can be called to perform checkouts of
code, compilation, package, and execution of the java code that was generated. Here is the
build.xml for you to review:
<?xml version="1.0"?>
<project name="helloWorld" default="publish" basedir=".">
<target name="init">
<property name="name" value="helloWorld" />
<property name="src.dir" value="HelloWorldAnt_SCM/src" />
<property name="build.dir" value="bin" />
<property name="deploy.name" value="${name}.jar" />
<property environment="env" />
</target>
<target name="prepare" depends="init">
<echo message="Repo Address is ${env.repositoryAddress}"/>
<startBuildActivity activityIdProperty="prep" label="Preparing directories..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<mkdir dir="${build.dir}" />
<completeBuildActivity activityId="${prep}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="clean" depends="init">
<startBuildActivity activityIdProperty="clean"
label="Cleaning directories..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<delete dir="${build.dir}" />
<completeBuildActivity activityId="${clean}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="scm_accept" depends="prepare">
<startBuildActivity activityIdProperty="rtc-accept"
label="Accepting any incoming RTC changes to the stream..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<teamAccept repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}"
workspaceUUID="${env.team_scm_workspaceUUID}"
buildResultUUID="${buildUUID}"
changeSetFile="workitems-randy.txt"
snapshotName="snapshot_dev_${env.B}"
verbose="true" />
<completeBuildActivity activityId="${rtc-accept}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="scm_fetch" depends="prepare">
<startBuildActivity activityIdProperty="rtc-fetch"
label="Fetching all RTC code..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<mkdir dir="${java.io.tmpdir}/toolkittest" />
<teamFetch repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}"
workspaceUUID="${env.team_scm_workspaceUUID}"
buildResultUUID="${buildUUID}"
destination="${bfRoot}"
verbose="true" />
<completeBuildActivity activityId="${rtc-fetch}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="compile" depends="prepare">
<startBuildActivity activityIdProperty="compile"
label="Compiling java files..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<javac srcdir="${src.dir}" destdir="${build.dir}" debug="true" deprecation="true"
optimize="false" includeantruntime="false"/>
<completeBuildActivity activityId="${compile}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="java" depends="compile">
<startBuildActivity activityIdProperty="java"
label="Executing java file"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<copy file="HelloWorldAnt_SCM/src/hello.properties" todir="${build.dir}/com/hello/world"
overwrite="true" />
<java classname="com.hello.world.HelloClient">
<classpath>
<pathelement location="${build.dir}"/>
<pathelement location="${basedir}"/>
</classpath>
</java>
<completeBuildActivity activityId="${java}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="jarfile" depends="java">
<startBuildActivity activityIdProperty="jarfile"
label="Generating jar file"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<copy file="HelloWorldAnt_SCM/src/hello.properties" todir="${build.dir}/hello"
overwrite="true" />
<jar destfile="${build.dir}/${name}.jar" basedir="${build.dir}" manifest="MANIFEST.MF" />
<completeBuildActivity activityId="${jarfile}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<target name="publish" depends="jarfile">
<startBuildActivity activityIdProperty="publish"
label="Publishing jar file back to RTC..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
<echo message="Build Result UUID: ${buildUUID}" />
<echo message="Build Result Requester: ${env.buildRequesterUserId}" />
<echo message="Respository Address: ${env.repositoryAddress}" />
<artifactFilePublisher repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}" password="${env.BUILD_PASSWD}" buildResultUUID="${buildUUID}"
filePath="${build.dir}/${name}.jar" label="HelloWorld.jar" />
<workItemPublisher repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}"
buildResultUUID="${buildUUID}"
filePath="workitems-randy.txt" />
<completeBuildActivity activityId="${publish}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}" />
</target>
<taskdef name="artifactFilePublisher"
classname="com.ibm.team.build.ant.task.ArtifactFilePublisherTask" />
<taskdef name="startBuildActivity"
classname="com.ibm.team.build.ant.task.StartBuildActivityTask" />
<taskdef name="completeBuildActivity"
classname="com.ibm.team.build.ant.task.CompleteBuildActivityTask" />
<taskdef name="completeBuildActivity"
classname="com.ibm.team.build.ant.task.CompleteBuildActivityTask" />
<taskdef name="workItemPublisher"
classname="com.ibm.team.build.ant.task.WorkItemPublisherTask"/>
<taskdef name="teamAccept"
classname="com.ibm.team.build.ant.task.TeamAcceptTask">
</taskdef>
<taskdef name="teamFetch"
classname="com.ibm.team.build.ant.task.TeamFetchTask">
</taskdef>
</project>
I will now break down this build.xml to explain the RTC related ANT targets in more detail.
Generic Ant Targets for Progress Monitoring
During the execution of the build, the following generic ANT targets are leveraged:
ildActivity
<target name="clean" depends="init">
<startBuildActivity activityIdProperty="clean"
label="Cleaning directories..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb" />
<delete dir="${build.dir}" />
<completeBuildActivity activityId="${clean}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb" />
</target>
These targets enable progress monitoring update back to RTC as the build execution is in
progress. In this case, as Build Forge invokes these targets, progress updates are sent back to
RTC and is visible inside the RTC client.
These two variables are picked up via the Build Forge environment group associated with the
project:
RTC automatically passes these variables to Build Forge when the build is triggered. For some
reason, the ${buildResultUUID} variable was not being resolved in our script in the same manner
(i.e. using ${env.buildResultUUID}) so I passed the variable as an argument via the ANT
command and referred to the variable like this in the build.xml file:
buildResultUUID="${buildUUID}"
To do this, our ANT command to invoke the build passes the ${buildUUID} variable to the
build.xml file:
ant –DbuildUUID=${buildResultUUID} –f ${BF_ROOT}\build.xml –lib
C:\IBM\TeamConcertBuild\buildsystem\buildtoolkit
Notice that I do this via the –D command line argument. Further, in order to take advantage of
these targets, you must include the RTC buildtoolkit directory in your library path for ANT.
Finally, the last thing you must to do leverage all of these targets is to declare the task
definitions at the bottom of the build.xml so they can be resolved appropriately. Here they are:
<taskdef name="artifactFilePublisher"
classname="com.ibm.team.build.ant.task.ArtifactFilePublisherTask" />
<taskdef name="startBuildActivity"
classname="com.ibm.team.build.ant.task.StartBuildActivityTask" />
<taskdef name="completeBuildActivity"
classname="com.ibm.team.build.ant.task.CompleteBuildActivityTask" />
<taskdef name="teamAccept"
classname="com.ibm.team.build.ant.task.TeamAcceptTask">
</taskdef>
<taskdef name="teamFetch"
classname="com.ibm.team.build.ant.task.TeamFetchTask">
</taskdef>
startBuildActivity The startBuildActivity task starts a new build activity for a build. A
build might have multiple activities in progress at any time. You can organize activities
hierarchically. When an activity is started, you can specify an existing parent activity for
it. Activities can be completed explicitly (see completeBuildActivity) or automatically if the
autoComplete attribute is set.
completeBuildActivity The completeBuildActivity task completes an existing build
activity.
NOTE: you can generally remote the <completeBuildActivity> tasks if you specify
autoComplete=”true” on the <startBuildActivity> tasks. This could simplify the script, however, I
wanted to include it for clarity in this demonstration.
RTC Source Control Ant Targets
For our simple Build Forge project, I leverage RTC for source control although it could be
something else like Subversion or CVS. When working with RTC, I have to invoke two targets to
checkout the source code for the build and these ANT targets must be invoked in this order:
1. teamAccept - accept any incoming changes to the stream
2. teamFetch – fetch all the data
The “scm_accept” target calls <teamAccept> as shown below. I specify a “changeSetFile”
argument to discover the “work items” associated with the incoming changes to the stream. I
need to save this away because at the end of the build I will publish the “work items” associated
with the build back to the RTC build record from a Build Forge ant target <workItemPublisher>.
<target name="scm_accept" depends="prepare">
<startBuildActivity activityIdProperty="rtc-accept"
label="Accepting any incoming RTC changes to the stream..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb" />
<teamAccept repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb"
workspaceUUID="${env.team_scm_workspaceUUID}"
buildResultUUID="${buildUUID}"
changeSetFile="workitems-randy.txt"
snapshotName="snapshot_dev_${env.B}"
verbose="true" />
<completeBuildActivity activityId="${rtc-accept}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb" />
</target>
Once again, for the <teamFetch> target, the variables used by this target are passed
automatically from RTC to Build Forge. There is a new one in play here which is the
${env.team_scm_workspaceUUID} variable.
<target name="scm_fetch" depends="prepare">
<startBuildActivity activityIdProperty="rtc-fetch"
label="Fetching all RTC code..."
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb" />
<mkdir dir="${java.io.tmpdir}/toolkittest" />
<teamFetch repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb"
workspaceUUID="${env.team_scm_workspaceUUID}"
buildResultUUID="${buildUUID}"
destination="${bfRoot}"
verbose="true" />
<completeBuildActivity activityId="${rtc-fetch}"
buildResultUUID="${buildUUID}"
repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}"
password="deb" />
</target>
Here are the source code related RTC targets:
teamAccept The teamAccept task accepts change sets from related workspaces.
Change sets are accepted from all incoming flow relationships.
teamFetch The teamFetch task fetches code from a team workspace and puts it in a
local destination.
teamLastModified The teamLastModified task determines the creation time of the
oldest baseline in the workspace that was created after the last Rational Team Concert
source controlchange anywhere within the specified folder. The output files should be
attached to the build as a log or download, so that you can maintain consistent
timestamps between different streams of development.
pluginOrganizer The pluginOrganizer task takes a source directory of plug-in and
feature directories and moves them to a target directory with plug-in and feature
subdirectories. If the plug-in and feature subdirectories do not exist in the target, they
are created. This is the directory structure that Eclipse pdebuild requires.
Publishing Build Results and Contributions Ant Targets
After the compile completes, I leverage a RTC related Ant target to publish the build result back
to RTC. I also leverage a RTC related Ant target to publish the work items associated with this
build.
<target name="publish" depends="jarfile">
<echo message="Build Result UUID: ${buildUUID}" />
<echo message="Build Result Requester: ${env.buildRequesterUserId}" />
<echo message="Respository Address: ${env.repositoryAddress}" />
<artifactFilePublisher repositoryAddress="${env.repositoryAddress}"
userId="${env.buildRequesterUserId}" password="deb"
buildResultUUID="${buildUUID}" filePath="${build.dir}/${name}.jar"
label="HelloWorld.jar" />
<workItemPublisher repositoryAddress="${env.repositoryAddress}"
userId="${env.BUILD_USER}"
password="${env.BUILD_PASSWD}"
buildResultUUID="${buildUUID}"
filePath="workitems-randy.txt" />
</target>
This target allows us to add an artifact contribution to a build result in RTC. The artifact is stored
directly in the Jazz repository. Artifact file contributions are shown on the downloads page of
the build result in RTC.
NOTE: this task should not be used to publish artifacts larger than 10 MB. You should store and
manage large artifacts outside of the repository.
The <workItemPublisher> target shown above will document the work items associated with
this build to the RTC build record. This section describes the Ant tasks that you can use to
publish build results and contributions:
artifactFilePublisher The artifactFilePublisher task adds an artifact contribution to a
build result. The artifact is stored directly in the Jazz repository. Artifact file contributions
are shown on the downloads page of the build result.
artifactLinkPublisher The artifactLinkPublisher task adds a link contribution to a build
result. The Jazz repository stores a URL link to the artifact. Artifact link contributions are
shown on the downloads page of the build result.
buildResultPublisher The buildResultPublisher task updates a build result in a team
repository.
cppunitLogPublisher The cppunitLogPublisher task adds a CPPUnit XML log as a
contribution to a build result.
filePublisher The filePublisher task publishes a file as a contribution to a build result.
All contributions within a build result have a primary extended contribution type
identifier, which helps you determine what type of contribution you are viewing. The
filePublisher task requires the client to identify all extended contribution identifiers. The
task is designed for scenarios where you have custom file-based contributions in build
results and the contributions require unique identifiers.
jdtCompileLogPublisher The jdtCompileLogPublisher task adds one or more JDT (or
ECJ) compiler logs as a contribution to a build result.
junitLogPublisher The junitLogPublisher task adds a JUnit XML log as a contribution
to a build result.
mstestLogPublisher The mstestLogPublisher task adds a MSTest TRX XML log as a
contribution to a build result.
nunitLogPublisher The nunitLogPublisher task adds a NUnit XML log as a contribution
to a build result.
linkPublisher The linkPublisher task adds a link as a contribution to a build result. You
can view the link contributions from the external links page of the build result editor.
logPublisher The logPublisher task adds a log as a contribution to a build result.
workItemPublisher The workItemPublisher task publishes work item information to
a build result.
RTC Ant Target Reference
All of the RTC Ant targets mentioned have more detailed documentation available at this
location:
http://pic.dhe.ibm.com/infocenter/rtc/v2r0m0/index.jsp?topic=/com.ibm.team.build.doc/topic
s/r_ant-tasks.html
Now that I have everything setup in Build Forge and have our build.xml ready to go, let’s create
the objects I need in RTC to complete the integration.
Create the RTC “Build Engine” and “Build Definition” for use with Build
Forge
These instructions provide a step-by-step guide for creating the “Build Engine” and “Build
Definition” for use with Build Forge Server.
Creating the Build Forge “Engine” in RTC
This Build Engine object pointing at the Build Forge server can be created once and used by
many. For example, a single reference can be used by many different RTC “build definitions” to
connect to that Build Forge server. The “build definition” will specify which Project in Build
Forge to execute.
Follow these steps:
1. In the RTC “Team Artifact” view, navigate to your Team Area (in my case HelloWorldAnt and
then expand the “Builds” node of the tree.
2. Right click on the “Build Engines” node of the tree and select “New Build Engine…” from the
popup menu.
3. Select “Create a new build engine” and click Next
4. Give your engine an ID, description, and then select the “Rational Build Forge” engine type
and click Finish.
5. The Build Engine properties window will appear. In lower portion of window, click the “Build
Forge” tab.
6. Enter the hostname of your Build Forge server. Further, enter the Build Forge user
name/password that should be used to connect to the server:
NOTE: you should create a user login/password in Build Forge for this connection
7. Click the “Test Connection” button to verify that it successfully connects to the Build Forge
server. It should succeed as shown below:
8. Click “Save” to save the Build Engine you created.
Creating the RTC “Build Definition” to point at the Build Forge Server
1. In the RTC “Team Artifact” view, find your Team Area and expand that node on the tree (in
my case it is “HelloWorldAnt”).
2. Right click on the “Builds” node of the tree and select “New Build Definition…” from the
popup menu.
3. Select “Create a new build definition” and click Next
4. Give your build definition an ID, Description, and select “Rational Build Forge” from the list of
available build templates in the list at the bottom.
5. Click Finish
6. The “Build Definition” screen appears. In the Overview tab, click “Add…” to add your
supporting Build Engine that I created in the earlier section.
7. Check the box for your build engine and click OK.
8. Click on the “Build Forge” tab at the lower portion of the Build Definition property window.
9. Click the “Get Projects” button to populate the list above with a view of all Projects found on
the Build Forge server.
10. Select your Project. In this case, HelloWorldJava_Ant. When you do this, RTC automatically
synchronizes the properties it needs to the Build Forge environment group associated with the
project selected.
11. Check the “Include all step logs” in the Build Forge Logs section on the right.
12. Click on the Properties tab
13. You must manually add the repositoryAddress property as shown below.
14. Return to the “Build Forge” tab (located at the bottom of the view) and click the Synchronize
Properties button so that the repositoryAddress property you just added is pushed to the Build
Forge project environment group.
15. Click the Save button.
All done
Requesting the Build and View the Results of the Integration
Now that everything is setup, I can now walk through the steps of requesting the build and
seeing the results of the integration. Follow these steps to request the build:
1. Launch the RTC client. Press OK to take the default workspace directory (for me it is a “deb”
user).
2. In the Team Artifacts perspective, expand the “HelloWorldAnt_SCM” node in the tree.
3. Expand the “Builds” child node in the tree.
4. Right click on the “HelloWorldAnt_SCM build” build definition and select “Request Build…”
from the pop-up menu.
5. Click the “Submit” button on the Request Build dialog that appears
6. When you do this, the “Builds” perspective in RTC will be updated to reflect status.
7. If you log in to the Build Forge management console and view the “Running” jobs, you will see
the build job executing as shown below:
8. When the job completes, the “Builds” perspective will show the result as shown below:
9. Double click on the latest build in the list to view the build record results in RTC as shown
below:
10. Click on the “Downloads” link to view any artifacts that were published to RTC that may be
downloaded. In this case, I published the helloWorld.jar file:
11. Click on the Overview tab to return to the main view and then click on the “Logs” link to
view the build log information:
12. Then click on one of the step logs (in this case 004 – Compile) to view the output of that step
that came from Build Forge:
13. Close this log output view.
14. Click on the “Overview” tab to return to the main build result view
15. Click on the “External Links” hyperlink. You should see this page:
16. If you click this external link, it will take you to the Build Forge management console where
you can login:
NOTE: it does not take you directly the job log. You have to navigate manually to it. This may be
a good feature request (or bug) to report to the RTC development team.
17. Click on the “Activities” tab in the build record in RTC. You should see all the build activities
as shown below:
These activities were logged with our RTC Ant targets (startBuildActivity and
completeBuildActivity)
18. Click on the Overview tab to return to the main build result view
19. Click on the “Show Changes” link to show the changes that went into this build.
20. They will be displayed in the Change Explorer perspective at the bottom.
21. You can also view the “work items” associated with the build by clicking the link next to
“Work Items” in the Contribution Summary area of the build record (see below):
22. If you click that link, you will see the work item details as shown below (in this case, defect
128 and then if you click on the Links tab, you can see the source code changes):
You are done.....