RTC Build Traceability with UrbanCode Deploy

There have been great developments in the past 12 months or so to improve the traceability between builds managed by RTC and UrbanCode Deploy.

  1. RTC build definitions now have built-in support for post-build deployment steps. If you use the Jazz Build Engine as your build engine, you can specify connection information and component information in the build definition itself to allow the build process to push a new version of the build result into a new component version. This is great and makes it simple and easy to accomplish getting your builds to the deployment engine. See Freddy’s blog entry from about a year ago on this very topic for more details. There are of course some limitations to this feature. It assumes you want to push your build result into a single UrbanCode Deploy component. This is fairly unrealistic in that most applications of even modest complexity will most likely have more than one component in their application. If you build each component individually, then you are all set. However, if you have a single build file for the entire application (or for more than one component), this feature won’t cut it. To solve this, you can always use the old tried and true method of adding ANT tasks to your build.xml to create a new component version and push the contents into that version.

    From a forward traceability perspective, RTC build results records also have links that you can add. A common practice is to create a link to the UrbanCode Deploy component that gets created.
  2. UrbanCode Deploy also has a feature that allows you to create links associated with component versions. These links can be URLs to anything you want, but the best use of this feature is to provide a link back to the build entries that produced the component version. In the case of RTC, a simple link to the build result record gives you that backward traceability. If you use another build engine like Jenkins, for example, you can also create another link that points back to the Jenkins job that produced the build.11-20-2014 12-03-08 PM
    And there are REST and command line API calls that allow you go GET and PUT links. This makes the creation of the link something you can do as part of the build step of pushing a new component version to UrbanCode Deploy.

So both RTC and UrbanCode Deploy have the ability to create and maintain links to and from build result records and component versions. But let’s examine a bit closer how these links can be used to enhance the visibility of code as it walks down the release pipeline.

But first a quick aside. RTC has the concept of baselines and UrbanCode Deploy has the concept of snapshots. At some point in time someone needs to lay out some strategies on how these two concepts can be used together. The concept of a baseline in RTC collects together all of the code versions of all the files in all the selected components (RTC component here) into a single entity. This make sense to do at build time. At the same time, UrbanCode Deploy has the concept of a snapshot that essentially does the same thing but at a build output level. There may be additional components in a snapshot that don’t have a corresponding build equivalent, but marrying the two concepts is something I hope the Rational development teams consider. Being able to build all components of an app, take an RTC snapshot of the code that corresponds to that build, push all the components into UrbanCode deploy as new component versions, and create a snapshot of the application with the new component versions seems like a logical thing to do. I am sure there are many scenarios where this simple case breaks down, but the concept is solid. Adding links to more element types in UrbanCode deploy will help make this a reality.

OK, now back to our story. We have the bi-directional traceability between RTC build results and component versions via links on either side. But as the components get deployed to new environments as they move down the release pipeline, there is no indication of that movement in the RTC build record. How can we make this happen? Let’s build a plug-in.

The concept of the plugin is that each time a component version gets deployed to a new environment, let’s put some type of indication in the build result record to indicate that it has been deployed to environment X. This way anyone observing the build result record will know how far into the release pipeline, if at all, the build output has made it. The easiest way to do this is to use the tag field of the build result record. Tags can be anything so let’s add some tags to indicate deployment to environments.

In order to do this programmatically, we need to take advantage of the RTC Java API. For any release of RTC, you can get a zip file of the Java API jars that can be used to write java programs that manipulate RTC elements. There were a few jazz.net articles here and here that I used to help come up with the code I wrote. I also made the plug-in step that adds the tag a two step java plug-in (the plug-in calls a java program that then collects properties and then spawns another java process to do the work). This was for a specific reason. The code that does the work needs the RTC Java API jar files in its classpath. For the latest release of RTC, there are about 100 jar files that make up the classpath list. I didn’t want to include that entire set in the plug-in. Therefore, I ask the user to provide a path to the directory that holds these jar files. I then spawn a second java process that includes this directory in its classpath. This also keeps the plug-in RTC version-independent as long as the Java API for builds doesn’t change that much and it puts the onus on the user to get those jars.

So I created a plug-in step that adds a tag to the list of tags of an RTC build result record. The information needed for this step is relatively small: the RTC URL, a username and password, and the UUID of the build result record, and the tag to add. The java for this took a bit of time but again using existing examples made things much easier.

The other step in the plug-in that I created was getting the RTC build result ID from the component version link. The URL to an RTC build result looks something like this:

hostname:9443/ccm/web/projects/JKE%20Banking%20(Change%20Management)
#action=com.ibm.team.build.viewDefinition&id=_PYarAGq4EeS_krMxQ9smpw

The id fragment at the end is the UUID of the build result record. So the plugin step needs to get the link from the component version, then parse that link to get the build record UUID, and then create an output property to hold that value so that the previously mentioned java step can use it. There is a REST API call that can be used to get the link from a component version. Groovy can then be used easily to parse the full URL and retrieve the id.

So here is a working example. I envision that at the end of a component deployment process you would add these two steps to update the build result record.
11-20-2014 2-10-24 PM

Here is the details for the first step, GetBuildId. It takes the parameters mentioned above. Using component name and version name properties makes this step dynamic. The link name comes from the process of creating the link through an ANT task when building the component. And the output property is simply whatever you want to call it.

11-20-2014 2-12-32 PM

Here are the properties for the second step. The RTC parameters are self explanatory. The build result record UUID is the property that is set by the previous step. And the Java API location is where the user has unzipped the RTC Java API files on the agent server. The tag value also uses the current environment name property so that this step works for any environment.

11-20-2014 2-15-43 PM

Both of these steps work in my environment without a hitch. If you are interested in trying it out, you can get the plug-in source code here in this IBM DevOps Services project. Let me know how it goes.

Advertisements

2 thoughts on “RTC Build Traceability with UrbanCode Deploy

  1. HI Darrell,

    I found this blog very interesting. I have a related question. Have you ever used the RTC Work Items plugins that ships with UCD ? I am wondering how you get the work item ID into the steps included in this plugin. Is it a manual thing ? Or is there a way to pass the work item id as part of the post-build deploy ? I thought I could use build properties to set a component version property, but the former are immutable.

    Thanks for you thoughs.

    V.

    • Vincent,
      Yes, the RTC plug-in expects a work item ID in the property. How you get it there is up to you. You can manually enter it but that isn’t practical. Or you could use the very same process that I am using here with a component version link. As part of the build process, you can add a link to your RTC work item via the command line method. Then use the exact same process I am using to retrieve the ID from the link create a step property out of the ID and then pass it to the RTC work item plug-in step the same way I am passing it to my custom step.

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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