Configuring Ant build scripts for a build integration

You configure the Ant scripts that are supplied with IBM® Rational® Asset Manager to integrate with a build application such as IBM Rational Build Forge® or other build utility.

Before you begin

  • You must set the properties in the scripts to reference your Rational Asset Manager system information.
  • To run the Publish and DownloadArtifactLinks scripts, you must install the Ant-Contrib .jar file on the lib path. You can download the compressed file containing the .jar file and follow the installation information for more details.
Note: When you configure the Ant build scripts for a build integration, set the JAVA_HOME variable to the Java™ folder, and set the ANT_HOME variable to the Ant installation directory (which must be 1.7.0 or later). You do not need to set PATH or CLASSPATH.

Procedure

  1. Create a build project (such as a Rational Build Forge project). If the tools, libraries, and dependent components are all available as assets in Rational Asset Manager, you can use the supplied Ant scripts to run a build based on these assets. You can also use these scripts with other build utilities and solutions.
  2. Use the Ant scripts provided in Rational Asset Manager for the build project to use assets in the build and to publish the build results as new assets. Each script uses Rational Asset Manager Ant tasks. The ramclient.zip file contains a set of required .jar files and Ant tasks and scripts, and is available on the Extensions page of any deployed Rational Asset Manager server instance. You can also access it directly from here: http://<hostname>:<port>/ram/ramclient.zip (such as http://<localhost>:<9080>/ram/ramclient.zip).
  3. To use the ramclient.zip file, extract the file to a folder, and then set the Ant library parameter to include the ramclient-ant1.8.jar file from that folder. Do not move any of the extracted files after you extract the ramclient.zip archive. Ant automatically finds the other .jar files required by ramclient-ant1.8.jar as needed.
  4. To reference assets that will be used in the build, use this script: ramDownloadAsset.xml

    The ramDownloadAsset.xml file is a sample Ant script that downloads asset content (as artifacts). This script can be used in a build process where a set of approved libraries or executable files are needed in order to execute the build (for example: a special compiler, common components, or common scripts).

    In the DownloadAsset script, the following properties must be set:
    • lib.dir = Directory to copy asset into.
    • ram.url = URL for the Rational Asset Manager web services application (In the Rational Asset Manager web client, click the Help icon, click Extensions, scroll down to the web services section, and then locate the Repository location field).
    • ram.user.uid = The uid to use when using the Rational Asset Manager server.
    • ram.user.passwd = Password to use when using the Rational Asset Manager server.
    • ram.asset.guid = Asset's unique identifier (that is, the Rational Asset Manager unique id from the asset page).
    • ram.asset.version = Asset's version (that is, the Rational Asset Manager version from the asset page).
    • build.id = Build id will be use by Rational Asset Manager to track the build this download is for.
    For example, replace these values with your own asset to download: 
    <property name="lib.dir" value="C:\libdir" />
