Ant’s Role in Enhancing Enterprise Capabilities with EWM & EWM EE

Getting Started What is Ant?

Ant is a build tool that is implemented as a scripting language, which is based on the JavaTM platform. Using Java as its platform allows Ant to be run on any system that supports Java in a variety of ways. Ant can be run via the command line, from a shell script or batch job, or from other applications like EclipseTM, a Jazz Build Engine (JBE), or a Rational Build Forge Agent (BFA). Ant scripts can be written such that they can be run in multiple environments without alteration or they can be written and customized for a specific target environment. Engineering Workflow ManagementTM (EWM) builds use Ant as the basic build tool. The flexibility of Ant allows you to customize how the EWM build is processed and how it is integrated into your software development workflow.

The scripting language implementation allows Ant to be extended to provide services beyond a simple build. In the case of EWM, Ant has been extended to allow for process automation – updating work items, checking work item conditions, triggering process actions based on build results – source control automation – updating files, delivering changes, flowing changes downstream, promoting changes from test to production – deployment automation – packaging build artifacts, deploying packages to other systems – and more.

Ant scripts are written in XML in a pseudo-programming language format. Each Ant script starts with an XML project element. The project element contains a top-level section, which is always executed when the script begins, and 0-n target elements, which can be required or optional, that are executed in a user-defined order. In a well-designed script a target will accomplish a defined unit of work: fetch files for a build; compile source files into an executable; publish the build results.

The basic building blocks used to complete a unit of work in an Ant build script target element are tasks. Each Ant task performs a specific function and is referenced by a unique name: copy to copy a file; delete to delete a file; and so on. There is an extensive list of built-in Ant tasks, and an even more extensive collection of tasks that have been contributed to Ant including those provided by the EWM.

The Engineering Workflow Management Ant tasks offer a variety of services that can be included in a build:

To use the EWM Ant tasks a general understanding of the Ant build environment and Ant build scripts is needed. For a general overview and introduction to Ant refer to the Apache Ant Manual that is appropriate for the version of Ant that you are running. The “Introduction”, “Using Apache Ant”, and “Running Apache Ant” sections provide an excellent overview. Refer to the “Ant Tasks” and “Concepts and Types” sections for more in-depth reference material.

Ant build environment

Ant runs in a Java JVM. It can be started from the command line via the ant command or directly using Java with one of the following Java command argument sequences:

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
                              -or-

java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]

For more information on running Ant from either the command line or directly using Java, see Running Apache Ant. This documentation also provides a full list of arguments and options for the Ant application. Also note that the EWM extensions to Ant can be included in a stand-alone environment like this by including the “-lib /path_to_Build_Toolkit” option on the Java command.

Under Eclipse, Ant can be invoked by right-clicking on an Ant script file and choosing the “Run As -> Ant Build” option. Numerous extensions to Ant are available under Eclipse including those provided by the EWM.

A JBE or RBA build invokes Ant via Java. The EWM extensions to Ant are identified by a -lib argument on the Java command that points to the Build Toolkit folder where all the EWM extensions to Ant are housed.

Ant build scripts

In all environments, the primary argument for Ant is a path to the build script (-f), the script to run for the invocation, which defaults to the build.xml file in the current directory. The build script describes a list of steps to perform, called targets, and the order in which they should be performed. The format of an Ant build script is an XML document that is bounded by a project element containing top-level tasks and typically at least one target element.1 A target element consists of a set of Ant tasks that are executed sequentially to perform a unit of work.

For example, the following excerpt defines a target named “compile” which creates an output directory, compiles a set of Java source code, and creates a jar from the compiled output (the details for each of the following Ant tasks have been omitted for clarity):

<target name="compile">
    <mkdir> - create a directory
    <javac> - compile Java code
    <jar>   - create a jar file

</target>
1Note: A build script can consist of just the top-level area of the project element. This is a common format for imported definition files for macros, tasks, and types, but an uncommon format for a typical build script.

