RTC: Build On Deliver Participant

From some time ago I wanted to post a chunk of code to enable to launch a build as a result of a deliver operation. I have found myself in some situations in which this kind of automation has been asked, and I wanted to play a bit wit the SCM part of RTC SDK, so in this post I want to publish some code sample that I hope will be useful for people having this or a similar need.

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 Jazz.net 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.

You can download the code here.

Note that I have  just coded the sample for server side of the participant, without an aspect editor. If you just get started with extending RTC, I would suggest to first read the article Extending Rational Team Concert 3.x and follow the Rational Team Concert 4.0 Extensions Workshop

Identifying the operation

The first decision I faced was to decide the deliver phase in which I wanted to plug in the participant:

I will trigger the follow-up operation as result of the Phase 2 deliver in the server, so all the conditions have already passed. I went and had a check to the following wiki page covering the Custom Preconditions Table, to find out that the operation ID I have to use for my extension is “com.ibm.team.scm.service.changehistory.modification”. Therefore my extension is defined as follows:

The process configuration

For this participant I wanted to support a single configuration to several streams and builds, avoiding to make configure the Participant in the Project Area for each stream. Defining several streams will simplify the maintenance and I found that in some complex situations, customers wanted to launch more than one build as result of a deliver to  streams. So the process configuration structure I took as basis for my participant would be something like:

<target-stream target-stream-id="STREAM1">
   <build-definition build-definition-id="Build.Def.A"/>
   <build-definition build-definition-id="Build.Def.B"/>
</target-stream>
<target-stream target-stream-id="STREAM2">
   <build-definition build-definition-id="Build.Def.C"/>
</target-stream>

The attached code contains the schema for the participant process configuration. A bit of tweaking with the “<xsd:restriction” tag in the schema helps in throwing an error if the user types duplicate IDs for the streams or builds within a stream; just trying to prevent mistakes when you have to type your information in the process.

An example of the configuration could be:

Checking permissions in the chain

The operation we are trying to chain (requesting a build), has different process permissions definition that the deliver itself. So we can find situations in which the participant could fail making the whole deliver operation to fail. The following method from IServerProcess allows us to check if the user has permission to execute the operations we query for:

boolean[] getPermittedActions(IProcessArea processArea, 
String operationId, String[] actions) 
throws TeamRepositoryException;

In this case we want to query for the “com.ibm.team.build.server.requestBuild” operation and its “request” action. Again the wiki page covering the Custom Preconditions Table, allows to get the ID of the operation and its action.

In this participant sample, if the user has no permission to request the build, the follow-up will flag a warning and exit, but always allowing the deliver operation to finish:

for (boolean permission : processService.getServerProcess(operation.getProcessArea()).
 getPermittedActions(operation.getProcessArea(),BUILD_OPERATION_ID,BUILD_ACTIONS_ID))
 {
  if (!permission)
  {
    String description = "No permission to request a build. " +
    "No build will we launched as result of the delvier";
    IReportInfo info = collector.createInfo("Unable to request build", description);
    info.setSeverity(IProcessReport.WARNING);
    collector.addInfo(info);

  // Exit the follow-up
  return;
}}

Where the “processService” has been retrieved by “getService(IProcessServerService.class);”

Getting the information from the deliver

For the Phase 2 deliver, we will get operation data which is an instance “IScmDeltaSource”. This data provide information from the deltas involved in the deliver operation, like the workspaces source and origin of the deliver:

So once we have checked that we are in the right context, from this information we can get the target workspace of the delta changes, validate that is a stream, and compare its name from the participant configuration, to check if the follow-up has to trigger a build as a result of the executing deliver to the stream. A snippet of the code in that part in “BuildOnDeliverParticipant” class is:

for (IChangeHistoryModificationDelta delta : 
sourceData.getDeltas(IChangeHistoryModificationDelta.class))
{
   // Getting the target workspace information from the repository

   IWorkspace targetWK = (IWorkspace) repoService.fetchItem(delta.getTargetWorkspace(),
   IRepositoryItemService.COMPLETE);

   // Check that the workspace is a stream
   if (targetWK.isStream())
   {

     // get its configuration in the follow-up if any, and request the builds
     ...

Where the “repoService” has been retrieved by “getService(IRepositoryItemService.class);”

Requesting the build

The build request is basically the same code that the one you can find in the Rational Team Concert 4.0 Extensions Workshop but modified a little bit for error handling. As we can try to request several builds, we gather all the possible “warnings” (not to block the deliver operation), in a List<IReportInfo> and send all the issues to the collector at the end. Possible issues reported are:

1. Issues launching the build definition, typically caused by problems with the build engine
2. The specified build definition is not found

Summary

The code is experimental. I have tested it my local Tomcat/Derby installation with the MTM sample assets. Several improvements can be made like providing a presentation for the configuration, getting more information from the build definitions to improve control, better error handling … Therefore, I don’t think the code is production ready, but I hope that it can serve as help if you have to code this or similar functionality.