IBM Support

How to launch an IBM Rational Application Developer Build from Jazz Build Engine as an Ant build

Question & Answer


Question

How do you launch an IBM Rational Application Developer build from the IBM Rational Team Concert Jazz Build Engine, using the Ant Build definition type?

Cause

Rational Application Developer provides specialized Ant Tasks for building Java Enterprise Edition, Service Component Architecture and OSGi applications. These Ant Tasks are not available as a plain Java library, but as Eclipse plug-ins: they are packaged inside IBM Rational Application Developer (RAD), or in the IBM Rational Application Developer Build Utility.
For this reason, these tasks cannot be invoked directly from the IBM Rational Team Concert (RTC) Jazz Build Engine, using the Ant Build definition type.

Answer

To launch a RAD Build from the RTC Jazz Build Engine, using the Ant Build definition type, follow these general steps:
  1. Launch an initial Ant build file (RTCBuild.xml) from the Jazz Build Engine. This build file invokes an external process
     
  2. Execute Rational Application Developer in headless mode as part of the external process, using a second Ant build file (RADBuild.xml). You can use all the existing Rational Application Developer and Eclipse Ant Tasks in this external process.


Here is an example that shows how to import projects from an RTC Repository, build them with RAD, report any build errors to the RTC Build Results, and if the build succeeds, export an Enterprise Archive and upload it to the RTC Build Results.

Prerequisites:
  1. Install Rational Team Concert server
     
  2. Install Rational Team Concert Build Engine
     
  3. Install Rational Application Developer
     
  4. Install Rational Team Concert Client Extension for Eclipse IDE in the same package group as Rational Application Developer. Note that if you are using a 64 bit Package Group for Rational Application Developer, you need to use at least Rational Team Concert 3.0.1.1 (See Related information section for more information). Currently, this approach cannot be used with the Rational Application Developer Build Utility, and its applicability is therefore limited to the platforms supported by Rational Application Developer.
     
  5. Start the Jazz Build Engine (JBE) with a command like the following:

    C:\Program Files\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse>jbe-vm "\Program Files\IBM\TeamConcert\jdk\bin\java" -repositoryhttps://hostname:port/ccm -userId buildUser -pass buildUser
     
  6. Configure a Build Engine in Rational Team Concert
     
Procedure:

Create a new Build Definition:
  1. Create a new build
     
  2. Specify the ID
     
  3. Select Ant / Jazz Build Engine
     
  4. Select Next
     
  5. Select Jazz Source Control (This is needed so that the Rational Application developer workspace gets populated with the files from the repository)
     
  6. Select Next (You do not need to select any Post Build Options, however this depends on requirements)
     
  7. Select all default choices in the page called: Additional Configuration::
    General
    Schedule
    Properties
     
  8. Select Finish
     
Customize the new Build Definition:
  1. Go to Properties
     
  2. Select the workspace from which to build in Jazz Source Control. This is an RTC Repository Workspace. The owner of the workspace must be the same as the user given on the Jazz Build Engine Command line. You can set the owner in the workspace editor.
     
  3. Enter C:\temp\LoadDirectory in the Load Directory. This value will be available as the Ant property team.scm.fetchDestination . This means that RTC will load the contents of the RTC Repository into the selected location. This will also be the location where the RAD workspace will be created.
     
  4. Select Delete Directory before loading to ensure that you build on a new, empty RAD Workspace every time
     
  5. Enter the location of the RAD build script: C:/workspace/BuildScripts/RADBuild.xml in the Ant tab, Build File text area
     
  6. Select Include the Jazz Build toolkit tasks on the Ant Library Path
     
