A RTC WorkItem Command Line Version 2.2


Creating links is not easy. Many things can go wrong.  Testing by a user showed that there was an issue with links between work items and build results. I found that I got the link direction wrong. I fixed that. Here is the updated source code.

Related posts

License and Getting Started

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.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment.

Download

You can download the latest version here:

Setup and Usage

Follow the description in A RTC WorkItem Command Line Version 2 and in A RTC WorkItem Command Line Version 2.1. Check the README.txt which is included in the downloads.

Posted in Jazz | Leave a comment

A RTC WorkItem Command Line Version 2.1


In the last post Extending the WorkItem Command Line With New Commands we added a new command to the WorkItemCommandLine to implement a solution for attribute data migration as explained in Workaround: Migrate from Rational Team Concert 3.X string attribute used as multi-select lists to RTC 4.X enumeration lists.  Here is the updated source code.

What’s new?

This version of the RTC WorkItem Command Line has a new command that allows to migrate RTC 3.x multi-select enumeration data stored in string type attributes, containing Enumeration Literals separated by comma ‘,’ into the new EnumerationList attribute type.

Related posts

License and Getting Started

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.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment.

Download

You can download the latest version here:

Setup

Follow the setup description in A RTC WorkItem Command Line Version 2

The Syntax of the new Command

WCL uses the following syntax for the new command:

wcl -migrateattribute {/ignoreErrors} repository=RepoitoryURI user=user password=password projectArea=ProjectAreaName workItemType=typeID { id=WorkItemID } sourceAttributeID=AttributeID targetAttributeID=AttributeID

Where the sourceAttributeID must be the ID of a work item attribute of any string type. The content must be Enumeration Literal ID’s, separated by comma stored by a RTC 3.x muti-select EnumerationList presentation. In RTC 3.x the attribute type used to store the enumeration literal ID’s was a small or medium string. The command only checks for any string.

The targetAttributeID must be the ID of a work item attribute of type EnumerationList, where the enumeration and thus the literal ID’s must match the enumeration used in the source attribute.

If the attribute types don’t match the required types or the finds literal ID’s that don’t match a literal in the target enumeration, the work item is not changed. The user requires the permission to read and write the work items.

The image below shows the source attribute as shown in RTC 4.x with a regular string presentation and the new EnumerationList attribute. The values from the source attribute have been migrated over to the target attribute.

Source and target attribute

Source and target attribute

Below are examples how to launch the WorkItem command Line. The first example runs the migration for all work item of a specific type in a project area.

wcl -migrateattribute /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task sourceAttributeID=custom.medium.string targetAttributeID=custom.enumeration.list

The second example is used for testing and only works on the work item with the specified ID.

wcl -migrateattribute /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task  id=275 sourceAttributeID=custom.medium.string targetAttributeID=custom.enumeration.list
Posted in Jazz, RTC, RTC Automation | Tagged | 3 Comments

Extending the WorkItem Command Line With New Commands


If one needs a new command to be run in the WorkItem Command Line, what needs to be done? Lets explore this with the background from the post The WorkItem Command Line Explained.

As always, keep in mind, this is not production code, under development and not designed to win a beauty pageant. Testing has not been very thorough, so using this code is at your own risk.

The New Command

The new command is supposed to help with migrating Multi Select Enumeration  attributes available until RTC 3.x to Enumeration List attributes available in RTC 4.x and later.

As explained in Workaround: Migrate from Rational Team Concert 3.X string attribute used as multi-select lists to RTC 4.X enumeration lists, in RTC 3.x these multi select lists where implemented as a string attribute, that stored the enumeration literal ID’s separated by comma. A special presentation handled input and output. Downside of this approach was, that it was hard to query these attributes and create dashboards and reports. The new way is a special list type for each enumeration.

The workaround explains how to use CSV export and import to migrate the data. This solution uses the API to do so. What this solution does not attempt so far is having a mapping that changes the data.

Related posts

License and Getting Started

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.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment.

Download

Download the version 2.1 that includes the code from this post.

Requirements

The command is supposed to work on work items of a specific type in a project area.

  • For a source attribute (of type string), read the value, split it into enumeration literal ID’s
  • Find the enumeration literals and build a list from them
  • Store the list of enumeration literals in a target attribute
  • Perform this for one work item of the type (e.g. for testing)
  • Perform this for all work items of the type
  • Be able to tolerate errors and run nonetheless

The image below shows the source attribute as shown in RTC 4.x with a regular string presentation and the new EnumerationList attribute. The values from the source attribute have been migrated over to the target attribute.

Source and target attribute

Source and target attribute

Creating the new Command

The first step is to create a new command class. As explained in The WorkItem Command Line Explained there are some abstract classes available to be used. The AbstractWorkItemModificationCommand seems to be it, but looking closer, it is very specialized in creating or modifying a work item with a list of provided attributes and values in a parameter list. So the choice here is the AbstractTeamRepositoryCommand instead.

So the first step is to create the class MigrateWorkItemAttributeCommand in the package com.ibm.js.team.workitem.commandline. Create a public constructor as required from the abstract class and override the abstract methods. In the method getCommandName() return the name of the command. Also override the method setRequiredParameters() but make sure to add a call to super() to get the parameters it requires added. The initial step would look similar to this:

public class MigrateWorkItemAttributeCommand extends
		AbstractTeamRepositoryCommand {

	public MigrateWorkItemAttributeCommand(ParameterManager parametermanager) {
		super(parametermanager);
	}

	/***
	 * Add required parameters
	 * 
	 * (non-Javadoc)
	 * 
	 * @see com.ibm.js.team.workitem.commandline.framework.AbstractTeamRepositoryCommand#setRequiredParameters()
	 */
	@Override
	public void setRequiredParameters() {
		super.setRequiredParameters();
	}

	/***
	 * Return the command
	 * 
	 * (non-Javadoc)
	 * 
	 * @see com.ibm.js.team.workitem.commandline.framework.IWorkItemCommand#getCommandName()
	 */
	@Override
	public String getCommandName() {
		return "migrateattribute";
	}

	/***
	 * Perform the command
	 * 
	 * (non-Javadoc)
	 * 
	 * @see com.ibm.js.team.workitem.commandline.framework.AbstractCommand#process()
	 */
	@Override
	public OperationResult process() throws TeamRepositoryException {
		return getResult();
	}
}

In addition to the repository URL, the user name and the password, the command needs to know the project area, and the the work item type. It also needs the parameter for the source attribute ID and the target attribute ID. Some flags like ignoreErrors might come in handy as well.

Most of this can be harvested from existing commands like the CreateWorkItemCommand.  A few new need to be added. Introducing some constants is a good idea for later. The code added to setRequiredParameters() would finally look like below. The call to super() makes sure the basic parameters for the login process are required as well.

public static final String COMMAND_MIGRATE_ENUMERATION_LIST_ATTRIBUTE = "migrateattribute";
public static final String PARAMETER_SOURCE_ATTRIBUTE_ID = "sourceAttributeID";
public static final String PARAMETER_SOURCE_ATTRIBUTE_ID_EXAMPLE = "com.acme.custom.enum.multiselect";
public static final String PARAMETER_TARGET_ATTRIBUTE_ID = "targetAttributeID";
public static final String PARAMETER_TARGET_ATTRIBUTE_ID_EXAMPLE = "com.acme.custom.enum.list";


/***
 * Add required parameters
 * 
 * (non-Javadoc)
 * 
 * @see com.ibm.js.team.workitem.commandline.framework.AbstractTeamRepositoryCommand#setRequiredParameters()
 */
@Override
public void setRequiredParameters() {
	super.setRequiredParameters();
	// Copied from CreateWorkItemCommand
	getParameterManager()
			.syntaxAddRequiredParameter(
					IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY,
					IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY_EXAMPLE);
	getParameterManager()
			.syntaxAddRequiredParameter(
					IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY,
					IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY_EXAMPLE);
	getParameterManager().syntaxAddSwitch(
			IWorkItemCommandLineConstants.SWITCH_IGNOREERRORS);
	getParameterManager().syntaxAddRequiredParameter(
			PARAMETER_SOURCE_ATTRIBUTE_ID,
			PARAMETER_SOURCE_ATTRIBUTE_ID_EXAMPLE);
	getParameterManager().syntaxAddRequiredParameter(
			PARAMETER_TARGET_ATTRIBUTE_ID,
			PARAMETER_TARGET_ATTRIBUTE_ID_EXAMPLE);
}

The method getCommandName() would look like this now, with the string extracted into a constant:

	/***
	 * Return the command
	 * 
	 * (non-Javadoc)
	 * 
	 * @see com.ibm.js.team.workitem.commandline.framework.IWorkItemCommand#getCommandName()
	 */
	@Override
	public String getCommandName() {
		return COMMAND_MIGRATE_ENUMERATION_LIST_ATTRIBUTE;
	}

Add The New Command to the Main Class

The new command needs to be added to the WorkItem Command Line. In the class WorkitemCommandLine add it to the method method addSupportedCommands() like shown below.

/**
 * Add the supported commands. If introducing a new command, add it here.
 * 
 * @param parameterManager
 */
private void addSupportedCommands(ParameterManager parameterManager) {
	addSupportedCommand(new PrintTypeAttributesCommand(
			new ParameterManager(parameterManager.getArguments())));
	addSupportedCommand(new CreateWorkItemCommand(new ParameterManager(
			parameterManager.getArguments())));
	addSupportedCommand(new UpdateWorkItemCommand(new ParameterManager(
			parameterManager.getArguments())));
	addSupportedCommand(new MigrateWorkItemAttributeCommand(new ParameterManager(
			parameterManager.getArguments())));
}

Now it can be used like shown below. It is also possible to start debugging it using Launches.

wcl -migrateattribute /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task sourceAttributeID=custom.medium.string targetAttributeID=custom.enumeration.list

or this

wcl -migrateattribute /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task  id=275 sourceAttributeID=custom.medium.string targetAttributeID=custom.enumeration.list

Implementing the Command Logic

Now the method process() needs to be implemented. It orchestrates the work to be done. This obviously took some iterations. Here is the final result.

/***
 * Perform the command
 * 
 * (non-Javadoc)
 * 
 * @see com.ibm.js.team.workitem.commandline.framework.AbstractCommand#process()
 */