<project
    basedir="."

    default="all"
    name="FindWorkItemIdForWorkItemType"
    xmlns:ac="antlib:net.sf.antcontrib"
    xmlns:xt="antlib:com.ibm.team.build.extensions.toolkit">

<ac:switch value="${tmp.authenticationPolicy}">
    <ac:case value="CERTIFICATEFILE">

        <startBuildActivity
                repositoryAddress="@{repositoryAddress}"
                userId="@{userId}"
                certificateFile="@{certificateFile}"
                autoComplete="true"
                buildResultUUID="@{buildResultUUID}"
                label="@{label}"/>

    </ac:case>
    <ac:case value="INTEGRATEDWINDOWS">

        <startBuildActivity
                repositoryAddress="@{repositoryAddress}"
                integratedWindows="@{integratedWindows}"
                autoComplete="true"
                buildResultUUID="@{buildResultUUID}"
                label="@{label}"/>

    </ac:case>
    <ac:default>

        <startBuildActivity
                repositoryAddress="@{repositoryAddress}"
                userId="@{userId}"
                password="@{password}"
                autoComplete="true"
                buildResultUUID="@{buildResultUUID}"
                label="@{label}"/>

    </ac:default>
</ac:switch>

<xt:deleteBuildResults
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    password="${password}"
    buildId="${buildDefinition}">

    <xt:includeResult>
        <xt:buildProperty name="buildDefinitionId" value="${buildDefinition}"/>

    </xt:includeResult>
</xt:deleteBuildResults>

         classpath="${path_to_jar}/ant-contrib-1.0b3.jar"/>

     <taskdef resource="net/sf/antcontrib/antcontrib.properties">
         <classpath>

             <fileset dir="${commonPath}/external_libs" includes="**/*.jar"/>
         </classpath>

     <taskdef
         resource="com/ibm/team/build/extensions/toolkit/antTasks.properties"
         classpath="${path_to_jar}/com.ibm.team.build.extensions.toolkit_1.1.600.v20200807_1702.jar"/>

     <typedef
         resource="com/ibm/team/build/extensions/toolkit/antTypes.properties"
         classpath="${path_to_jar}/com.ibm.team.build.extensions.toolkit_1.1.600.v20200807_1702.jar"/>

     <taskdef resource="com/ibm/team/build/extensions/toolkit/antTasks.properties"
         <classpath>

             <fileset dir="${installPath}/jazz/buildsystem/buildtoolkit"
                 includes="**/com.ibm.team.build.extensions.toolkit*.jar"/>

         </classpath>
     </taskdef>

     <typedef resource="com/ibm/team/build/extensions/toolkit/antTypes.properties"
         <classpath>

             <fileset dir="${installPath}/jazz/buildsystem/buildtoolkit"
                 includes="**/com.ibm.team.build.extensions.toolkit*.jar"/>

         </classpath>
     </typedef>

<macrodef name="GetExportCreateBuild">
    <attribute name="property"/>
    <attribute name="testcase"/>
    <sequential>

<local name="lcl.buildType"/>

 <propertyregex
            property="lcl.buildType"
            input="@{testcase}"
            regexp="^ExportBuildDefinition(.*)"
            select="\1" override="true"/>

        <property name="@{property}"
            value="CreateBuildDefinition${lcl.buildType}.xml"/>

        <echo>createBuild: ${@{property}}</echo>
    </sequential>

<project>
    <import file="/path_to_file/BuildToolkitTaskDefs.xml"/>
    ...

<import>
    <javaresource name="scripts/imports/BuildExtensionsToolkitTaskDefs.xml"/>

<taskdef name="artifactFilePublisher" classname="com.ibm.team.build.ant.task.ArtifactFilePublisherTask"/>

/com/ibm/team/build/extensions/toolkit/ant/builddefinition/task/CreateBuildDefinitionTask.class

becomes

com.ibm.team.build.extensions.toolkit.ant.builddefinition.task.CreateBuildDefinitionTask