Create the RTC build script:
 
  1. Create the Build Script C:/workspace/BuildScripts/RTCBuild.xml (see attachment):
    RTCBuild.zipRTCBuild.zip

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- ==============================================================
        ANT Script to be launched by JBE                                                            
        ============================================================== -->
    <project name="project" default="default">

    <import
    file="C:/IBM/TeamConcertBuild401/buildsystem/buildtoolkit/BuildToolkitTaskDefs.xml"/>
     <property name="rad.install.dir"
              value="C:/Progra~1/IBM/SDP" />
    <property name="rad.build.file"
              value="C:/workspace/BuildScripts/RADBuild.xml" />
    <property name="userId" value="BuildUser"/>
    <property name="password" value="BuildUser"/>

    <target name="EnvironmentCheck">
     <startBuildActivity buildresultuuid="${buildResultUUID}"
                         userid="${userId}"
                         repositoryaddress="${repositoryAddress}"
                         password="${password}"
                         label="Check RAD Installation and Build File"
           activityidproperty="checkActivityId"/>
     <condition property="environment.check">
    <and>
    <available file="${rad.install.dir}/bin/runAnt.bat"/>
       <available file="${rad.build.file}"/>
      </and>
     </condition>
     <completeBuildActivity buildresultuuid="${buildResultUUID}"
                            userid="${userId}"
                            repositoryaddress="${repositoryAddress}"
                            password="${password}"
      activityid="${checkActivityId}"/>
    </target>
    <!-- =================================
             target: default              
            ================================= -->
    <target name="default"
            description="Invoke a Rational Application Developer build"
            depends="EnvironmentCheck"
            if="environment.check">


     <startBuildActivity buildresultuuid="${buildResultUUID}"
                         userid="${userId}"
                         repositoryaddress="${repositoryAddress}"
                         password="${password}"
                         activityidproperty="radBuildActivityId"
                         label="Run RAD Build File" />
     <exec executable="cmd.exe">
    <arg value="/c" />
    <arg value="${rad.install.dir}/bin/runAnt.bat
    -buildfile ${rad.build.file}
    -DrepositoryAddress=${repositoryAddress}
    -DbuildResultUUID=${buildResultUUID}
    -DuserId=${userId}
    -Dpassword=${password}
    -DparentActivityId=${radBuildActivityId}
    -Dteam.scm.fetchDestination=${team.scm.fetchDestination}"/>
      <env key="WORKSPACE"
           value="${team.scm.fetchDestination}" />
     </exec>
    <completeBuildActivity buildresultuuid="${buildResultUUID}"
                            userid="${userId}"
                            repositoryaddress="${repositoryAddress}"
                            password="${password}"
      activityid="${radBuildActivityId}"/>
    </target>
    </project>


     
  2. Adapt this line:

    <import
    file="C:/IBM/TeamConcertBuild401/buildsystem/buildtoolkit/BuildToolkitTaskDefs.xml"/>


    to match the location where you installed the Rational Team Concert Build Toolkit. This file contains the definitions of the RTC Ant tasks startBuildActivity, completeBuildActivity, etc.
     
  3. Replace the values of the following properties in the above script:

    rad.install.dir = Installation directory of Rational Application Developer and Rational Team Concert Client

    rad.build.file = Absolute path of the Ant Build file that Rational Application Developer needs to execute

    userId
    = UserID that started the Jazz Build Engine

    password = Password of the UserID that started the Jazz Build Engine


     
  4. Note that the following properties are supplied by the Jazz Build Engine when running an Ant Build Definition. You pass them to the second script (RADBuild.xml), together with the userId and password :



    repositoryAddress = URL of the Rational Team Concert Repository

    buildResultUUID
    = Unique Identifier of the Build Result, used to attach logs  to the Build Result

    team.scm.fetchDestination = Value of the Load Directory parameter


    parentActivityId = Unique Identifier of the parent Activity, used to nest Activities in the Build Results


     
  5. Note that the line:

    <env key="WORKSPACE"
           value="${team.scm.fetchDestination}"/>

    passes to the RADBuild.xml the environment variable WORKSPACE, which has the value specified above as Load Directory.
     

