Automatically link rebuilt impacted files to a work item – Custom Ant Task

At this point you may be already be familiar with the Promotion and Packaging Enterprise Extensions features, and how you can use them in a work item basis. You can specify concrete work items to be promoted or packaged, therefore associated changes will be the ones to consider in these processes. This offers great fine grain control of how your changes are to progress in your defined development flow, which is to sum with all the goods that managing change sets with work items offer (traceability, process control, …).

In this post, however, I want to discuss the case of dependencies impact and their management: when files get rebuild because a source they depend on has been modified. I will provide a custom Ant task as sample approach for automatically linking those files rebuilt to a work item to incorporate them (and their outputs) in the development flow. In the last part of this post I want to also introduce some new features improvements coming in RTC.

In this post I am going to publish code, so our lawyers reminded me to state that the code in this post is derived from examples from as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license. Please also remember, as stated in the disclaimer, that this code comes with lack of promise or guarantee.

For the remainder of this post I am going to use the Mortgage Application sample.

Reviewing a sample Scenario

While the basic scenario of work item based promotion and packaging can be reviewed in the links provided at the beginning of this post, I will then focus on the dependencies case.

Let’s review a basic scenario: a copybook used in a COBOL source file. From the sample code, I have chosen JKEPDATA.cpy copybook from MortgageApplication-Common zComponent project. If I run an impact analysis we can check that JKECSRMT.cbl and JKEMPMT.cbl COBOL file uses the copy and depend on it:

impactI this sample scenario, I will modify the copybook and associate a work item to that change:

copychangeFinishing with a deliver and then running the team build associated to the development stream. The build report after this flow, with no other changes, will show something like this:

buildReportWe can see in the build report that the two COBOL files have been rebuilt as result of modifying the copy that both use.

OK, let’s get back to our original discussion … What would happen if, taking the work item #209 to which the copybook change is associated, I try to: (a) package the work item or, (b) promote the work item?

(a) We will find out that there’s nothing to package, and even trying to run the package creation may result in an error because of an empty package. This is right as the copybook change itself didn’t generate any output. While it may be acceptable in some cases, there are may be others in which you want to package any binaries that were regenerated as result of this change as result of the dependencies, as just shown.

(b) Similarly, promoting the work item will allow us to promote the source code change itself (i.e. the copybook change), but none of the rebuilt cobol files generated outputs will be considered as part of the promotion (a promotion of sources and binaries).

We can manually link these COBOL files to the 209 work item so the impacted source files and the regenerated outputs will be considered in the packaging and promotion operations. For example, from the impact analysis result view:

associateworkitemNext what I want to show is a custom built Ant Task that does this association to a work item automatically for you.

Sample custom Ant Task

The build report showed earlier is a visual rendering of buildReport.xml file, which uses as input the information from buildableFiles.xml, both available in the Downloads tab of the build result.

downloadsFor the task development I followed the steps outlined in the Robin Yehle Bobbitt’s blog post Adding a custom Ant task to your build toolkit.

