The Process Sharing API

RTC process sharing allows to manage a process in one project area and to use the process in multiple other project areas. This post explains the internal API that allows to use  this feature in automation to make operations easier.

The RTC process sharing feature allows to minimize process customization while having a common process in many project areas. This is interesting for all kinds of users, especially with a growing number of project areas while in the need of a common process.

I worked with a team, that needed to create many project areas to contain the information for each project in one project area while limiting access to other project areas. So the idea was to automate the process of creating project areas, which required to be able to use an API. I found hints to this API provided by Sam on Jazz.net. I consolidated the code into an example that I could share with others.

You can find more about how this feature works in the following articles on Jazz.net

• Work Item Configuration and Shared Process in Rational Team Concert
  
• Managing Rational Team Concert work item changes with process sharing
  
• Cross Server Process Sharing
  

The code in this post is client API.

This blog post uses internal API which can be changed at any time. If the Internal API changes, the code published here will no longer work.

Warning, some of the code uses internal API that might change in the future. If the Internal API changes, the code published here will no longer work.

The post contains published 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. I found a section relevant to source code at the and of the license. Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee. Enjoy!

Just Starting With Extending RTC?

If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.

You should be able to use the following code in this environment and get your own automation or extension working.

The Code

To provide at least some wrapper around the internal code calls, I created a utility class ProcessProviderUtil. This utility wraps the API to set a project area to provide the process to be used by other project areas, as well as the API to set a project area to use another project area’s process and provides methods to use this API. The methods just delegate to the internal API call at this time.

You can download the code from here.

This is how the code looks like:

/*******************************************************************************
 * Licensed Materials - Property of IBM
 * (c) Copyright IBM Corporation 2014. All Rights Reserved. 
 * 
 *
 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 *******************************************************************************/
package com.ibm.team.js.process.client;

import com.ibm.team.process.common.IProjectArea;
import com.ibm.team.process.common.IProjectAreaHandle;
import com.ibm.team.process.internal.common.ProjectArea;

/**
 * Skeleton for a plain-Java client, see
 * https://jazz.net/wiki/bin/view/Main/ProgrammaticWorkItemCreation.
 */
public class ProcessProviderUtil {

	/**
	 * Set a project area to provide its process for sharing
	 * 
	 * @param projectArea
	 */
	public static void setIsProcessProvider(IProjectArea projectArea, boolean isProcessProvider) {
		((ProjectArea) projectArea).setIsProcessProvider(isProcessProvider);
	}

	/**
	 * Test if the projectArea Provides its process
	 * 
	 * @param projectArea
	 * 
	 *            Determines whether other project areas can get their process
	 *            from this project area.
	 * @return true if this project area allows other project areas * to use its process, false if not. */ public static boolean isProcessProvider(IProjectArea projectArea) { return ((ProjectArea) projectArea).isProcessProvider(); } /** * Share the process on another project area * * @param usingProjectArea * @param providingProcessArea */ public static void setProcessProvider(IProjectArea usingProjectArea, IProjectArea providingProcessArea) { ((ProjectArea) usingProjectArea) .setProcessProvider(providingProcessArea); } /** * Get the project area from which we use the process * * @param projectArea * * @return {@link IProjectAreaHandle} or null if this project * area does not rely on another project area for its process. */ public static IProjectAreaHandle getProcessProvider(IProjectArea projectArea) { return ((ProjectArea) projectArea).getProcessProvider(); } }

Example Usage

The methods are so simple that there is no reason to explain them in detail. The code below shows how they can be used. The example needs two project areas to be provided. One project area e.g. based on the Scrum process template. A second project area based on the ‘Unconfigured Process’. The User that runs this automation needs to be member of the JazzAdmins repository group.

The code to set the first project area to provide its process to be used by another projects looks like below.

IProcessItemService processItemService = (IProcessItemService) teamRepository.getClientLibrary(IProcessItemService.class);

System.out.println("\nProcessing project area: "+ providingProjectAreaName);
URI uri = URI.create(providingProjectAreaName.replaceAll(" ", "%20"));
IProjectArea providingProjectArea = (IProjectArea) processItemService.findProcessArea(uri, null, monitor);
if (providingProjectArea == null) {
	System.out.println("....Error: Project area not found: ");
	return false;
}
providingProjectArea = (IProjectArea) providingProjectArea.getWorkingCopy();

System.out.println("...Project area provides its process for usage:"
		+ new Boolean(ProcessProviderUtil
				.isProcessProvider(providingProjectArea)).toString());
// Set to provide the process for sharing
System.out.println("...Set project area process to provided for usage");
ProcessProviderUtil.setIsProcessProvider(providingProjectArea,true);
System.out.println("...Project area provides its process to other project areas:"
		+ new Boolean(ProcessProviderUtil
			.isProcessProvider(providingProjectArea))
			.toString());

// Save project area that uses the provided process
processItemService.save(providingProjectArea, monitor);

The code basically finds the project area somehow (by its name). It then gets a working copy to be able to modify it. It then provides if the project area is already providing its process to others. Regardless of this information it sets the project area to provide its process for usage. It again prints if the process is provided. Finally the changes are saved.

The code to use the process of a project area that provides it looks as below.

System.out.println("\nProcessing project area: " + usingProjectAreaName);
uri = URI.create(usingProjectAreaName.replaceAll(" ", "%20"));
IProjectArea usingProjectArea = (IProjectArea) processItemService.findProcessArea(uri, null, monitor);
if (usingProjectArea == null) {
	System.out.println("....Error: Project area not found: ");
	return false;
}
usingProjectArea = (IProjectArea) usingProjectArea.getWorkingCopy();

System.out.println("...Project area provides its process to other project areas:"
			+ new Boolean(ProcessProviderUtil
				.isProcessProvider(usingProjectArea))
				.toString());
Boolean used = new Boolean(false);
IProjectAreaHandle handle = ProcessProviderUtil
	.getProcessProvider(usingProjectArea);
if (null != handle) {
	used = new Boolean(true);
}
System.out.println("...Project area uses a process provided by another project area:" + used.toString());
// Set to share process
System.out.println("...set to use a process provided by another project area");
ProcessProviderUtil.setProcessProvider(usingProjectArea,providingProjectArea);
used = new Boolean(false);
handle = ProcessProviderUtil.getProcessProvider(usingProjectArea);
if (null != handle) {
	used = new Boolean(true);
}
System.out.println("...Project area uses a process provided by another project area:" + used.toString());
// Save project area that uses the provided process
processItemService.save(usingProjectArea, monitor);

As in the part above the code first finds the project area. It then detects if the project area provides its process for informational reasons. Then it checks if it uses the process of another project area. It then sets the project area to use the process of the first project area, prints a check of the fact and saves the process change.

Please note, there is no real error handling here. e.g. if the project area provides its process and can actually share another process is not tested.

In the inverse case, if providing the process is supposed to be disabled, the save would fail if project areas still share the provided process.

Summary

The code is experimental. I have tested it against a test server on Tomcat and Derby. It is by no means production ready and can be enhanced for various scenarios. However, as always, I hope the code is an inspiration and helps someone out there to save some time. If you are just starting to explore extending RTC, please have a look at the hints in the other posts in this blog on how to get started.