Create the RAD build script:
  1. Create the Build Script C:/workspace/BuildScripts/RADBuild.xml (See attachment).

    RADBuild.zipRADBuild.zip


    <?xml version="1.0" encoding="UTF-8"?>
    <!-- == ANT Script to be launched by JBE ===== -->
    <project name="project"
    default="default">
    <property name="runningLocation"
    location="C:/ant-contrib-1.0b3-bin/ant-contrib/ant-contrib-1.0b3.jar" />

    <taskdef resource="net/sf/antcontrib/antcontrib.properties">
    <classpath>
    <pathelement location="${runningLocation}" />
    </classpath>
    </taskdef>
    <target name="prepareWorkspace">
    <startBuildActivity
    activityIdProperty="createWSRuntimeAndImportActivityId"
    parentActivityId="${parentActivityId}"
    label="Create WS Runtime and import Projects into RAD Workspace"
    repositoryAddress="${repositoryAddress}"
    buildResultUUID="${buildResultUUID}"
    userId="${userId}"
    password="${password}"
    verbose="true" />

    <createWSRuntime name="WebSphere Application Server v8.5"
    targetid="WebSphere Application Server v8.5"
    path="C:/IBM/WebSphere/AppServer85"
    typeId="com.ibm.ws.ast.st.runtime.v85" />

    <!-- Import Projects -->
    <projectImport
    projectLocation="${team.scm.fetchDestination}/TestEJBProjClient"
    projectname="TestEJBProjClient" />
    <projectImport
    projectLocation="${team.scm.fetchDestination}/TestEJBProjEAR"
    projectname="TestEJBProjEAR" />
    <projectImport
    projectLocation="${team.scm.fetchDestination}/TestEJBProj"
    projectname="TestEJBProj" />

    <!-- Build/Compile projects -->
    <completeBuildActivity
    activityId="${createWSRuntimeAndImportActivityId}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    verbose="true"
    buildResultUUID="${buildResultUUID}" />
    </target>
    <!-- === target: default === -->
    <target name="default"depends="prepareWorkspace">
    <startBuildActivity
    activityIdProperty="buildActivityId"
    parentActivityId="${parentActivityId}"
    label="Build Workspace"
    repositoryAddress="${repositoryAddress}"
    buildResultUUID="${buildResultUUID}"
    userId="${userId}"
    password="${password}"
    verbose="true" />
    <!-- Build/Compile projects -->
    <workspaceBuild failonerror="FALSE" />

    <!-- End the build (with ERROR status if the workspaceBuild task reported errors) -->
    <echo message="The value of the property workspaceErrorCount is ${WorkspaceErrorCount} " />
    <echo message="${WorkspaceErrorMessages}" />
    <echo message="${WorkspaceErrorMessages}"
    file="log.txt"
    append="false" />

    <completeBuildActivity activityId="${buildActivityId}"
    repositoryAddress="${repositoryAddress}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    verbose="true"
    buildResultUUID="${buildResultUUID}" />
    <if>
    <equals
    arg1="${WorkspaceErrorCount}"
    arg2="0" />
    <then>
    <echo message="Completing the build with OK state" />
    <startBuildActivity
    activityIdProperty="exportAndPublishEARActivityId"
    parentActivityId="${parentActivityId}"
    label="Export EAR - See Downloads Tab of the Build Results"
    repositoryAddress="${repositoryAddress}"
    buildResultUUID="${buildResultUUID}"
    userId="${userId}"
    password="${password}"
    verbose="true" />

    <logPublisher
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    buildResultUUID="${buildResultUUID}"
    filepath="log.txt"
    status="OK"
    label="OK log" />

    <earExport
    earprojectname="TestEJBProjEAR"
    earexportfile="${team.scm.fetchDestination}/TestEJBProjEAR.ear" />

    <artifactFilePublisher
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    buildResultUUID="${buildResultUUID}"
    filepath="${team.scm.fetchDestination}/TestEJBProjEAR.ear"
    status="OK"
    label="TestEJBProjEAR.ear" />

    <completeBuildActivity
    activityId="${exportAndPublishEARActivityId}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    verbose="true"
    buildResultUUID="${buildResultUUID}" />

    </then>
    <else>

    <startBuildActivity
    activityIdProperty="logBuildFailureActivityId"
    parentActivityId="${parentActivityId}"
    label="Log Build Errors"
    repositoryAddress="${repositoryAddress}"
    buildResultUUID="${buildResultUUID}"
    userId="${userId}"
    password="${password}"
    verbose="true" />
    <echo
    message="Completing the build with ERROR state" />

    <logPublisher
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    buildResultUUID="${buildResultUUID}"
    filepath="log.txt"
    status="ERROR"
    label="ERROR log" />

    <completeBuildActivity
    activityId="${logBuildFailureActivityId}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    verbose="true"
    buildResultUUID="${buildResultUUID}" />
    </else>
    </if>
    </target>
    </project>


     
  2. Adapt the property  runningLocation , to indicate the location where you downloaded the jar file containing the <if>  task (Ant-Contrib). See Related information for further details.
     
  3. Specify as many projectImport tasks as projects in your RAD workspace. For each project, specify the projectName and projectLocation (See APAR PM81639 A NullPointerException occurs when using the projectImport Ant task.)

Successful build:
  1. Open the Activities tab of the Build Results. If the build is successful, you will see the following activities listed (they are created by using the ant tasks startBuildActivity, completeBuildActivity):
  2. Open the Downloads Tab of the Build Results. You will see that the EAR was attached:



    Note: There are many other solutions for storing the output of the build. You could store them in IBM Rational Asset Manager, or use some other methods: Build Artifacts Publishing using HTTP Servers, Automated Build Output Management Using the Plain Java Client Libraries.
     
  3. Open the Logs tab of the Build Results. The Full Build Log contains the complete output of the build file, and the OK log is an empty marker file that indicates that the build was successful.


Failed build:
  1. Open the Activities tab of the Build Results. If the build fails, you will see the following activities listed (they are created by using the ant tasks startBuildActivity, completeBuildActivity):

  2. Open the Logs tab of the Build Results. The Full Build Log contains the complete output of the build file, and the ERROR log will contain an extract of the build errors.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSUC3U","label":"IBM Engineering Workflow Management"},"ARM Category":[{"code":"","label":""}],"Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"3.0;3.0.1;3.0.1.1;3.0.1.2;3.0.1.3;3.0.1.4;3.0.1.5;4.0;4.0.0.1;4.0.0.2;4.0.1;4.0.2","Line of Business":{"code":"LOB59","label":"Sustainability Software"}},{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSRTLW","label":"Rational Application Developer for WebSphere Software"},"ARM Category":[{"code":"","label":""}],"Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"8.5.1;8.5;8.0.4.2;8.0.4.1;8.0.4;8.0.3;8.0.2;8.0.1;8.0","Line of Business":{"code":"LOB45","label":"Automation"}},{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SS4JCV","label":"Rational Software Architect for WebSphere Software"},"ARM Category":[{"code":"","label":""}],"Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"8.0;8.0.1;8.0.2;8.0.3;8.0.4;8.0.4.1;8.0.4.2;8.5;8.5.1","Line of Business":{"code":"LOB15","label":"Integration"}}]

Product Synonym

Rational Team Concert

Document Information

Modified date:
29 May 2020

UID

swg21622655