@Override
public OperationResult process() throws TeamRepositoryException {
	// From CreateWorkItemCommand
	// Get the parameters such as project area name and Attribute Type and
	// run the operation
	String projectAreaName = getParameterManager()
			.consumeParameter(
					IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY)
			.trim();
	// Find the project area
	IProjectArea projectArea = ProcessAreaUtil.findProjectArea(
			projectAreaName, getProcessClientService(), getMonitor());
	if (projectArea == null) {
		throw new WorkItemCommandLineException("Project Area not found: "
				+ projectAreaName);
	}

	String workItemTypeID = getParameterManager().consumeParameter(
			IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY)
			.trim();
	// Find the work item type
	IWorkItemType workItemType = WorkItemHelper.findWorkItemType(
			workItemTypeID, projectArea.getProjectArea(),
			getWorkItemCommon(), getMonitor());

	// Get the parameter values - The source attribute
	String sourceAttributeID = getParameterManager().consumeParameter(
			PARAMETER_SOURCE_ATTRIBUTE_ID).trim();
	// check if old attribute ID is string type
	IAttribute sourceIAttribute = getWorkItemCommon().findAttribute(
			projectArea, sourceAttributeID, getMonitor());
	if (sourceIAttribute == null) {
		throw new WorkItemCommandLineException(
				"Source Attribute not found: " + sourceAttributeID);
	}
	if (!AttributeTypes.STRING_TYPES.contains(sourceIAttribute
			.getAttributeType())) {
		throw new WorkItemCommandLineException(
				"Source Attribute is not a String type: "
						+ sourceAttributeID);
	}

	// Get the parameter values - The target attribute
	String targetAttributeID = getParameterManager().consumeParameter(
			PARAMETER_TARGET_ATTRIBUTE_ID).trim();
	// check if new attribute ID is EnumerationList
	IAttribute targetIAttribute = getWorkItemCommon().findAttribute(
			projectArea, targetAttributeID, getMonitor());
	if (targetIAttribute == null) {
		throw new WorkItemCommandLineException(
				"Target Attribute not found: " + targetAttributeID);
	}
	if (!AttributeTypes.isEnumerationListAttributeType(targetIAttribute
			.getAttributeType())) {
		throw new WorkItemCommandLineException(
				"Target Attribute is not an EnumerationList: "
						+ targetAttributeID);
	}
	if (getParameterManager().hasSwitch(
			IWorkItemCommandLineConstants.SWITCH_IGNOREERRORS)) {
		setIgnoreErrors();
	}
	String wiID = getParameterManager().consumeParameter(
			IWorkItemCommandLineConstants.PARAMETER_WORKITEM_ID_PROPERTY);
	if (wiID != null) {
		IWorkItem wi = WorkItemHelper.findWorkItemByID(wiID,
				IWorkItem.SMALL_PROFILE, getWorkItemCommon(), getMonitor());
		if (!wi.getWorkItemType().equals(workItemType.getIdentifier())) {
			throw new WorkItemCommandLineException(
					"Work item type mismatch: "
							+ workItemType.getIdentifier() + " specified "
							+ workItemType.getIdentifier());
		}
		migrateSingleWorkItem(wi, sourceIAttribute, targetIAttribute);
	} else {
		// Update all work items of this type.
		migrateAllWorkItems(projectArea, workItemType, sourceIAttribute,
				targetIAttribute);
	}
	// If we got here, we succeeded
	getResult().setSuccess();
	return getResult();
}

What it basically does is to get the parameters needed for this command and work with them. Keep in mind that the abstract class AbstractTeamRepositoryCommand does the login process already. So what needs to be done is to get the project area, the work item type, the source and the target attribute ID and the flags. Most of the code has been harvested in existing commands as well as in the WorkItemHelper class. The methods migrateSingleWorkItem() and migrateAllWorkItems() will be explained in a bit.

Some new fields and getters/setters where introduced in the process. We also need the separator for the literals in the original string later. The code looks as below:

public static final String SEPARATOR_ENUMERATION_LITERAL_ID_LIST = ",";

private boolean fIgnoreErrors = false;

private void setIgnoreErrors() {
	fIgnoreErrors = true;
}

private boolean isIgnoreErrors() {
	return fIgnoreErrors;
}

public MigrateWorkItemAttributeCommand(ParameterManager parametermanager) {
	super(parametermanager);
}

There was also a need to be able to access the ITeamRepository in the MigrateWorkItemAttributeCommand. I introduced a getter into the AbstractTeamRepositoryCommand class for convenience.

Note, it is always possible to get the ITeamRepository from an RTC object using the getOrigin() method and cast it to the ITeamRepository. However, it makes sense to add this to the framework, too.

Implementing the Work Item Modification

The final implementation steps are to implement the missing methods as well as add a inner class extending WorkItemOperation, to do the change to the work item. The code is shown below.

/**
 * Migrate one specific work item - for testing
 * 
 * @param wi
 * @param sourceIAttribute
 * @param targetIAttribute
 * @throws TeamRepositoryException
 */
private void migrateSingleWorkItem(IWorkItem wi,
		IAttribute sourceIAttribute, IAttribute targetIAttribute)
		throws TeamRepositoryException {
	MigrateWorkItem operation = new MigrateWorkItem("Migrate",
			IWorkItem.FULL_PROFILE, sourceIAttribute, targetIAttribute);
	performMigration((IWorkItemHandle) wi.getItemHandle(), operation);
}

/**
 * Migrate all work items of a specific type in a project area
 * 
 * @param projectArea
 * @param workItemType
 * @param sourceIAttribute
 * @param targetIAttribute
 * @throws TeamRepositoryException
 */
private void migrateAllWorkItems(IProjectArea projectArea,
		IWorkItemType workItemType, IAttribute sourceIAttribute,
		IAttribute targetIAttribute) throws TeamRepositoryException {
	// Find all work items of this type.
	// Create an Expression to find them
	IQueryableAttribute attribute = QueryableAttributes.getFactory(
			IWorkItem.ITEM_TYPE).findAttribute(projectArea,
			IWorkItem.PROJECT_AREA_PROPERTY, getAuditableCommon(),
			getMonitor());
	IQueryableAttribute type = QueryableAttributes.getFactory(
			IWorkItem.ITEM_TYPE).findAttribute(projectArea,
			IWorkItem.TYPE_PROPERTY, getAuditableCommon(), getMonitor());
	Expression inProjectArea = new AttributeExpression(attribute,
			AttributeOperation.EQUALS, projectArea);
	Expression isType = new AttributeExpression(type,
			AttributeOperation.EQUALS, workItemType.getIdentifier());
	Term typeinProjectArea = new Term(Term.Operator.AND);
	typeinProjectArea.add(inProjectArea);
	typeinProjectArea.add(isType);

	// Run the Expression
	IQueryClient queryClient = getWorkItemClient().getQueryClient();
	IQueryResult results = queryClient.getExpressionResults(
			projectArea, typeinProjectArea);
	// Override the result set limit so that we get more than 1000 items if
	// there are more
	results.setLimit(Integer.MAX_VALUE);
	MigrateWorkItem operation = new MigrateWorkItem("Migrate",
			IWorkItem.FULL_PROFILE, sourceIAttribute, targetIAttribute);
	// Run the operation for each result
	while (results.hasNext(getMonitor())) {
		IResult result = (IResult) results.next(getMonitor());
		performMigration((IWorkItemHandle) result.getItem(), operation);
	}
}

/**
 * Perform the update and
 * 
 * @param handle
 * @param operation
 * @throws WorkItemCommandLineException
 */
private void performMigration(IWorkItemHandle handle,
		MigrateWorkItem operation) throws WorkItemCommandLineException {
	String workItemID = "undefined";
	try {
		IWorkItem workItem = getAuditableCommon().resolveAuditable(
				(IWorkItemHandle) handle, IWorkItem.SMALL_PROFILE,
				getMonitor());
		workItemID = getWorkItemIDString(workItem);
		operation.run(handle, getMonitor());
		getResult().appendResultString(
				"Migrated work item " + workItemID + ".");
	} catch (TeamRepositoryException e) {
		throw new WorkItemCommandLineException(
				getResult().getResultString()
						+ "TeamRepositoryException: Work item "
						+ workItemID + " attribute not migrated. "
						+ e.getMessage(), e);
	} catch (WorkItemCommandLineException e) {
		String message = "WorkItemCommandLineException Work item " + workItemID
				+ " attribute not migrated. " + e.getMessage();
		if (!isIgnoreErrors()) {
			throw new WorkItemCommandLineException(getResult().getResultString() + message, e);
		} else {
			getResult().appendResultString(message);
		}
	}
}

The method migrateSingleWorkItem() basically runs the migration operation for a single work item. It creates the inner class MigrateWorkItem with the data it needs and then calls the method performMigration() to perform the migration. The method performMigration() calls the provided method and does all the error handling.

The method migrateAllWorkItems() basically creates an expression to get all work items of the specified type from the project area. The expression is run and performMigration() is performed on one result after the other.

Please note that the line

results.setLimit(Integer.MAX_VALUE);

makes sure that the built in query limit of the Eclipse client is overwritten to allow getting all possible results. To work it has to be exactly at the place it is.

The method performMigration() just performs the call and wraps everything up to be able to process exceptions. The information is provided in the result.

The methods above use some additional methods to get the client library IWorkItemClient to be able to perform the query expression.

/**
 * We need this client libraries to run queries
 * 
 * @return
 */
private IWorkItemClient getWorkItemClient() {
	return (IWorkItemClient) getTeamRepository().getClientLibrary(
			IWorkItemClient.class);
}

/**
 * Get the work item ID as string
 * 
 * @param workItem
 * @return
 */
private String getWorkItemIDString(IWorkItem workItem) {
	return new Integer(workItem.getId()).toString();
}

The WorkItemOperation Implementation

Finally lets look at the inner class MigrateWorkItem which extends WorkItemOperation. I use this approach in all the work item manipulation client API usage, because it conveniently handles all possible mishaps.

private class MigrateWorkItem extends WorkItemOperation {
	
	IAttribute fsourceAttribute = null;
	IAttribute fTargetAttribute = null;
	
	/**
	 * Constructor
	 * 
	 * @param The
	 *            title message for the operation
	 * @param message
	 * @param profile
	 * @param sourceAttribute
	 * @param targetAttribute
	 */
	public MigrateWorkItem(String message, ItemProfile<?> profile,
			IAttribute sourceAttribute, IAttribute targetAttribute) {
		super(message, profile);
		fsourceAttribute = sourceAttribute;
		fTargetAttribute = targetAttribute;
	}
	
	/***
	 * This gets called if run() is called
	 * 
	 * @see com.ibm.team.workitem.client.WorkItemOperation#execute(com.ibm.team
	 *      .workitem.client.WorkItemWorkingCopy,
	 *      org.eclipse.core.runtime.IProgressMonitor)
	 */
	@Override
	protected void execute(WorkItemWorkingCopy workingCopy,
			IProgressMonitor monitor) throws TeamRepositoryException,
			RuntimeException {
	
		IWorkItem workItem = workingCopy.getWorkItem();
		String thisItemID = getWorkItemIDString(workItem);
		if (!workItem.hasAttribute(fsourceAttribute)) {
			throw new WorkItemCommandLineException(
					"Work Item "
							+ thisItemID
							+ " Source Attribute not available - Synchronize Attributes: "
							+ fsourceAttribute.getIdentifier());
		}
		if (!workItem.hasAttribute(fTargetAttribute)) {
			throw new WorkItemCommandLineException(
					"Work Item "
							+ thisItemID
							+ " Target Attribute not available - Synchronize Attributes: "
							+ fTargetAttribute.getIdentifier());
		}
		// get the old value - a string with literals separated by a comma
		Object ovalue = workItem.getValue(fsourceAttribute);
		// compute the result values
		String sourceValues = "";
		if (null != ovalue && ovalue instanceof String) {
			sourceValues = (String) ovalue;
		}
		if (!sourceValues.equals("")) {
			String[] values = sourceValues
					.split(SEPARATOR_ENUMERATION_LITERAL_ID_LIST);
			IEnumeration<? extends ILiteral> enumeration = getWorkItemCommon()
					.resolveEnumeration(fTargetAttribute, monitor);

			List<Object> results = new ArrayList<Object>();
			for (String literalID : values) {
				if (literalID == "") {
					// Nothing to do
					continue;
				}
				Identifier<? extends ILiteral> literal = getLiteralEqualsIDString(
						enumeration, literalID);
				if (null == literal) {
					throw new WorkItemCommandLineException("Work Item "
							+ thisItemID
							+ " Target literal ID not available: "
							+ literalID + " Attribute "
							+ fTargetAttribute.getIdentifier());
				}
				results.add(literal);
			}
			// Set the value
			workItem.setValue(fTargetAttribute, results);
		}
		getResult().appendResultString("Migrated work item " + thisItemID);
	}

