Manipulating Work Item Enumeration Values

I ran into the mysteries of Enumerations in the Java API several times and there is a question on the Jazz Forum right now how to get and set enumeration type values using the Java API. Lets look at it, it is really easy.

The post A RTC WorkItem Command Line Version 2 uses this technique to find, set and remove literals for enumeration and enumeration list attribute types.

License and how to get started with the RTC API’S

As always, 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, which basically means you can use it for internal usage, but not sell. Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee. Enjoy!

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.

To keep it simple this example is, as many others in this blog, based on the Jazz Team Wiki entry on Programmatic Work Item Creation and the Plain Java Client Library Snippets. The example in this blog shows RTC Client and Common API.

Download the Code

The example code can be downloaded from DropBox. Please note, there might be restrictions to access DropBox and the code in your company or download location.

The Code Explained

The code below is client code. Code in the server would be very similar, except that the Client Library would be replaced by a service.

When accessing the value of a work item attribute using Object value = workItem.getValue(iAttribute); objects of various types are returned. For Enumeration attribute types the returned value is an Identifier. You can use the code below to get the data.

if (value instanceof Identifier) {
	Identifier literalID = (Identifier) value;
	ILiteral literal = getLiteralbyID(literalID, iAttribute);
	String displayValue = literal.getName();
}

The code to get the literal by its ID looks as follows:

private ILiteral getLiteralbyID(Identifier findLliteralID, IAttributeHandle iAttribute) throws TeamRepositoryException {
	IWorkItemClient workItemClient = (IWorkItemClient) teamRepository().getClientLibrary(IWorkItemClient.class);
	IEnumeration enumeration = workItemClient.resolveEnumeration(iAttribute, null);

	List literals = enumeration.getEnumerationLiterals();
	for (Iterator iterator = literals.iterator(); iterator.hasNext();) {
		ILiteral iLiteral = (ILiteral) iterator.next();
		if (iLiteral.getIdentifier2().equals(findLliteralID)) {
			return iLiteral;
		}
	}
	return null;
}

If you have a string value and need to set the work item attribute value of an enumeration type attribute you can use the code below. It looks up the literals and compares their display value to the string it is looking for. Then it sets the value.

Note: You need to get a WorkItemWorkingCopy before you can set the value of a work item attribute, otherwise you will receive an exception saying that the item is immutable. The best way to get a WorkItemWorkingCopy is to use a WorkItemOperation as explained in this post.

workItem.setValue(priority, getLiteralEqualsString(fPriorityEnumerationString,workItemClient, priority));

Finding the literal happens in the code below:

private static Identifier getLiteralEqualsString(String name, IAttributeHandle ia) throws TeamRepositoryException {
	IWorkItemClient workItemClient = (IWorkItemClient) teamrepository.getClientLibrary(IWorkItemClient.class);

	Identifier literalID = null;
	IEnumeration enumeration = workItemClient.resolveEnumeration(ia, null); // or IWorkitemCommon
	List literals = enumeration.getEnumerationLiterals();
	for (Iterator iterator = literals.iterator(); iterator.hasNext();) {
		ILiteral iLiteral = (ILiteral) iterator.next();
		if (iLiteral.getName().equals(name)) {
			literalID = iLiteral.getIdentifier2();
			break;
		}
	}
	return literalID;
}

List Attributes such as Enumeration Lists

It is possible to define attributes for several types as list attributes that allow to select multiple values.

To set a value for such attribute types add the values the attribute is supposed to have set to a List and return that list.

You can create a typed list or an untyped list and simply add the literals as objects. See Working with Work Item Attributes in the section List Attributes and the section Set the WorkItem Attribute for an example.

A very simple example would be for a custom enumeration. Construct a list of attribute values (e.g. the Identifier for the enumeration literal) and use the list to set the values:

List values = new ArrayList();
values.add(getLiteralEqualsString("foo", customEnumerationList));
values.add(getLiteralEqualsString("bar", customEnumerationList));
workItem.setValue(customEnumerationList,values);

For more examples see the work item commandline especially the WorkItemUpdateHelper for methods ending with List for example:

com.ibm.js.team.workitem.commandline.helper.WorkItemUpdateHelper.calculateEnumerationLiteralList(ParameterValue, List)

Common API

Please note, the example above uses the IWorkItemClient interface, however, the enumeration relevant interface is just inherited from the interface com.ibm.team.workitem.common.IWorkItemCommon . This interface can be used in the client as well as the server API.

Summary

This post explains the basics of the RTC Enumeration API and how to access and use enumeration literals in automation.

I hope this code will help others struggling with the RTC Java API.