The main constructs of the coded Ant task are as follows:

  1. The main class is called AssignOrphanBuildableFilesTask, it implements the task and extends AbstractTeamBuildTask.
    public class AssignOrphanBuildableFilesTask extends AbstractTeamBuildTask {
  2. “BuildImpactedFilesWorkItemID” will be the name of the build property to set with the ID of the work item to which the files would be linked. Therefore, a public setter method for the attribute is implemented
         * Ant attribute with the ID of the work item to link files with
        public static final String WORKITEM_NUMBER_ATT = "BuildImpactedFilesWorkItemID"; //$NON-NLS-1$
    public void setBuildImpactedFilesWorkItemID(int workItemId) {
            fBuildImpactedFilesWorkItemID = workItemId;
  3. The OrphanBuildableFilesCollector class is built to parse buildableFile.xml and return a map with the IFileItemHandle as key and the SCM Location path as value. AssignOrphanBuildableFilesTask uses the returned map to perform the linkage to the work item.
  4. AssignOrphanBuildableFilesTask creates a link using as description the file name and the build label for easy identification and trace. The following method is the responsible for such operation:
private void linkFilesToWorkItem(Map<URI, String> itemsToLink, IWorkItem trackingItem, IWorkItemClient workItemClient) 

        WorkItemWorkingCopy workingCopy = null;

            IWorkItemWorkingCopyManager wcm = workItemClient.getWorkItemWorkingCopyManager();
            try {
                wcm.connect(trackingItem, IWorkItem.FULL_PROFILE, null);
            } catch (TeamRepositoryException e) {
                throw new BuildException(e);
            workingCopy = wcm.getWorkingCopy(trackingItem);
            workingCopy = (WorkItemWorkingCopy) (trackingItem.getWorkingCopy());

        for (Map.Entry<URI, String> entry : itemsToLink.entrySet()) 
            IReference reference= IReferenceFactory.INSTANCE.createReferenceFromURI(entry.getKey(), entry.getValue());
            log("Creating link for" + entry.getValue(), Project.MSG_VERBOSE);
            workingCopy.getReferences().add(WorkItemEndPoints.RELATED_ARTIFACT, reference);

The parsing of buildableFiles.xml considers any reported rebuilt file with a rebuild Reason Code of 2 or 3:


The Ant Task in Action


You can add the “jar” file containing the custom task to the toolkit directly, or specify it with the “-lib” argument in the Ant Configuration section of the Dependency Build as in the screenshot:

antconfigThen you will have to incorporate the task as a step in your build process. You could add the new target as part of your build, as described in this Robin Yehle Bobbitt’s blog post Sample custom Ant task. However, in my case, I added it as part of a post-build script as it makes sense to have the parsing and linkage of the files to occur at the end of my build process:

postbuildThe contents of the post-build script are as follows:

<?xml version="1.0" ?>
<project name="link-impacted-files" default="all">
<taskdef name="assignorphanfiles" classname=""/>

    <target name="all">
        <assignorphanfiles  userId="${userId}" passwordFile="${passwordFile}" repositoryAddress="${repositoryAddress}" workspaceUUID="${teamz.scm.workspaceUUID}" buildResultUUID="${buildResultUUID}" BuildImpactedFilesWorkItemID="${BuildImpactedFilesWorkItemID}"/>


See it in action

Now with the custom task in place and the build definition prepared to take advantage of it, we can basically repeat the steps as in the scenario introduction.

This time, in the build request we specify the property for the Ant task, for example at request time:

requestBuildAnd at the end of a successful build, if the referred work item (ID 211) is opened, the files rebuilt are linked:

linksYou can then review these automatically linked elements, along with the build report, and decide which ones you want to keep. Let’s assume we are satisfied with all the links generated, what’s the result of this linkage for promotion and packaging operations now?

  • Promotion: a work item promotion of sources and outputs will include the outputs of the files that the Ant task linked because of the change impact. As the following screenshot of the promotion report shows:promotionNote that if you were to perform a promotion of only the sources the linked files wouldn’t be considered, as no source code modification has been performed
  • Packaging: performing a work item packaging operation will consider the outputs of the files linked as well


Conclusion and RTC Feature improvements

In this post I wanted to provide a sample custom Ant task to allow you to automatically link files that have been rebuilt as result of a change in other file. You can download the Ant task with the source code from here. And the sample post-build script from here.

In addition to offering this little automation example, I took advantage of the topic to further explain how this type of scenarios work today in the tool and provide some insight on the packaging and promotion processes.

You will also want to stay tuned to some new features in RTC that will address some of these scenarios. You can check the implementation of All Outputs rebuilt based on other built objects should be packaged starting as of RTC 4.0.5M2; see the information at the New&Noteworthy page. This feature will help you when you are using the packaging wizard so you can interactively instruct RTC to include these regenerated outputs, via a new option in the create package wizard:

IncludeImpactedObjectsOptionThis is a cool new feature, where I hope my sample task will still help you in your automation needs or if you need the traceability that the linkage to work items offer.


One thought on “Automatically link rebuilt impacted files to a work item – Custom Ant Task

  1. Hi Jorge,

    This is great! One thing to note though is in 4.0.5M2 we introduced new Ant tasks to help with the automation of your packaging and deployment needs. The package ant task has an attribute for setting whether to include impacted outputs or not.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s