	/**
	 * Gets an enumeration literal for an attribute that has the specific
	 * literal ID.
	 * 
	 * @param enumeration
	 *            - the enumeration to look for
	 * @param literalIDString
	 *            - the literal ID name to look for
	 * @return the literal or null
	 * @throws TeamRepositoryException
	 */
	private Identifier<? extends ILiteral> getLiteralEqualsIDString(
			final IEnumeration<? extends ILiteral> enumeration,
			String literalIDString) throws TeamRepositoryException {
		List<? extends ILiteral> literals = enumeration
				.getEnumerationLiterals();
		for (Iterator<? extends ILiteral> iterator = literals.iterator(); iterator
				.hasNext();) {
			ILiteral iLiteral = (ILiteral) iterator.next();
			if (iLiteral.getIdentifier2().getStringIdentifier()
					.equals(literalIDString.trim())) {
				return iLiteral.getIdentifier2();
			}
		}
		return null;
	}
}

The interesting method here is execute(). It basically checks if the work item has the source attribute and the target attribute. If one of the attributes is missing, it can not run. You have to synchronize attributes first.

As last step the method gets the string value and splits the string into its values. The list of enumeration literal ID’s is then used to look up the enumeration literals. In case a literal can not be found, this is an error. If the literals are retrieved, they are put into a list and finally set as the value for the new attribute.

The method getLiteralEqualsIDString() is actually mostly harvested from the WorkItemHelper class, where it is used with the literal display name.

Additional Changes to the Framework

Since this command works very different than the others, it became apparent that it would be nice to see progress directly, if we are not working in RMI server mode. this also helps the other commands and potential future commands. To provide a better user experience

  • In WorkitemCommandLine the method isServer() has been made public so that it can be read from the framework classes
  • In OperationResult the method appendResultString() was changed to output the information rather than storing it in a result string, if the WorkItemCommandLine does not run in server mode

This change makes the result output much more immediate, especially for long running commands in normal mode. In RMI mode, the data is provided as is, after the call finishes.

Some Observations

The Parameter handling does not handle optional parameters well. It should be possible to add an optional parameter like the work item ID in this case. However, this is just a minor problem here. In addition at some point it can get so complicated that the automation for printing the command syntax won’t be easily manageable any more.

Summary

This post explains how to extend the WorkItem Command Line with your own commands. As always, I hope that helps someone out there.

Posted in Jazz, RTC, RTC Automation | Tagged , , , | Leave a comment

The WorkItem Command Line Explained


This post explains how the WorkItem Command Line works. It explains its structure and the main classes. This should allow users to extend the capabilities the code and add new commands or extend the current commands.

Please note, as this is work in progress, things might change slightly in future versions, however the general structure should persist.

Related posts

License and Getting Started

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.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment.

Importing The Project

Download the code from the post A RTC WorkItem Command Line Version 2. The file with the source code is named WorkItemCommandLine_Project-Vx-YYYYMMDD.zip. The x represents the version number and is followed by the date it was created. The file is an exported Eclipse project.

The project expects the Eclipse workspace to be set up as described in the posts Setting up Rational Team Concert for API Development. It requires the SDK to be set up as well as the Plain Java Client Libraries. The SDK is needed, because the project is a Plugin Project. this is done to be able to use the Eclipse Plugin Development Environment (PDE) to look at the API source code. The Plain Java Client Libraries are needed to run the code a Java application.

Use the Eclipse import File>Import. In the wizard window select “Existing Projects into Workspace” in the section General. Click Next and chose the option “Select archive file”, browse to the file you downloaded and select it. Make sure you see the project com.ibm.js.team.workitem.commandline selected and press Finish to start the import.

After the import you should see the project in your workspace. You should see no errors in the project. If you see errors, the most likely reasons for that are:

  1. The SDK is not set up correctly and the classes can not be resolved
  2. The SDK version is prior to RTC 4.0.1
  3. The Plain Java Client Libraries are not installed or the User Library has a different name

The first two will show in the plugin.xml and the manifest file. Setup the SDK correctly, or change the minimal versions needed in the dependencies.

The third will show as an error in the the build path. Define a user library named PlainJavaApi as explained in  Setting up Rational Team Concert for API Development or remove the existing user library entry and add you own. Make sure the dependency order of SDK and user library are correct as explained in  Understanding and Using the RTC Java Client API.

In case you have other errors you should search the internet for a solution.

Explore the Project

You can now explore the project. The folder structure is shown below.

WCL Project Overview

There are the following files and folders

  • src – contains the source code files.
  • build – contains a jardesc file to build a jar file for packaging
  • Launches – contains launch files used for testing
  • License – contains the license files
  • scripts – contains the script files used to start WCL, as well as a file with help information
  • the root contains a readme file, explaining how to build a releasable version of WCL, scripts used to start WCL in the development setup and a test file for upload attachment tests.

The Source Files

The image below shows the structure of the source code.

Source StructureThe package com.ibm.js.team.workitem.commandline contains the class WirkitemCommandLine, which has the main method to call WCL. The class OperationResult is used to pass result information. This is necessary, since the code could run in RMI mode and the output needs to be transferred to the RMI client. This class needs to support serializing in order to pass the result back. IWorkItemCommandLineConstants contains various constants used by WCL.

The package com.ibm.js.team.workitem.commandline.commands contains the classes that implement the currently available commands. CreateWorkItemCommand creates a work item of a specific type in a specific project area and sets the attributes as provided. PrintTypeAttributesCommand prints the attributes of a specific work item type in a specific project area. UpdateWorkItemCommand finds a work item and updates its attribute values.

The package com.ibm.js.team.workitem.commandline.framework contains a basic framework that is used by commands that are implemented in WCL. The main class requires the interface IWorkItemCommand to run the command. I ended up using this kind of framework, because all commands required some kind of parameters. The command should be able to define the parameters needed. The commands also require to do error handling. To interact with the RTC repository commands also need to login. The framework handles all the common activities and allows to create new commands without having to redevelop all this.

The class AbstractCommand implements the interface IWorkItemCommand and leaves some methods abstract that extending classes need to implement.

The class AbstractTeamRepositoryCommand adds a login to the team repository and the class AbstractWorkItemModificationCommand adds a WorkItemOperation to perform the changes to the work item. WorkItemCommandLineException is the exception class that is used to wrap other exceptions and thrown in case of unrecoverable errors.

The package com.ibm.js.team.workitem.commandline.helper contains helper classes. The class DevelopmentLineHelper is from another blog post Handling Iterations – Automation for the “Planned For” Attribute. It allows to find development lines and iterations on a development line. WorkItemHelper implements modifying work item attribute modification. Most of the RTC API related code is in there. WorkItemTypeHelper helps with printing the attribute information for a work item type.

The package com.ibm.js.team.workitem.commandline.parameter contains classes that implement all the parameter handling needed. The class Parameter is used to describe a parameter, if it is required, if it was already consumed, if it is a switch and the like. ParameterIDMapper defines a list of aliases that can be used instead of an attribute ID. You can add your own aliases that can be used for convenience. ParameterList represents a list of parameters. The class ParameterManager manages a parameter list and provides the central access to the parameters. The class ParameterParser is used to parse the parameters passed from outside and store them in a parameter list.

The package com.ibm.js.team.workitem.commandline.remote contains the remote interface IRemoteWorkItemOperationCall that is used in RMI mode.

The package com.ibm.js.team.workitem.commandline.utils contains some utility classes (providing static methods as interfaces). The class ProcessAreaUtil allows to search process areas. The class SimpleDateFormatUtil helps with conversion of timstamps from and to a string representation.

 How The Code Works

The main method of the WorkitemCommandLine basically instantiates the class and then calls the method run(). We will look at that method later.

/**
 * The main entry point into the work item commandline
 * 
 * @param args
 *            - the arguments to be used by the commandline
 * @throws RemoteException
 */
public static void main(String[] args) {

	OperationResult result = new OperationResult();
	System.out.println("WorkItemCommandLine Version "
			+ IWorkItemCommandLineConstants.VERSIONINFO + "\n");
	WorkitemCommandLine commandline;
	try {
		commandline = new WorkitemCommandLine();
		result = commandline.run(args);
	} catch (RemoteException e) {
		result.appendResultString("RemoteException: " + e.getMessage());
		result.appendResultString(e.getStackTrace().toString());
	}
	System.out.println(result.getResultString());
	if (TeamPlatform.isStarted()) {
		TeamPlatform.shutdown();
	}
	if (!isServer()) {
		// If I am not in server mode, I need to exit and return success or
		// failure
		if (result.isSuccess()) {
			// If the operation was unsuccessful, terminate with an error
			System.exit(0);
		}
		System.exit(1);
	}
}

The operation run() will return a result if it terminates. The information in this result is used to create the exit code to terminate the call.

In case this WCL is started as RMI server, the process can not terminate with System.exit(). It needs to persist registered to the RMI registry. The static method isServer() is used to communicate this information.

The method run() parses the parameters passed. It then checks if it is supposed to run as RMI server or as RMI client. If that is the case it starts the RMI server mode or, uses RMI to call the server as client. If this is a normal run, it calls runCommands() with the parameters that have been parsed.

If started as RMI server, the method startRMIServer() is used to initialize RMI and to register the class to the registry. The method runOperation() is basically the interface that is used to run the command on the server and is called by RMI clients. The method runOperation() parses the parameters and calls runCommands() as well.

The method runCommands() really executes the command requested in the parameters.  The first steps it does is to initialize the data it needs. Then it runs addSupportedCommands() to add the commands that are available.

/**
 * Add the supported commands. If introducing a new command, add it here.
 * 
 * @param parameterManager
 */
private void addSupportedCommands(ParameterManager parameterManager) {
	addSupportedCommand(new PrintTypeAttributesCommand(
			new ParameterManager(parameterManager.getArguments())));
	addSupportedCommand(new CreateWorkItemCommand(new ParameterManager(
			parameterManager.getArguments())));
	addSupportedCommand(new UpdateWorkItemCommand(new ParameterManager(
			parameterManager.getArguments())));
}

Now the method runCommands() gets the command from the Parameter Manager. If there is a command string, it gets the class that implements the command. If there is a command registered for this command string, runCommand() calls the command to validate if the required parameters for it to run are available. If this is the case, runCommand() calls the command and returns the result back.

In all other cases runCommand() prepares a result error and also uses the method helpGeneralUsage() to print a help for the command.

Adding Commands to the WorkItemCommandLine

It is easy to add new commands to the WorkitemCommandLine. You need to implement a new command and add a new entry for it in the method addSupportedCommands().

How Commands Work

Commands have to implement the IWorkItemCommand interface. You should pick one of the abstract classes in the framework and extend them. This makes sure the basic workflow will work. If you command needs to create or modify a work item based on property values, use the class AbstractWorkItemModificationCommand. If you only need to have a repository connection, use the class AbstractTeamRepositoryCommand. In both cases all you need to do really is to override and implement the methods required. There are three things that need to be there.

In the method getCommandName() you need to return the name of the command you implement.

@Override
public String getCommandName() {
	return IWorkItemCommandLineConstants.COMMAND_CREATE;
}

If your command needs additional parameters, override the method setRequiredParameters(). Call the method of the superclass to have it add its required parameters and add your parameters. Here is an example

/*
 * (non-Javadoc)
 * 
 * @see com.ibm.js.team.workitem.commandline.framework.
 * AbstractWorkItemCommandLineCommand#setRequiredParameters()
 */