<property name="ram.url" value="http://machine127.ibmtst01.com:9080/ram.ws" />
<property name="ram.asset.guid" value="8141FA04-E837-FA50-7052-5269E7C6937C" /> 
<property name="ram.asset.version" value="1.0" />
    The following are optional properties that will be submitted to Rational Asset Manager to describe what is the download for:
    • build.type = What type of build is it (for example, "RTC Daily Build").
    • build.team.area = What team, or project this build is for (such as, Rational Asset Manager project).
    • build.team.server = Server used for the change or control source for this project or team.
  5. To reference related artifacts that are required for the referenced assets in the build, use this script: ramDownloadArtifactLinks.xml

    The ramDownloadArtifactLinks.xml file is a sample Ant script that resolves Eclipse project artifacts links to Rational Asset Manager by downloading the artifacts the links point to. This script can be used in a build process where source code is extracted from a SCM system, and where the extracted projects have links to artifacts in Rational Asset Manager. In Eclipse, the client plug-ins for Rational Asset Manager will process these links automatically.

    This script uses the ANT-CONTRIB (http://ant-contrib.sourceforge.net/) task utilities. Make sure to put the ant-contrib-XXX.jar file on the library path.

    In the DownloadArtifactLinks script, the following properties must be set:
    • build.dir = Eclipse workspace where rambuildercontrol.xml files are located. Directory path where all Eclipse projects were extracted into (typically from a SCM system).
    • ram.url = URL for the Rational Asset Manager web services application (In the Rational Asset Manager web client, click Help > Extensions, scroll down to the web services section and see the Repository location field).
    • ram.user.uid = The uid to use when using the Rational Asset Manager server.
    • ram.user.passwd = Password to use when using the Rational Asset Manager server.
    • ram.download.result.file = Optional file path. If set, there will also be a property "ram.downloadlist" that will hold a ";" separated list of the downloaded assets. (For example, GUID,version,artifact,artifact;GUID,version,artifact,artifact,artifact).
    For example, replace these values for your own related assets to download: 
    <property name="ram.url" value="http://machine127.ibmtst01.com:9080/ram.ws" />
<property name="build.dir" value="C:\Documents and Settings\Administrator\Desktop\RTC Workspace\" />
<property name="ram.download.result.file" value="C:\BuildDir\publishresults" />
  6. To publish the build results as new assets, use this script: ramPublishAsset.xml

    The ramPublishAsset.xml file is a sample Ant script that publishes an asset's content into Rational Asset Manager. This script can be used in a build process, where a set of generated artifacts need to be published into Rational Asset Manager as a single asset, reflecting dependencies on other assets that were used to generate this asset (for example open source/common components, supported platforms, and specifications) as well as a link to what is it that this built and published asset implements (such as a specification, release, or design).

    This script uses the ANT-CONTRIB (http://ant-contrib.sourceforge.net/) task utilities. Make sure to put the ant-contrib-XXX.jar file on the library path.

    In the PublishAsset script, the following properties must be set:
    • ram.url = URL for the Rational Asset Manager web services application (see the Rational Asset Manager Help/Extension page for the Repository location).
    • ram.user.uid = The uid to use when using the Rational Asset Manager server.
    • ram.user.passwd = Password to use when using the Rational Asset Manager server.
    • ram.asset.version = Asset's version (that is, the Rational Asset Manager version from the asset page).
    • ram.asset.name = The unique name of the asset.
    • ram.asset.community = Community to upload the asset to.
    • ram.asset.type = Type to use for this asset.
    • ram.asset.shortDescription = Short description.
    • ram.asset.description = Description regarding this asset.
    • ram.asset.artifacts = An archive file holding a directory structure of all artifacts to be published.
    • ram.release.guid = The unique id this asset is related to as part of a release. Asset to relate to with the "implementation for" relationship (for example, when publishing an asset, you can relate the asset to specifications, release requirements, and so on).
    • ram.release.version = The version of the "implementation for" asset.
    • build.id = Build id will be used by Rational Asset Manager to track the build this download is for; it can be any string.
    For example, replace these values to publish your assets: 
    <property name="ram.url" value="http://machine127.ibmtst01.com:9080/ram.ws" />
<property name="ram.asset.version" value="1.0" />
<property name="ram.asset.name" value="Publish Script test" />
<property name="ram.release.guid" value="7198899C-3E2A-A3CE-2E76-68BC2A637AD2" />
<property name="ram.release.version" value="7.2" />
<property name="build.id" value="1234" />
    The following are optional properties that will be submitted to Rational Asset Manager to describe what is the download for.
    • ram.download.result.file = Optional file path to a file created by the ramDownloadArtifactLinks.xml script. If set, the script will place a dependency relationship to all asses listed in this file.
    • verify.state.name = If specified, the script will verify that all files listed in ram.download.result.file are in this state (such as, "Approved").
    The following will be placed as information on the uploaded artifacts:
    • build.type = What type of build is it (such as, "RTC Daily Build").
    • build.team.area = What team, or project this build is for (such as, Rational Asset Manager project).
    • build.team.server = Server used for the change or control source for this project or team.
    • src.repository = Repository for the source/origin that this asset was developed with.
    • build.id = The build id that generated this asset.
    • build.def.id = The type of build used to create this asset with.
    • build.label = Build description.
    • build.url = URL to link to a build this asset was generated with.
    • src.repository = Repository URL used to develop this asset.

Example

Here is an example of running the download script:
ant -v -lib <ramclient folder>/ramclient-ant1.8.jar 
-file ramDownloadAsset.xml 
-Dlib.dir=<location where to download the artifacts> 
-Dram.url=<URL to repository location from Extension page> 
-Dram.user.id=<ram uid> 
-Dram.user.passwd=<ram passwd> 
-Dram.asset.guid=<guid> 
-Dram.asset.version=<version> 
-Dbuild.id=<An ID that denotes what this download is for>
For an example of how these scripts can be used, see http://www.ibm.com/support/docview.wss?uid=swg27016509 or http://www.ibm.com/developerworks/offers/lp/demos/summary/r-assetmanagerrbf.html
Feedback