Adding Approvals to Work Items Using the Plain Java Client Libraries

Another question I have seen various times already is how to add approvals to work items using the Java API. Let’s look at it, it is not that hard to do.

*UPDATE* See the library article Creating, customizing, and deleting approval records programmatically with Rational Team Concert for additional code examples around approvals.

*UPDATE* See A RTC WorkItem Command Line Version 2.2 for much more API code.

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

As always, our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license, which basically means you can use it for internal usage, but not sell. Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee. Enjoy!

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

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

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

Download

*UPDATE*

The code can be downloaded here.

Solution Overview

The code below shows the WorkItemOperation that creates (or would modify) the work item. The operation does all the complicated steps for us, such as getting a WorkItemWorkingCopy and saving later.

/**
 * Add an approval to a work item
 *
 */
private static class WorkItemCreateApproval extends WorkItemOperation {
	private String fContributorUserID;
	private String fApprovalName;

	public WorkItemCreateApproval(String contributorUserID, String approvalName) {
		super("Add Approval",IWorkItem.FULL_PROFILE);
		fContributorUserID=contributorUserID;
		fApprovalName=approvalName;
	}

	@Override
	protected void execute(WorkItemWorkingCopy workingCopy,
		ProgressMonitor monitor) throws TeamRepositoryException {
		// Get the work item to get the team repository.
		IWorkItem workItem = workingCopy.getWorkItem();
		ITeamRepository repo = (ITeamRepository)workItem.getOrigin();
		// Find a contributor based on the ID
		IContributor aUser = repo.contributorManager().fetchContributorByUserId(fContributorUserID, null);
		// Find a contributor based on the login information
		IContributor loggedIn = repo.loggedInContributor();
		ArrayList reviewers = new ArrayList();
		reviewers.add(loggedIn);
		reviewers.add(aUser);

		// Create a new approval and add the approvers
		IApprovals approvals= workItem.getApprovals();
		IApprovalDescriptor descriptor= approvals.createDescriptor(WorkItemApprovals.REVIEW_TYPE.getIdentifier(), fApprovalName);
		for (IContributorHandle reviewer: reviewers) {
			IApproval approval= approvals.createApproval(descriptor, reviewer);
			approvals.add(approval);
		}
	}
}

What the code does is basically, given a WorkItemWorkigCopy, to get the team repository and use it to get the IContributorManager and use it to find a user based on a user ID. It then gets the logged in user as well. Both IContributor objects are stored for later use.

The next step is to create a new approval descriptor in the approvals of the work item. For each user a new approval for the approval descriptor is created and the new approvals are added to the approval list.

The operation is called using this code:

WorkItemCreateApproval operation = new WorkItemCreateApproval(approverUserID, approvelName);
operation.run(workItemHandle, null);

As always, to keep it simple, there is few error handling. You might want to enhance this for later usage.