public void setRequiredParameters() {
	super.setRequiredParameters();
	// Add the parameters required to perform the operation
	// getParameterManager().syntaxCommand()
	getParameterManager()
			.syntaxAddRequiredParameter(
					IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY,
					IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY_EXAMPLE);
	getParameterManager()
			.syntaxAddRequiredParameter(
					IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY,
					IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY_EXAMPLE);
	getParameterManager().syntaxAddSwitch(
			IWorkItemCommandLineConstants.SWITCH_IGNOREERRORS);
	getParameterManager().syntaxAddSwitch(
			IWorkItemCommandLineConstants.SWITCH_ENABLE_DELETE_ATTACHMENTS);
	getParameterManager().syntaxAddSwitch(
			IWorkItemCommandLineConstants.SWITCH_ENABLE_DELETE_APPROVALS);
}

Parameters added with syntaxAddRequiredParameter() will be assumed to be required. If they are not available the command line will show an error during the parameter validation. The error message is automatically created from the parameter information provided here.

Finally you have to override and implement the method process() to implement the command.

/*
 * (non-Javadoc)
 * 
 * @see com.ibm.js.team.workitem.commandline.framework.
 * AbstractWorkItemCommandLineCommand#process()
 */
@Override
public OperationResult process() throws TeamRepositoryException {
	// Get the parameters such as project area name and Attribute Type and
	// run the operation
	String projectAreaName = getParameterManager()
			.consumeParameter(
					IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY)
			.trim();
	// Find the project area
	IProjectArea projectArea = ProcessAreaUtil.findProjectArea(
			projectAreaName, getProcessClientService(), getMonitor());
	if (projectArea == null) {
		throw new WorkItemCommandLineException("Project Area not found: "
				+ projectAreaName);
	}

	String workItemTypeID = getParameterManager().consumeParameter(
			IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY)
			.trim();
	// Find the work item type
	IWorkItemType workItemType = WorkItemHelper.findWorkItemType(
			workItemTypeID, projectArea.getProjectArea(),
			getWorkItemCommon(), getMonitor());
	// Create the work item
	createWorkItem(workItemType);
	return this.getResult();
}

To complete the code of this command, here is the method that creates the work item and uses the parameters to update the attributes.

/**
 * Create the work item and set the required attribute values.
 * 
 * @param workItemType
 * @return
 * @throws TeamRepositoryException
 */
private boolean createWorkItem(IWorkItemType workItemType)
		throws TeamRepositoryException {

	ModifyWorkItem operation = new ModifyWorkItem("Creating Work Item");
	this.setIgnoreErrors(getParameterManager().hasSwitch(
			IWorkItemCommandLineConstants.SWITCH_IGNOREERRORS));
	IWorkItemHandle handle;
	try {
		handle = operation.run(workItemType, getMonitor());
	} catch (TeamOperationCanceledException e) {
		throw new WorkItemCommandLineException("Work item not created. "
				+ e.getMessage(), e);
	}
	if (handle == null) {
		throw new WorkItemCommandLineException(
				"Work item not created, cause unknown.");
	} else {
		IWorkItem workItem = getAuditableCommon().resolveAuditable(handle,
				IWorkItem.SMALL_PROFILE, getMonitor());
		this.appendResultString("Created work item " + workItem.getId()
				+ ".");
		this.setSuccess();
	}
	return true;
}

In case you wonder where the actual work gets done – I wondered looking at it. The line

handle = operation.run(workItemType, getMonitor());

does all the work. By calling it this way, the WorkItemOperation creates the work item. The operation is based upon the code in the class AbstractWorkItemModificationCommand.

In that class, the execute() method is overwritten with this code:

/*
 * This is run by the framework
 * 
 * (non-Javadoc)
 * 
 * @see
 * com.ibm.team.workitem.client.WorkItemOperation#execute(com.ibm.team
 * .workitem.client.WorkItemWorkingCopy,
 * org.eclipse.core.runtime.IProgressMonitor)
 */
@Override
protected void execute(WorkItemWorkingCopy workingCopy,
		IProgressMonitor monitor) throws TeamRepositoryException,
		RuntimeException {
	// run the special method in the execute.
	// This is called by the framework.
	update(workingCopy);
}

The call to the method update() does the real work. It walks through all the unconsumed parameters in the parameter list – which should contain the attributes and values to be set and applies the changes to the work item.

/**
 * This operation does the main task of updating the work item
 * 
 * @param workingCopy
 *            the workingcopy of the workitem to be updated.
 * 
 * @throws RuntimeException
 * @throws TeamRepositoryException
 */
public void update(WorkItemWorkingCopy workingCopy)
		throws RuntimeException, TeamRepositoryException {

	ParameterList arguments = getParameterManager().getArguments();

	// We use a WorkItemHelper to do the real work
	WorkItemHelper workItemHelper = new WorkItemHelper(workingCopy,
			arguments, getMonitor());

	// Run through all properties not yet consumed and try to set the values
	// as provide
	for (Parameter parameter : arguments) {
		if (!(parameter.isConsumed() || parameter.isSwitch() || parameter
				.isCommand())) {
			// Get the property ID
			String propertyName = parameter.getName();
			// Get the property value
			String propertyValue = parameter.getValue();
			try {
				workItemHelper.updateProperty(propertyName, propertyValue);
			} catch (WorkItemCommandLineException e) {
				if (this.isIgnoreErrors()) {
					this.appendResultString("Exception! " + e.getMessage());
					this.appendResultString("Ignored....... ");
				} else {
					throw e;
				}
			} catch (RuntimeException e) {
				this.appendResultString("Runtime Exception: Property "
						+ propertyName + " Value " + propertyValue + " \n"
						+ e.getMessage());
				throw e;
			} catch (IOException e) {
				this.appendResultString("IO Exception: Property "
						+ propertyName + " Value " + propertyValue + " \n"
						+ e.getMessage());
				throw new RuntimeException(e.getMessage(), e);
			}
		}
	}
}

The Class WorkItemHelper

This class is basically doing all the work related to modifying work item data. The helper needs to be instantiated. Then the method updateProperty() can be called.

public void updateProperty(String propertyID, String value)
		throws TeamRepositoryException, WorkItemCommandLineException,
		IOException {
.
.
.
}

The method checks if the attribute is one of the special ones like the type, or complex attributes such as workflow or state changes, approvals or other pseudo attribute ID’s and handles these if detected. Otherwise it calls the method updateGeneralAttribute() to handle the update.

private void updateGeneralAttribute(ParameterValue parameter,
		List exceptions) throws TeamRepositoryException,
		WorkItemCommandLineException {
.
.
.
}

The method updateGeneralAttribute() checks if this attribute is actually available on the work item. If so it calls getRepresentation() to get a value that can be set for the attribute.

private Object getRepresentation(ParameterValue parameter,
		List exceptions) throws TeamRepositoryException,
		WorkItemCommandLineException {
.
.
.
}

The method getRepresentation() basically is a huge list of checks to narrow down what type the attribute to modify is. If the type is narrowed down, it calls a related methods to parse the input data and to create a value for the attribute, that can be returned and set.

Summary

This post explains how the code works and how you can utilize it to implement your own commands. As always, I hope that helps someone out there.

While creating this post, I realized, that I should have named some of the classes differently. This framework is not only good for a work item command line. This code could be used for any command line. Maybe I will adjust this a bit in later versions, should time permit.

Posted in Jazz, RTC, RTC Automation, RTC Extensibility | Tagged , , , , , , , , , , , | Leave a comment

A RTC WorkItem Command Line Version 2


After publishing the first version of the RTC WorkItem Command Line  I realized several things that users might want to do that were not supported. So I updated the version to 2.0 and added these capabilities. I also found an issue with setting string lists, which is also now fixed.

This post, like the previous, provides a simple Work Item Command Line Client and explains the usage. It comes with code, so you can also enhance it if you need more features.

What’s new?

This version of the RTC WorkItem Command Line is complete as far as I am concerned.

  • It still supports work item creation and update.
  • It now supports all attribute types and the link types that I think can be supported. The missing Item types are now supported.
  • It now supports several modes to modify the work item properties such as set the value, add to the available value or remove data.
  • It supports a RMI server mode to enhance performance if multiple calls are needed
  • It supports the RMI client mode to delegate requests to the RMI server portion.

Related posts

WorkItemCommandLine Summary

The WorkItemCommandLine – in short WCL – works on Windows and Unix clients. It requires a JDK and the Plain Java Client Libraries to be installed. Please note, I had issues running the Plain Java Client Libraries with just a JRE. You can try to use a JRE, if you like.

It currently allows to

  • Create work items
  • Update work items
  • Show the attributes ID’s available for a work item type in a project area

The WCL allows to set and update all available attribute types (I am aware of) in RTC 4.x up to 5.0.2.

  • String based attributes
  • Number based attributes
  • Enumeration and Enumeration List based attributes
  • Tag based attributes
  • Typed and untyped Item type attributes
  • Typed and untyped ItemList type attributes
  • ……

This works for built in attributes as well as for custom attributes.

In addition to these attribute types various not attribute based work item values can be modified:

  • Subscription
  • Comments
  • Approvals
  • Links to work items
  • CLM links to work items
  • CLM links to Requirements Management and Test artifacts and to SCM change sets
  • Links from build results
  • Attachments can be uploaded
  • Trigger a workflow action

This should be sufficient for most of the automation needs, especially during builds.

The WCL supports the following operations modes on work item attributes:

  • set – set the value of the attribute, overwriting or deleting existing information
  • add – add values or data to the attribute
  • remove – delete values or data from the attribute
  • default – dependent on the type of the attribute set the value or add values

The WCL supports RMI where the WCL runs as a RMI server and WCL can delegate calls to that server to have them processed. This only requires starting the team platform once and saves several seconds in subsequent calls.

License and Getting Started

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.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment.

Download

You can download the latest version here:

Setup

Download the packaged executable application. The file is compressed and will be named like wcl-Vx-YYYYMMDD.zip. The x represents the version number and is followed by the date it was created.

If you have installed an RTC API development environment following the RTC Extensions workshop and this post, you have all else that is needed and can use  the installs folder of your extension development install, for example C:\RTC401Dev\installs.

Extract the file e.g. using 7Zip to a folder, for example C:\RTCWCL (or C:\RTC401Dev\installs).

The destination folder should now contain a folder wcl.

If you don’t have an extension development environment set up, download and install the Plain Java Client Libraries for your version of RTC. Open the All Downloads tab of the RTC version you are interested in. For example https://jazz.net/downloads/rational-team-concert/releases/4.0.1?p=allDownloads and scroll down to the Plain .zip Files section.

PlainJavaDownloadDownload the Plain Java Client Libraries file.

Use 7Zip and unzip the Plain Java client Libraries download file (for example named RTC-Client-plainJavaLib-4.0.1.zip). Use 7Zips Extract Files command and provide the extraction Path C:\RTCWCL\PlainJavaAPI .

If you don’t have an extension development environment set up, download and install a Java JDK. If you have the Rational Team Concert client installed a compatible JDK is available in the install location e.g. TeamConcert\jazz\client\eclipse\jdk. The easiest way is to download the zip version of the Rational Team concert Client and extracting it to C:\RTCWCL\TeamConcert.

The folder should now look similar to this image.

Install Folder

Adjusting the Scripts to the Environment

If you downloaded a different JDK or have the RTC Eclipse client installed in a different location, follow the next steps to adjust the WCL to the different paths.