CheckApprovals build Log

</import>

    <!-- - - - - - - - - - - - - - - - - - - *
    *  CheckApprovals init                   *
    *- - - - - - - - - - - - - - - - - - - -->
    <target name="init" description="init"/>

    <!-- - - - - - - - - - - - - - - - - - - *
    *  CheckApprovals main                   *
    *- - - - - - - - - - - - - - - - - - - -->
    <target name="main" description="main">

        <xt:getchangesetworkitems
            repositoryAddress="${repositoryAddress}"
            userId="${userId}"
            password="${password}"
            workspaceUUID="${workspaceUUID}"
            property="workItems"

        />
        <echo>${workItems}</echo>

        <ac:for list="${workItems}" param="workItem" delimiter="," trim="true">
            <sequential>

                <local name="approved"/>

                <CheckForApprovals
                    repositoryAddress="${repositoryAddress}"
                    userId="${userId}"
                    password="${password}"
                    approval="Code review"
                    property="approved"
                    workItemId="@{workItem}"

                />
                <echo>${approved}</echo>

                <fail message="Build failed: Code review approvals are not complete">
                    <condition>

                        <not>
                            <istrue value="${approved}"/>

                        </not>
                    </condition>

                </fail>
            </sequential>

        </ac:for>
    </target>

    <!-- - - - - - - - - - - - - - - - - - - *
    *  CheckApprovals term                   *
    *- - - - - - - - - - - - - - - - - - - -->
    <target name="term" description="term"/>

    <target depends="init,main,term" description="all" name="all"/>
</project>

CheckForApprovals Ant Macro

The CheckForApprovals macro is supplied with EWM. You do not need to install, duplicate, or update this macro. It is made available by the import task described previously. It is presented here for information purposes only. If you wish to copy and modify this macro for your own purposes in your own locally maintained source, feel free to do so.

The CheckForApprovals macro retrieves approvals information for the specified work item in JSON format. It calls the CheckForApprovalsScript script which searches for the specified approval. The following discussion describes the meaning of critical aspects of the code using line number references:

password="@{password}"
                certificateFile="@{certificateFile}"
                integratedWindows="@{integratedWindows}"
                kerberos="@{kerberos}"
                passwordFile="@{passwordFile}"
                repositoriesFile="@{repositoriesFile}"
                smartCard="@{smartCard}"
                failOnError="@{failOnError}"
                reuseLoginOption="@{reuseLoginOption}"
                verbose="@{verbose}"

            >
            <taskAttribute name="workItemId" value="@{workItemId}"/>
            <taskElement>

                <xt:fetch name="approvals" property="lcl.approvals" ApprovalsJson="true"/>
            </taskElement>

</TeamTask>

        <CheckForApprovalsScript approval="@{approval}" input="${lcl.approvals}" property="@{property}"/>
    </sequential>

</macrodef>

}

    // Function to traverse JSON
    var json = eval("(" + input + ")");
    function traverse(obj,lastkey) {

        var type = typeof obj;
        if (type == "object") {

            for (var key in obj) {
                var type = typeof obj[key];

                if (lastkey === undefined || lastkey == "" || lastkey == key) {
                    newkey = key;

                } else {
                    newkey = lastkey + ’.’ + key;

                }
                if (type == "object") {

                    traverse(obj[key],newkey);
                } else {

                    // Complete value
                    debugMsg("key=" + newkey + " " + "value=" + obj[key]);

                    // Check approvals
                    if (newkey.indexOf(approval) != -1 && newkey.indexOf("cumstate") != -1 && obj[key] == "Approved") {

                        approved = "true";
                    }

} }

} }

    // Debug messages
    debugMsg("approval=" + approval);
    debugMsg("input=" + input);

    // Main Processing
    traverse(json);

    // Debug messages
    debugMsg("property=" + property);
    debugMsg("approved=" + approved);

    project.setProperty(property,approved);

    ]]>
</scriptdef>