Subscribing To a Work Item Using the Java API


Another thing I have been asked for several times and that is asked in the Jazz Forum right now is how to use the API to subscribe to a work item. Lets look at it, it is really easy.

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.

Solution Overview

The example in this blog shows RTC Client and Common API. If you are not sure what this means, please read this and the additional blog posts mentioned in this article. Code in the server would be very similar, except that the Client Library would be replaced by a service. See the Server side code at the end of the post.

For more details on the API, suggested readings and if you want to update a work item, see the last post on uploading attachments to work items. The code below is used to create a work item and subscribe users.

private static class CreateAndSubscribeWorkItem extends WorkItemOperation {

	private String fSummary;
	private ICategoryHandle fCategory;
	private ITeamRepository fTeamRepository;
	private String fContributorUserID;

	public CreateAndSubscribeWorkItem (String summary, ICategoryHandle category, 
			ITeamRepository teamRepository, String contributorUserID) {
		super("Initializing Work Item");
		fSummary = summary;
		fCategory = category;
		fTeamRepository=teamRepository;
		fContributorUserID=contributorUserID;
	}

	@Override
	protected void execute(WorkItemWorkingCopy workingCopy,	IProgressMonitor monitor) throws TeamRepositoryException {
		IWorkItem workItem = workingCopy.getWorkItem();
		workItem.setHTMLSummary(XMLString.createFromPlainText(fSummary));
		workItem.setCategory(fCategory);

		IContributor aUser = fTeamRepository.contributorManager().fetchContributorByUserId(fContributorUserID, null);
		IContributor loggedIn = fTeamRepository.loggedInContributor();
		ISubscriptions subscriptions = workItem.getSubscriptions();
		subscriptions.add(aUser);
		subscriptions.add(loggedIn);
	}
}

The operation can be called like below. The example is again based on the wiki entry on Programmatic Work Item Creation where the missing details can be found.

	CreateAndSubscribeWorkItem operation = new CreateAndSubscribeWorkItem(summary,category, teamRepository, approverUserID);
	IWorkItemHandle handle = operation.run(workItemType, null);

The core part is shown below. First a contributor is searched using the ContributorManager and the contributor ID. The next statement gets the user that is currently logged in – running the java class. The code then retrieves the subscription list and adds both users to it. Saving (or updating) is done for us by the operation.

	IContributor aUser = fTeamRepository.contributorManager().fetchContributorByUserId(fContributorUserID, null);
	IContributor loggedIn = fTeamRepository.loggedInContributor();
	ISubscriptions subscriptions = workItem.getSubscriptions();
	subscriptions.add(aUser);
	subscriptions.add(loggedIn);

Server Code

The code above is client code and only runs in the client. However, the code to get the subscription and to add (or remove) users is common API that would run on the client and on the server. So to make this work on the server see RTC Update Parent Duration Estimation and Effort Participant for how to save a work item in the server.

In addition, the client library call to get the user would be replaced by using a service as presented below, assuming your class extends AbstractService and thus has access to the getService() method.

	IContributorService contributorService = getService(IContributorService.class);
	IContributorHandle approver = contributorService.fetchContributorByUserId(approverId);

8 thoughts on “Subscribing To a Work Item Using the Java API

  1. Hello Ralph,
    I am doing the same operation in my server participant plug in

    ISubscriptions subscriptions = workItem.getSubscriptions();
    subscriptions.add(IContributor or IContributorHandle object);

    But this is not adding the subscribers to the work item
    Do I need to save the work item with this subscription as additional save parameters?
    Thanks for the help!

    • I believe that the code in this blog post worked for me. Obviously the code only works in a WorkItemOperation where the workitem working copy actually gets saved. The code

      ISubscriptions subscriptions = workItem.getSubscriptions();
      subscriptions.add(IContributor or IContributorHandle object);

      alone, does nothing. The work item needs to be saved however – hence i wrapped it in a WorkItemOperation. If there would be the need to add an additional save parameter, i would have mentioned that.

      How an WorkItemOperation works is explained in ine of my API over view blogs and in https://jazz.net/wiki/bin/view/Main/ProgrammaticWorkItemCreation as mentioned in the blog.

    • Last thought, an additional save parameter might be necessary to prevent a recursion in case you do this in a work item save participant. I suggested the necessary reading in the section ‘Server Code’. this blog also explains the server side API to save a work item.

      I had assumed in my initial response, that you had already followed the suggestions.

      • Hello Ralph,

        Thanks for the information,
        My problem was the way how i was getting the work item copy i think
        earlier i took like this,
        IWorkItem workCopy = workItemServer.findWorkItemById(workItem.getId(), IWorkItem.FULL_PROFILE, monitor);

        now i tried this
        IWorkItem workCopy = (IWorkItem)workItemServer.findWorkItemById(workItem.getId(), IWorkItem.FULL_PROFILE, monitor).getWorkingCopy();

        and did the subscribers addition
        ISubscriptions subscriptions = workItem.getSubscriptions();
        subscriptions.add(IContributor object);

        then saved the copy work item.
        now i am able to save the subscriptions.

        Also, Meanwhile in another approach i considered Subscription as a custom attribute and used
        workItem.setValue(SubcriberAttribute, List object)
        This also worked for me 🙂

        Thanks for the help

      • The code

        Thanks for the information,
        My problem was the way how i was getting the work item copy i think
        earlier i took like this,
        IWorkItem workCopy = workItemServer.findWorkItemById(workItem.getId(), IWorkItem.FULL_PROFILE, monitor);

        Does not get the WorkingCopy. It only gets the work item. You can not modify that.

        You have to perform the .getWorkingCopy(); to get the working copy that you can change and save.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.