Open the folder created when extracting the WCL for example C:\RTCWCL\wcl. The folder contains the script files

  • wcl.bat – for Windows clients
  • wcl.sh – for client with Unix/*ux operating systems such as Linux
  • rmi_no.policy – a RMI policy file
  • README.txt – the online help printed in a file

Open the files relevant for your operating system. They should look similar to this:

Script

The scripts assume an install structure where the JDK and the Plain Java Client Libraries are installed like in the image before. If your setup uses different paths, adjust then according to your setup. The scripts for usage with RMI only add a statement to the rmi_no.policy file.

On Unix operating systems chmod the shell scripts so that they are executable and the RMI policy is readable.

You should now be able to run the WorkItemCommandLine.

In order to allow RMI to work, WCL requires a policy file. Modify the file rmi_no.policy to your requirements and make sure it is in the same wcl folder on the server and the client. Make sure the policy file it is readable for the user that runs WCL.

Test the Environment

Open a shell or cmd window. change the directory to where you extracted WCL for example C:\RTCWCL\wcl. Type wcl and run the WorkItemCommandLine. The command should be executed and print help content like below.

Start WCLIf this does not happen, make sure the paths are set correctly and the JDK is compatible.

Please note, because the version 2.0 supports so much more, the help is very long and the windows shell can cut it off. To avoid this, you can

  1. Redirect the output into a file for example by typing wcl>wcl_help.txt
  2. Change the console setting to increase the size and buffer using mode con: lines=1100 cols=150

The README.txt is provided as help for convenience.

The Syntax of WCL

WCL uses the following syntax:

wcl -<command> {/<switch>} {<parameter>[:<mode>]=<value>}

Where <command>, at this time, can be

  • create
  • update
  • printtypeattributes

The commands have their own requirements for base parameters such as repository URL, users, password and the like.

Switches

WCL provides several switches that influence the behavior. Some switches are command specific, others are general. Available values for <switch> are:

  • ignoreErrors allows to successfully perform the create and update command if minor errors happen. Errors covered are for example if an optional attribute or its value was not found. If the flag is provided, WCL will continue to perform the next operations and print the error. If the flag is not provided any error will cause the operation to fail.
  • enableDeleteAttachment enables deletion of attachments using the set or the remove mode.
  • enableDeleteApprovals enables deletion of approvals using the set or the remove mode.
  • rmiServer is used to start the RMI server, see the RMI section below.
  • rmiClient is used to run the Workitem Command Line  against a RMI server instead of processing the command itself. See the RMI section below

Parameters

Values for <parameter> are usually the ID of a work item attribute. The WCL defines various pseudo attribute names, typically prefixed with an @ e.g. to create links and upload files as attachment. The reason for the prefix is that RTC does not allow to start attribute ID’s with special characters and this makes it impossible to define custom attributes with conflicting names.

The parameter sections <parameter>=<value> must not have spaces in the <parameter> or in the <value> or before or after the =. The value of <parameter>, <value> or the whole term can be enclosed in quotation marks “.

Parameter and value example:

projectArea=”JKE Banking (Change Management)”

Each parameter can only be used once in the command line. In some cases like attachment uploads a special section needs to be added in the parameter to allow for multiple specifications in one call.

Multiple parameter example, ‘_2′ is used to make the second parameter unique:

@attachFile:add="./Test.txt:Some Description:text/plain:UTF-8" @attachFile_2:add="./Test.txt:Some Description:text/plain:UTF-8"

The WCL also has an alias mechanism built in, that allows to map different external names for attributes to the internal representation. Currently the names of the AttributeCustomization described here are built in. This allows, for example, to use FOUND_IN=”Sprint 2 Development” instead of foundIn=”Sprint 2 Development”. You can add your own aliases if needed.

Values
The <value>s are specified by a string. Parameter values are usually the display value of elements (enumerations) or composed of display values of the path to this item (category, iterations, process areas). For example setting an enumeration attribute would use the display name “High”, instead of the literal ID. This makes it easier to use. In some cases e.g. for links, subscriber lists and other user lists, it is necessary to specify the ID of the element instead of the display name.

Value examples

  • For enumeration based attributes use the display value for the enumeration literal:
    internalPriority=High
  • For HTML and string based attributes use a string. HTML types like summary, description, comment and HTML support the syntax below:
    description=”Plain text<br/><b>bold text</b><br/><i>italic text</i><br/><a href=”https://rsjazz.wordpress.com”>External RSJazz Link</a><br/>User link to <b>@ralph </b><br/>Work Item link to Defect 3 <br/>”
  • For Wiki and multi line text attributes use <br> or \n for line breaks and check the syntax in the wiki editor. The full description for the Wiki Syntax can be found here. Example for a Wiki entry:
    custom.wiki=”<br>=Heading1<br><br>Plain text\n==Heading 2\n\nNormal Text **bold text** <br>**bold text**<br>//Italics//”
  • For work item type, owner and some other attributes use the object ID:
    workItemType=task
    owner=tanuj
  • Use the display name for simple attributes or the path composed out of the display names for hierarchical attributes;
    category=JKE/BRN
    foundIn=”Sprint 2 Development”
    target=”Main Development/Release 1.0/Sprint 3″
    custom.process.area=”JKE Banking (Change Management)/Release Engineering”
  • Dates have to be specified in the Java SimpleDateFormat notation:
    dueDate=”2015/02/01 12:30:00 GMT+01:00″
  • Duration values are specified in milliseconds:
    duration=1800000 correctedEstimate=3600000 timeSpent=60000

Lists

Work item attribute values of <item type>List with a specified item type such as userList. Use the separator  ‘,‘ like in “value1,value2,…,valueN” to separate values.

Example user list: custom.user.list:add=”deb,al,bob,tanuj”

Work item attributes with an general attribute value type such as Item or itemList require encoding to locate the items. The format is: custom.item.list=value

Where value has the form: <value>{,<value>}

Each <value> having the form <TypeDescriptor>:<Item> with no spaces allowed in the value list.

Available values for <TypeDescriptor> and examples for Item and itemList attribute values:

  • ProjectArea – specified by its name.
    Example: “ProjectArea:JKE Banking (Change Management)”
  • TeamArea – specified by its name path from the project area to the team area.
    Example: “TeamArea:JKE Banking (Change Management)/Release Engineering”
  • ProcessArea – specified by the name path from the project area to the process area.
    Example: “ProcessArea:JKE Banking (Change Management)/Business Recovery Matters”
  • Category – specified by the category path.
    Example: “Category:JKE/BRM”
  • User – specified by the users user id.
    Example: “User:tanuj”
  • Iteration – specified by the iterations name path (including the development line name).
    Example: “Iteration:Main Development/Release 1.0/Sprint 3″
  • WorkItem – specified by the work items id.
    Example: “WorkItem:20″
  • SCMComponent – specified by the Jazz SCM components display name.
    Example: “SCMComponent:Build”

Modes

Modes allow different types of changes to attributes such as add values, append text or remove and set other data. The mode is specified using this syntax:

<parameter>[:<mode>]=<value>

Supported values for <mode> are default (no mode specified), add, set and remove.

If no mode is specified, the default mode for the parameter is used.

  • Example for default mode: summary=”This is a summary.”.
  • Example for add mode: summary:add=” Add this to the summary.”.
  • Example for set mode: summary:set=”Overwite the existing summary with this text.”.
  • Example for remove mode: custom.enumeration.list:remove=$,Unassigned.

Which modes are supported and their behavior depends on the attributes type.

  • Single value attributes typically support default and set mode, but not add and remove mode.
    • Default mode for single value attributes is set the value.
  • Multiple value attributes, such as lists and links, typically support default, add, set and remove mode.
    • Default mode for multiple value attributes is add, which adds the value(s).
    • Set mode for multiple value attributes removes the old values and then adds the new value(s).
    • Remove mode for multiple value attributes removes the specified values that can be found.
  • String values such as HTML, Summary, Wiki type attributes support default (same behavior as set mode), set and add mode.

The Print Type Attributes Command to get the Attribute ID’s and Types

To set work item attributes, WCL needs the ID of the attribute. You can look up the ID of an attribute in the process configuration. The command printtypeattributes prints the attribute ID’s for the built-in and for the custom attributes of a work item type in a project area. The command requires, in addition to the repository URL, the user and password, at least the project area and the work item type to look up. Syntax and required parameters:

wcl -printtypeattributes repository=RepositoryURI user=userID password=password  projectArea=ProjectAreaName workItemType=WorkItemTypeID {parameter[:mode]=value}

Example

wcl -printtypeattributes repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task

Please note, for the built in attributes this returns an internal ID that might not show up if you look into the process configuration. You can use the ID’s you find there too, the API should translate them correctly.

The Create Command

The command create can be used to create a new work item and set its attributes.

The command requires, in addition to the repository URL, the user and password, at least the project area and the work item type to create. Please note, if the process specifies additional required attributes, these need to be provided as well, otherwise the creation and save operation will fail. Syntax and required parameters:

wcl -create repository=RepositoryURI user=userID password=password  projectArea=ProjectAreaName workItemType=WorkItemTypeID {parameter[:mode]=value}

Here an example for creating a work item.

wcl -create /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task summary="New Item" category=JKE owner=ralph

The command will report back the ID of the newly created work item if the operation was successful.

The Update Command

The command update can be used to update a work items attributes.

The command requires, in addition to the repository URL, the user and password, at least the ID of the work item to update. Syntax and required parameters:

wcl -update repository=RepositoryURI user=userID password=password  id=workItemID {parameter[:mode]=value}

Please note, if the process specifies additional required attributes, these need to be provided as well, otherwise the save operation will fail. This can be relevant if the state of a work item is changed.

Here is an example where a work item gets heavily updated:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 SUMMARY="New summary" FOUND_IN="Sprint 2 Development" owner=ralph target="Main Development/Release 1.0/Sprint 3" internalSeverity=Major foundIn="Sprint 2 Development" internalPriority=High attachFile="./Test.txt:Some Description:text/plain:UTF-8" internalApprovals="approval:Please Approve:ralph,deb" internalSubscriptions=al,ralph,deb internalState="In Progress" internalTags="test1,test2" custom.duration=1800000 custom.boolean=true custom.contributor=al custom.contributor.list=al,deb,tanuj custom.decimal=1500200 custom.integer=234 custom.long=567 custom.tag=tag1,tag2 custom.timestamp="2014/12/31 12:30:00 GMT+01:00" custom.wiki="My Wiki" custom.projectarea.list="JKE Banking (Change Management)" custom.project.area="JKE Banking (Change Management)" custom.teamarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering" custom.team.area="JKE Banking (Change Management)/Release Engineering" custom.process.area="JKE Banking (Change Management)/Release Engineering" custom.processarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering" custom.workitem=3 custom.workitem.list=9,20,7

The command will report back the ID of the updated work item if the operation was successful.

Special Attributes and not  Attribute Based Work Item Modifications

Some attribute types need special treatment or require more complex values to be specified. Some have other limitations and considerations. These are explained below.

For Item List attributes the items need to be provided as a list of items with the separator “,”. As an example a work item attribute of type TeamAreaList would be set like this:

custom.teamarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering"

Please note, that this implies that the separator ‘,’ can not be part of any of the display names of the elements.

Special Properties Handling

Some special properties are protected from changing.

  • Work Item ID: can not be changed
  • Project Area: parameter “projectArea” can only be specified when creating the work item. It can not be set to a different value later.

There might be other limitations imposed by the process e.g. against changing the creator of a work item.

Comments

The parameter “internalComments” can be used to add a comment. This pseudo attribute only supports the default and add mode. Removing comments is not supported in the WCL. Comments support the HTML syntax mentioned above allowing to create web links, user and work item links. Example:

internalComments=””Plain Text<br/><b>Bold Text</b><br/><i>Italic Text</i><br/> <a href=\”https://rsjazz.wordpress.com\”>External RSJazz Link</a>  <br/><b>@ralph </b><br/>Defect 3 <br/>”

User, User Lists

For attributes that require users or user lists the value of the property needs to specify the user or the list of users with the ID. Examples:

internalSubscriptions=al,ralph,deb custom.contributor.list=al,deb,tanuj

Subscriptions

The parameter internalSubscriptions can be used to subscribe a list of users to a work item using their user ID’s. The syntax is:

internalSubscriptions[:mode]=<userID>{,<userID>}

This attribute supports the modes default (same as) add, set and remove mode.

  • Example set specific users (removing all others):
    internalSubscriptions:set=al,tammy
  • Example add users:
    internalSubscriptions:add=deb,tanuj,bob
  • Example remove users:
    internalSubscriptions:remove=sally,bob

Example:

wcl -update repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalSubscriptions:add=al,ralph,deb

Tags

The parameter internalTags can be used to add a list of tags. This attribute supports the modes default (same as) add, set and remove. The syntax is:

internalTags[:<mode>] =<Tag>{,<Tag>}

Example to set the tag list of the work item to two tags test1 and test2, removing all other tags:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalTags:set="test1,test2" custom.tags="MyTag"

Approvals

The parameter internalApprovals can be used to add approvals and approvers. Approvals only support the modes default (same as) add, set and remove. Set and remove only affects approvals of the same approval type. For example, mode set for approval type review will only remove existing reviews. The syntax is:

internalApprovals[<ID>][:mode]=”<approval_type>:<Approval Name>{:<userID> {,userIDn}}”

The name of the approval to be created <Approval Name> is required. The Approver ID list is optional and it is possible to add one or more approver userID’s. Example without approvers

internalApprovals:add=”verification:Please Verify”

The section <ID> can be left out if only one approval is specified. If multiple approvals are specified, it needs to be a unique string. In the example below “_1″ and “_2″ make the parameters uniquely distinguishable:

internalApprovals_1:add="approval:Please approve:ralph,deb" internalApprovals_2:add="verification:Please verify:tanuj"

Available values for <approval_type> are

  • approval – to create an approval record
  • review – to create a review record
  • verification – to create a verification record

Examples:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="approval:Please approve:ralph,deb"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="review:Please review:deb"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="verification:Please verify:tanuj"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="verification:We need a verification"

The implementation of the modes set and remove is as follows. Removal of approvals by either set or remove mode must be explicitly enabled using the switch enableDeleteApprovals, otherwise the command will fail if one of these modes is used with a internalApproval parameter.

The mode set removes all existing approvals of the specified <approval_Type> and then adds a new approval of this type as specified.

The mode remove searches for all approvals of the specified <approval_Type> and deletes those found with a matching the Approval Name.

Workflow and State Change

The WCL allows to set the state of the work item in different ways. Please note, the state is reached after the save operation, if it can be set.

A pseudo parameter @workflowAction can be used to set a workflow action to change the work item state when saving. This attribute supports only the modes default and set.

When using this pseudo parameter WCL looks up the current state of the work item, tries to find a workflow action with the given display name. If one exists, it  sets the save operation to trigger this action when the work item gets saved.

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=115 @workflowAction="Reopen"

Another example: @workflowAction=”Stop working” . Please note, the workflow change is governed by the RTC process engine. If RTC prevents the state change, the operation will fail on save. It is impossible to detect this prior to the save.

The parameter internalState representing the attribute to read the state can be used to set the state. The parameter only implements the modes default and set, which act equal. The syntax is:

internalState=[<forceFlag>:]StateName

Where <forceFlag> is the value forceState.

Without the forceFlag provided WCL acts similar to using the pseudo parameter @workflowAction. It looks up the current state, and checks if any workflow action from the current state exists, that leads to the specified target state. If there is one, it sets the workflow action to be performed during the save operation. If there is no workflow action the state change is not performed.

Example with a target state:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalState="In Progress"

If the flag forceState: is added before the target state, WCL uses a deprecated API to forcefully set the state. Please note, that this does not trigger a workflow action and does also not trigger operational behavior. It should be used with caution. If the target state exists in the workflow of the work item type, the state is set, regardless if it is reachable directly or using multiple workflow actions or even if it is not reachable by the workflow at all.

Example with a target state forcefully set:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalState="forceState:New"

State Resolution

The resolution of a work item can be set using the attribute internalResulution. The parameter only implements the modes default and set, which act equal. The parameter value provided is the display value of the resolution.

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalResolution=Invalid

 Attachments

The WCL provides a capability to manipulate work item attachments. The pseudo parameter @attachFile can be used to upload and remove attachments. This attribute supports the modes default (same as) add, set and remove. The syntax format is:

@attachFile[<IDString>]=”SomeFilePath:Some Description:<ContentTypeID>:<EncodingID>”

Where:

<ContentTypeID> has one of the following values:

  • text/plain
  • application/unknown
  • application/xml

<EncodingID> has one of the following values:

  • UTF-8
  • UTF-16LE
  • UTF-16BE
  • us-ascii.

As above, <IDString> must be unique for multiple attachments in one command. If only one attachment is uploaded, the <IDString> can be left empty.

The file must be accessible and in the correct encoding for the operation to perform correctly.

As above for approvals the mode set is implemented to remove all attachments first and then add the new attachment. The mode remove is implemented to search for an attachment with the same file path and description and remove it if it is available.

Some examples:

-update /ignoreErrors  repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=150 @attachFile="./Test.txt:Some Description:text/plain:UTF-8" @attachFile_2:add="./Test.txt:Some Description:text/plain:UTF-8"
-update /ignoreErrors /enableDeleteAttachment repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=150 @attachFile:remove="./Test.txt:Some Description:text/plain:UTF-8"
-update /ignoreErrors /enableDeleteAttachment repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=150 @attachFile:set="./Test.txt:Some Description:text/plain:UTF-8"

Duration Types

In duration types provide the value in milliseconds. For example

custom.duration=1800000

Timestamps

Timestamps need to be provided as string in the SimpleDateFormat using the format pattern “yyyy/MM/dd hh:mm:ss z”. For example:

custom.timestamp="2014/12/31 12:30:00 GMT+01:00"

Links

The pseudo parameter @link_ can be used to link the current work item to other objects. The syntax is

@link_<link_type>=<target>{|<target>}

Where <link_type> specifies the type of link to be created, for example reportAgainstBuild and the values on the right side specifies one target object or a list of target objects to be linked to the current work item using the link type. The separator used here is the pipe symbol ‘|‘. The reason is, that the links can be URI’s and the naming conventions are problematic. It is hard to find a character that is likely not to appear in that string. Not everyone sticks to the specification and the pipe symbol seemed to be appropriate.

The parameter supports the modes default (same as) add, set and remove.  Similar to other implementations above the mode set removes all links of the specified <link_type> before creating the new links. The mode remove tries to find an existing link of the <link_type> with the same target and removes this link, if it exists.

There are different ways the links get created, dependent on what link type and what target elements are specified.

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 @link_parent=1 @link_blocks=2,3 @link_reportAgainstBuild=P20141208-1713|@_IjluoH-oEeSHhcw_WFU6CQ,P20141208-1713
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=150 @link_tracks_workitem="https://clm.example.com:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/80|4|5" @link_affected_by_defect=123 @link_affects_plan_item=20|30 @link_related_change_management=4|7
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=150 @link_related_artifact="https://rsjazz.wordpress.com/"  @link_affects_requirement="https://clm.example.com:9443/rm/resources/_6c96bedb0e9a490494273eefc6e1f7c5" @link_tested_by_test_case="https://clm.example.com:9443/qm/oslc_qm/contexts/_6u2zcH-nEeSJhuhJc8_drg/resources/com.ibm.rqm.planning.VersionedTestCase/_N6HHYX-oEeSJhuhJc8_drg"

Work Item Links – links between this work item and another work item within the same repository

The following <link_types> are supported from the current work item to a target work item. These links are local to the repository this work item belongs to. This means the value list is a list of work item numbers separated by pipe ‘|’ symbols.

  • copied
  • copied_from
  • successor
  • blocks
  • resolves
  • mention
  • predecessor
  • parent
  • duplicate_of
  • duplicate
  • related
  • depends_on
  • child
  • resolved_by

Please note, that if you try to create a link that can not be supported on the target end, save errors will show up. As an example if a target is set to be the child of this work item and that work item has already some other work item set as parent, the save will fail.

Format example:

@link_related=123|80

CLM Work Item Links – CLM links between this work item and another work item within the same or across repository boundaries

The following <link_types> are supported from the current work item to a target work item. These links can be local to the repository this work item belongs to, or to work items in another repository. The parameter value is a list of one or more work items specified by their ID (if they are in the same repository) or by their Item URI separated by pipe ‘|’ symbols. To understand the URI format, look at an existing link in the RTC web UI and inspect the link target. Wrong target formats can lead to corrupt data.

  • affects_plan_item
  • tracks_workitem
  • related_change_management
  • affected_by_defect

Format example:

@link_tracks_workitem="https://clm.example.com:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/80|120|150"

CLM URI Links – CLM links between this work item and another item, described by a valid URI, in a different application or repository.

The following <link_types> are supported from the current work item to a target item such as a requirement, test case or test result. These links are across repositories and applications. The parameter value is a list of one or more items, that support this link type, specified by their Item URI separated by pipe ‘|’ symbols. To understand the URI format, look at an existing link in the RTC web UI and inspect the link target. Wrong target formats can lead to corrupt data.

  • related_test_plan
  • affects_requirement
  • tested_by_test_case
  • blocks_test_execution
  • implements_requirement
  • affects_execution_result
  • related_artifact
  • related_test_case
  • elaborated_by
  • tracks_requirement
  • scm_tracks_scm_changes
  • related_execution_record

Format example:

@link_affects_requirement=https://clm.example.com:9443/rm/resources/_848a30e315524069854f55e1d35a402d|https://clm.example.com:9443/rm/resources/_6c96bedb0e9a490494273eefc6e1f7c5

Please note that the link “Associate Work Item” between a change set and the work item can only be created by the SCM component. The link created here is the looser CLM link. Create the work item change set link using the SCM command line.

Build result Links – Links from a work item to a build result in the same repository.

The following <link_types> are supported from the current work item to a build result. These links are within a repository. The parameter value is a list of one or more build results. The Build result can be specified by its Build Result Label or by the Build Result ID separated by pipe ‘|’ symbols. The parameter value is a list of one or more Buildresults specified by their ID or their label. The WCL distinguishes between build result ID and Build Label, add @ as prefix to the Build Result Label.

  • reportAgainstBuild
  • includedInBuild

Please note that the link includedBuild should only be created by the SCM system from the snapshot, it is only available for completeness.

Format example: @link_reportAgainstBuild=@_IjluoH-oEeSHhcw_WFU6CQ|P20141208-1713

RMI Modes

The WCL can be run as a local Java application. This is fine if only one work item needs to be modified. However, since each call requires the RTC API TeamPlatform to be started and the process takes around 6 seconds, this does not scale for a lot of calls, it is possible to run the work item command line in a RMI server mode on the same or a different machine. This server waits for incoming requests and only needs to initialize the API once.

Called from another RMI client process, the server can process requests very fast and return the result. This can be achieved with two switches to set up the server and to delegate the call to the server.

The syntax for the switches is

/<switch>[=<RMI_Name>]

Where <switch> is one of the following values.

  • rmiServer
  • rmiClient

By default the RMI Name used to connect to the RMI server is “//localhost/RemoteWorkitemCommandLineServer” using a default port of 1099 for the RMI registry.

It is possible to define a different name and port by providing a value. The example below starts WCL as RMI server with name “//clm.example.com/WorkItemCommandLine” with a RMI registry listening to port 1199:

wcl /rmiServer=//clm.example.com:1199/WorkItemCommandLine

By providing the same naming in the rmiClient switch for the requested command, the connection can be established.

wcl -create /rmiClient=//clm.example.com:1199/WorkItemCommandLine /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task summary="New Item" category=JKE owner=ralph target="Main Development/Release 1.0/Sprint 3" internalSeverity=Major foundIn="Sprint 2 Development" internalPriority=High creator=myadmin

If the WCL is started as RMI server, the process will not terminate, but RMI will listen to requests and delegate them to that process. It is not necessary to provide a command or any other input values, when starting the WCL in RMI server mode as they will be ignored. RMI will make the process available and call it to service commands requested by other client instances that are started with the additional switch /rmiClient added to the command that is supposed to be performed.

Please note, that the server and the client require a policy file for the security manager.  A policy file rmi_no.policy is shipped with the download. The policy file opens up everything.

So please rename and modify the file to your requirements

To enable security Java requires to call the class with the additional vm argument -Djava.security.policy=rmi_no.policy where the policy file name must exist and be readable on the server and on the client side.

Predefined Attribute ID Aliases

Aliases for attribute ID’s have been coded into the application. You can add your own aliases in the mapping table.
Available mappings:

RESOLUTION_DATE: resolutionDate
FOUND_IN: foundIn
PRIORITY: internalPriority
RESOLVER: resolver
SUMMARY: summary
ESTIMATE: duration
MODIFIED: modified
FILED_AGAINST: category
CREATOR: creator
RESOLUTION: internalResolution
MODIFIED_BY: modifiedBy
PLANNED_FOR: target
CREATION_DATE: creationDate
STATE: internalState
PROJECT_AREA: projectArea
OWNER: owner
TAGS: internalTags
DUE_DATE: dueDate
TYPE: workItemType
ID: id
TIME_SPENT: timeSpent
DESCRIPTION: description
SEVERITY: internalSeverity
CORRECTED_ESTIMATE: correctedEstimate

Summary

This WorkItem Command Line should allow for most of the automation needs when creating work items. In addition it is a nice resource for the RTC work Item API.

In later posts I will explain the code for users that are interested in adding their own implementation.

As always, I hope the post 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.

Posted in Jazz, RTC, RTC Automation, RTC Extensibility | Tagged , , , , , , , , , , ,

A RTC WorkItem Command Line V1.0 – Deprecated


Please refer to the new Version 2.0 of the RTC WorkItem Command Line. The code has been enhanced and received a lot of testing and will be the basis for future efforts.

Version 1.0 is Deprecated

Version 1.0 is Deprecated

Please refer to the new Version 2.0 of the RTC WorkItem Command Line. The code has been enhanced and received a lot of testing and will be the basis for future efforts.

I have seen many requests to be able to create and update work items from a command line in the forum. There are enhancement requests and a story for it in the Rational Team Concert development repository. I had a lot of the required code already available and thought I should provide a solution if possible.

This post provides a simple Work Item Command Line Client and explains the usage. It comes with code, so you can also enhance it if you need more features.

 

Related posts

  • Installing and using the WorkItemCommandLine – this post

WorkItemCommandLine Summary

The WorkItemCommandLine – in short WCL – works on Windows and Unix clients. It requires a JDK and the Plain Java Client Libraries to be installed.

It currently allows to

  • Create work items
  • Update work items
  • Show the attributes ID’s available for a work item type in a project area

The WCL allows to set and update almost all available attribute types.

  • String based attributes
  • Number based attributes
  • Enumeration and Enumeration List based attributes
  • Tag based attributes
  • ……

This works for built in attributes as well as for custom attributes.

The only attribute types currently not supported are Item and ItemList, where the type of the item is not specified or where the type is an SCM object. This might get implemented in the future. The problem is that the syntax needs to be able to specify what Item Type to look for in order to implement this, and to include the SCM component for searching.

Please note, for List attribute types it is currently only possible to set the list, unless described otherwise in the help. I am looking into a common parameter value encoding that can help more flexibility with being able to add and remove items as well.

In addition to these attribute types various not attribute based work item values can be modified:

  • Subscription
  • Comments
  • Approvals
  • Links to work items
  • Links from build results
  • Attachments can be uploaded
  • Trigger a workflow action

This should be sufficient for most of the automation needs, especially during builds.

License and Getting Started

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.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment.

Download

You can download the tool here:

Setup

Download the packaged executable application. The file is compressed and will be named like wcl-Vx-YYYYMMDD.zip. The x represents the version number and is followed by the date it was created.

If you have installed an RTC API development environment following the RTC Extensions workshop and this post, you have all else that is needed and can use  the installs folder of your extension development install, for example C:\RTC401Dev\installs.

Extract the file e.g. using 7Zip to a folder, for example C:\RTCWCL (or C:\RTC401Dev\installs).

The destination folder should now contain a folder wcl.

If you don’t have an extension development environment set up, download and install the Plain Java Client Libraries for your version of RTC. Open the All Downloads tab of the RTC version you are interested in. For example https://jazz.net/downloads/rational-team-concert/releases/4.0.1?p=allDownloads and scroll down to the Plain .zip Files section.

PlainJavaDownloadDownload the Plain Java Client Libraries file.

Use 7Zip and unzip the Plain Java client Libraries download file (for example named RTC-Client-plainJavaLib-4.0.1.zip). Use 7Zips Extract Files command and provide the extraction Path C:\RTCWCL\PlainJavaAPI .

If you don’t have an extension development environment set up, download and install a Java JDK. If you have the Rational Team Concert client installed a compatible JDK is available in the install location e.g. TeamConcert\jazz\client\eclipse\jdk. The easiest way is to download the zip version of the Rational Team concert Client and extracting it to C:\RTCWCL\TeamConcert.

The folder should now look similar to this image.

WCL Folder Structure

Adjusting the Scripts to the Environment

If you downloaded a different JDK or have the RTC Eclipse client installed in a different location, follow the next steps to adjust the WCL to the different paths.

Open the folder created when extracting the WCL for example C:\RTCWCL\wcl. The folder contains the script files

  • wcl.bat – for Windows clients
  • wcl.sh – for client with Unix/*ux operating systems such as Linux

Open the file relevant for your operating system. It should look similar to this:

Script

The script assumes an install structure where the JDK and the Plain Java Client Libraries are installed like in the image before. If your setup uses different paths, adjust then according to your setup.

On Unix operating systems chmod the shell script so that it is executable.

You should now be able to run the WorkItemCommandLine.

Test the Environment

Open a shell or cmd window. change the directory to where you extracted WCL for example C:\RTCWCL\wcl. Type wcl and run the WorkItemCommandLine. The command should be executed and print help content like below.

Start WCLIf this does not happen, make sure the paths are set correctly and the JDK is compatible.

The Syntax of WCL

WCL uses the following syntax:

wcl -<command> [/<flag>] [<parameter>=<value>]

Where <command> can be

  • create
  • update
  • printtypeattributes

The commands have their own requirements for base parameters such as repository URL, users, password and the like.

The flag

  • ignoreErrors allows to successfully perform the create and update command if minor errors happen. For example if an optional attribute or its value was not found. If the flag is not provided any error will cause the operation to fail.

The parameter sections <parameter>=<value> must not have spaces in the <parameter> or in the <value> or before or after the =. You can enclose the value of <parameter>, <value> or the whole term in quotation marks. For example projectArea=”JKE Banking (Change Management)”.

The WorkItemCommandline also defines various pseudo attribute names e.g. to upload files as attachment.

Each <parameter> can only be used once in the command line. In some cases like attachment uploads a special section needs to be added in the parameter to allow for multiple specifications.

The WorkItemCommandline also has an alias mechanism built in, that allows to map different external names for attributes to the internal representation. Currently the names of the AttributeCustomization described here are built in. This allows, for example, to use FOUND_IN=”Sprint 2 Development” instead of foundIn=”Sprint 2 Development”. You can add your own aliases if needed.

Parameter values <value> are usually the display value of elements. For example setting an enumeration attribute would use “High” instead of the literal ID. This makes it easier to use.

In some cases e.g. for links, subscriber lists and other user lists, it is necessary to specify the ID of the element instead of the display name.

The help given by the tool should be enough to figure out how to use it. However, here some more details and examples.

The Command to get the Attribute ID’s and Types

To set work item attributes, wcl needs the ID of the attribute. You can look up the ID of an attribute in the process configuration. The command printtypeattributes prints the attribute ID’s for the built-in and for the custom attributes of a work item type in a project area.

wcl -printtypeattributes repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task

Please note, for the built in attributes this returns an internal ID that might not show up if you look into the process configuration. You can use the ID’s you find there too, the API should translate them correctly.

The Create Command

The command create can be used to create a new work item and set its attributes.

The command requires, in addition to the repository URL, the user and password, at least the project area and the work item type to create. Please note, if the process specifies additional required attributes, these need to be provided as well, otherwise the creation and save operation will fail.

Here an example for creating a work item.

wcl -create /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task summary="New Item" category=JKE owner=ralph

The Update Command

The command update can be used to update a work items attributes.

The command requires, in addition to the repository URL, the user and password, at least the ID of the work item to update. Please note, if the process specifies additional required attributes, these need to be provided as well, otherwise the save operation will fail. This can be relevant if the state of a work item is changed.

Here is an example where a work item gets heavily updated:

-update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 SUMMARY="New summary" FOUND_IN="Sprint 2 Development" owner=ralph target="Main Development/Release 1.0/Sprint 3" internalSeverity=Major foundIn="Sprint 2 Development" internalPriority=High attachFile="./Test.txt:Some Description:text/plain:UTF-8" internalApprovals="approval:Please Approve:ralph,deb" internalSubscriptions=al,ralph,deb internalState="In Progress" internalTags="test1,test2" custom.duration=1800000 custom.boolean=true custom.contributor=al custom.contributor.list=al,deb,tanuj custom.decimal=1500200 custom.integer=234 custom.long=567 custom.tag=tag1,tag2 custom.timestamp="2014/12/31 12:30:00 GMT+01:00" custom.wiki="My Wiki" custom.projectarea.list="JKE Banking (Change Management)" custom.project.area="JKE Banking (Change Management)" custom.teamarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering" custom.team.area="JKE Banking (Change Management)/Release Engineering" custom.process.area="JKE Banking (Change Management)/Release Engineering" custom.processarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering" custom.workitem=3 custom.workitem.list=9,20,7

Special Attributes and not  Attribute Based Workitem Modifications

Some attribute types need special treatment or require more complex values to be specified. Some have other limitations and considerations. These are explained below.

For Item List attributes the items need to be provided as a list of items with the separator “,”. As an example a work item attribute of type TeamAreaList would be set like this:

custom.teamarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering"

Please note, that this implies that the separator can not be part of any of the display names of the elements.

Special Properties Handling

Some special properties are protected from changing.

  • Work Item ID: can not be changed
  • Project Area: can not be changed – use the category

There might be other limitations imposed by the process e.g. against changing the creator of a work item.

User, User Lists, Subscribers

For attributes that require users or user lists the value of the property needs to specify the user or the list of users with the ID. Examples:

internalSubscriptions=al,ralph,deb custom.contributor.list=al,deb,tanuj

Links

To create links to other elements a special pseudo attribute/parameter link is used. The syntax is:

link_<linktype>=<value>

The supported <linktype> values are printed in the help. The value is a list of item ID’s to link to. The list of one or more elements can either be a list of one or more work item ID’s or the label or ID, in case of a build result. Examples:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 link_parent=1 link_blocks=2,3 link_reportAgainstBuild=P20141208-1713

 Workflow, States and Resulutions

The WorkItemCommandline allows to set the state of the work item in different ways. Please note, the state is reached after the save operation, if it can be set.

You can specify a workflow action by using the pseudo parameter workflowAction. In this case wcl looks up the current state of the work item, tries to find a workflow action with the given name and sets the save operation to trigger this action when the work item gets saved. An example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=115 workflowAction="Reopen"

In addition the attribute internalState can be used to set the state.

Syntax is:

internalState=[<forceFlag>:]StateName

In this case wcl looks up the target state and tries to reach the state, using any available direct workflow action. If there is no workflow action the state change is not performed. If the flag forceState: is added before the target state, wcl uses a dprecated API to forcefully set the state. Please note, that this does not trigger a workflow action and does also not trigger operational behavior. It should be used with caution.

Example with a target state:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalState="In Progress"

Example with a target state forcefully set:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalState="forceState:New"

The resolution can be set using the attribute internalResulution. Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 workItemType=defect internalResolution=Invalid

Approvals

The WorkItemCommandline allows to create approvals, reviews and verifications. The syntax is

internalApprovals=”<approval_type>:<Approval Name String>:{<userID1>{,<userID>}}

Where <approval_type> is one of

  • approval
  • review
  • verification

The name of the approval <Approval Name String> is required and it is possible to add one or more approver userID’s

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="approval:Please approve:ralph,deb"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="review:Please review:deb"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="verification:Please verify:tanuj"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="verification:We need a verification"

Attachments

The WorkItemCommandline allows to upload attachments to work items. The syntax is

attachFileIDString{<uniqueID>}=”<pathToFile>:<description>:<contentTypeID>:<encodingID>”

Where the <uniqueID> is optional, but must be unique if multiple attachment uploads are specified, the <pathToFile> needs to exist  and be accessible, the description is some string.

The values for <contentTypeID> and <encodingID> need to match the file.

Supported values for <contentTypeID> are:

  • text/plain
  • application/unknown
  • application/xml

Supported values for <encodingID> are:

  • UTF-8
  • UTF-16LE
  • UTF-16BE
  • us-ascii

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 attachFile="./Test.txt:Some Description:text/plain:UTF-8" attachFile_1="./LintResult.txt:Lint result:text/plain:UTF-8"

Subscriptions

WCL allows to add subscribers to work items. The syntax is:

internalSubscriptions=<userID1>{,<userID>}

To remove subscribers use the pseudo attribute unsubscribe. The syntax is the same as when subscribing:

unsubscribe=<userID1>{,<userID>}

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph internalSubscriptions=al,ralph,deb unsubscribe=myadmin

Tags

WCL allows to set tags in the built in tag attribute as well as for custom attributes of the type tag. The syntax is:

<parameter>=<Tag>{,<Tag>}

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalTags="test1,test2" custom.tags="MyTag"

Duration Types

In duration types provide the value in milliseconds. For example

custom.duration=1800000

Timestamps

Timestamps need to be provided as string in the SimpleDateFormat using the format pattern “yyyy/MM/dd hh:mm:ss z”. For example:

custom.timestamp="2014/12/31 12:30:00 GMT+01:00"

Summary

This WorkItemCommandLine should allow for most of the automation needs when creating work items. In addition it is a nice resource for the RTC work Item API. If my schedule allows, I will enhance it to support the missing types and potentially some export and import options.

In later posts I will explain the code for users that are interested in adding their own implementation.

As always, I hope the post 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.

Posted in Jazz, RTC, RTC Automation | Tagged , , , , , , , , , , , | 7 Comments

Creating Custom Link Types for Rational Team Concert


It can be useful to be able to create custom link types for RTC. This is Interesting if a special business logic/behavior needs to be implemented and the available link types don’t fit. How can this be done?

It is surprisingly easy to do as Eduardo describes in Creating a New Link Type in his blog Extending Rational Team Concert – RTC Extending. I had to do it recently and thought it would be useful to describe the experience, adding a bit more detail to the content of the blog above.

License and Getting Started

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!

As always, please note, If you just get started with extending Rational Team Concert, or create API based automation, start reading this and the linked posts to get some guidance on how to set up your environment. Then I would suggest to read the article Extending Rational Team Concert 3.x and follow the Rational Team Concert 4.0 Extensions Workshop at least through the setup and Lab 1. This provides you with a development environment and with a lot of example code and information that is essential to get started. You should be able to use the following code in this environment and get your own extension working.

You can download the code for this extension here.

Creating a Custom Link Type

All that needs to be done to create a custom link type is to create a plug-in.

Oh, no! Another Extension! Can’t I just define a new link type in the process configuration? I can literally hear it 8). Unfortunately that is not supported in RTC today. Vote for this work item if you want this kind of capability.

On the other hand, if there is really a need for business logic and operational behavior for the link type, an extension would be needed and it would not matter.

To make the new link type available in the Eclipse UI as well as in the Web UI, the plug-in needs to be deployed in the client as well as in the server. The RTC SDK calls this common API and it makes sense to follow this example.

As explained in other posts already it is crucial to come up with a good naming schema for the various projects and ID’s needed. Have a unique part in it (in my case js as infix) to be able to find it on disk and in the UI.

When creating the link type an ID for the link is needed as well as ID’s for the endpoints of the link. It is crucial to keep these values once they are chosen. If you change them while developing, you would otherwise introduce dangling references into your test model. I managed to damage my test database and got unreliable results when doing this. If this happens, it is possible to delete the folder server that sits in the same folder as the workspace and create a new test repository running the [RTCExt] Create RTC Test Database JUnit test as described in the Extensions Workshop.

This is the extensions editor for the plug-in I created:

Link Type Common Plugin

Link Type Common Plugin

Different to the aforementioned blog post, the plugin defines a component as well as the link type. The reason is that the component allows to see if the plugin was successfully deployed in the server. At some time in the future a component might become required as well. So I always define a component for my extensions.

You can use the context menu of the editor to add the the extension elements for the source, target, endpoints and the itemReferenceTypes.

The endpoints allow to specify the multiplicity. This has actually an impact on how the links behave. If an endpoint specifies 0..1 as multiplicity, only one item can be referenced with the endpoint. If an item is selected already and another item is chosen in the add link dialog, the old item is replaced by the new one.

The plugin.xml looks as follows

Final plugin.xml

Final plugin.xml

The implication of the values in the plugin.xml can be found in the extension point description that can be opened from the extension point itself. Review it to understand the options. From that description:

  • id – String id for the link type.
  • editors – Semicolon separated string of ids of those components permitted to create and delete links of this type. For example, the string “com.ibm.team.repository;com.ibm.team.scm” specifies the two components “com.ibm.team.repository” and “com.ibm.team.scm”. If the attribute is not present, this indicates that there is no restriction regarding which components (or client) is permitted to create and delete links of this type.
  • constrained – If true, the defining component requests that Links of this link type not be created by other components (without permission, or without going through an API provided by the defining component).
  • internal – If true, this link type is an internal detail of the implementation of the defining component, and is not intended as a generic link type which users can freely create, delete and view.
  • componentId – The id of the component defining this link type. Component ids are declared using the com.ibm.team.repository.common.components extension point. If set and if constrained=true, then only services that are part of that component may save and delete links of this type.

The itemReferenceType entry is still a bit mysterious. It is easy to review existing examples. On the com.ibm.team.repository.common.linktype extension select “Show References” in the context menu and browse through the examples. Especially the references in com.ibm.team.workitem.common are of interest. It is possible to define different kinds of endpoints, dependent on what items to link.

In this case work items are supposed to be linked to work items. Both ends select this itemReferenceType. Please be aware that this kind of links will only work within one CCM repository. It will not allow to link across repository borders. The are other CLM link types that would allow this to happen.

I added some icons for the link types that show up in the editors. For the final deployment, I made sure that the folders icons and META-INF as well as the plugin.xml file are selected in the binary build.

I tested the new link type in a Jetty based test server OSGI2 launch as well as in an Eclipse2 Application launch.

Prepare to Deploy

As already mentioned the common plugin needs to be deployed in the server as well as in the Eclipse client. Please follow Lab 6 in the Rational Team Concert 4.0 Extensions Workshop if you have never done this and want to understand how deployment works in general. The workshop explains in great detail which files you need to deploy on the server. The procedure below follows the deployment procedure on the server side. Other than in the workshop the client extension gets deployed using an update site.

To make this easier I created a Feature project as well as an Update Site project. To make deploying it in the server easier I also created a normal Eclipse project that contains the deployment folder structure as well as the provision profile INI file. The projects look as follows:

Final Project Structure

Final Project Structure

Once the Update Site project is built, It is easy to copy the site.xml file and the folders  features and plugins into the folder js_custom_linktype in this project.The folders and contained files in this project can then used to easily deploy the extension on the server using copy paste. It is easy to do, reliable and repeatable.

The provision profile js_custom_linktype.ini looks as follows:

url=file:ccm/sites/js_custom_linktype
featureid=com.ibm.team.js.workitem.custom.linktype.feature

It references the sub folder in the site folder that will contain the feature and plugins folders, once it is copied over to the server for deploying.

TIP: Always delete all content of the Update Site project except the site.xml before building the update site again. I have seen cases where subsequent builds did not successfully pick up all changes.

Deploy in the Eclipse client

To deploy in the Eclipse client, use the Help>Install New Software menu, add the Update Site (browsing to the folder that represents the Update Site project) and install the extension. You can package the Update Site or provide it in a web server in a company context as well.

Deploy in the Server

Copy the generated folders and the site.xml file into the folder underneath the sites folder which is referenced by the provision profile js_custom_linktype.ini file in the  serverdeploy project folder. This would be easy to automate with a build script by the way.

Now select the folders provision_profies and site with all the content and copy the into the servers folder /server/conf/ccm. Allow to overwrite the folders and request a server reset. Then restart the server.

Add the New Link Type to the Quick Information Presentation

As Sam suggests in his comment below, you also want to add the new link type so that it shows in the quick Information presentation. This is done in the Process Configuration>Project configuration>Configuration Data>Workitems>Quick Information Presentations. It allows the workitem summary page Quick Information section to show a count of and quick link to the new link in a workitem This would look like below:

Quick Information Presentation

Quick Information Presentation

Admire your work

You can now admire the result of your work in the work item editors. If not, check your deployment setup. As usually the first attempt was, of course, on a test server to not affect the production system until you have perfected your deployment process.

 Too many Link Types! What to do?

If you have created all the new link types your business demanded, users might start to complain that there are too many link types and many are not needed anyways. You knew that would be coming and decided long ago to review the article Customization of work item editor presentation to show or hide link types in Rational Team Concert. to understand how to fix this issue once needed.

Summary
That was easy, wasn’t it? Now you can create behavior based on the link type.

I have tested it against a test server on Tomcat and Derby. There is no real code this time. However, as always, I hope the post 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.

Posted in CLM, Jazz, RTC, RTC Automation, RTC Extensibility | Tagged , , , | 5 Comments